Package: mljar-mercury
Share your Python notebook as web applicationMercury is a perfect tool to convert Python notebook to interactive web application and share with non-programmers.You define interactive widgets for your notebook with the YAML header.Your users can change the widgets values, execute the notebook and save result (as PDF or html file).You can hide your code to not scare your (non-coding) collaborators.Easily deploy to any server.Mercury is dual-licensed. Looking for dedicated support, a commercial-friendly license, and more features? The Mercury Pro is for you. Please see the details at ourwebsite.Documentation📚Mercury documentation:books:InstallationCompatible with Python 3.7 and higher.Install withpip:pip install mljar-mercuryOr withconda:conda install -c conda-forge mljar-mercuryGetting startedDemo notebookTo start with demo notebook please run:mercury run demoIt will create for youdemo.ipynbnotebook and run it with Mercury. Please open127.0.0.1:8000to check the app running.Your notebookTo run Mercury with your notebook please execute:mercury watch my_notebook.ipynbThewatchcommand will monitor your notebook for changes and will automatically reload them in the Mercury web app.YAML ExampleNotebook with YAML configThe YAML config is added as the first raw cell in the notebook.Web Application from NotebookThe web app is generated from the notebook. Code is hidden (optional). User can change parameters, execute notebook with theRunbutton, and save results with theDownloadbutton.💻 DemoThe demos with several example notebooks are running at:http://mercury.mljar.com(running on AWS EC2 t3a.small instance)http://mercury-demo-1.herokuapp.com(running on Heroku, if dyno is sleeping and notebooks are not loaded, please refresh it and wait a little)https://sketch-app-mercury.herokuapp.com/- sketch app for converting photos to sketches withcodeInteractive slidesYou can easily do interactive slides from the notebook and serve them with Mercury. Please check thedocs. Below is example demo:🛠️ Convert Notebook to web app with YAMLYou need to add YAML at the beginning of the notebook to be able to run it as a web application in the Mercury. The YAML configuration should be added as aRawcell in the notebook. It should start and end with a line containing "---". Below examples of how it should look like in the Jupyter Notebook and Jupyter Lab:YAML configurationAllowed parameters in YAML config:title- string with a title of the notebook. It is used in the app sidebar and the gallery view.author- string with a author name (optional).description- string describing the content of the notebook. It is used in the gallery view.show-code- can beTrueorFalse. Default is set toTrue. It decides if the notebook's code will be displayed or not.show-prompt- can beTrueorFalse. Default is set toTrue. If set toTrueprompt information will be displayed for each cell in the notebook.share- the comma separated list of users that can see the notebook. Default is set topublicwhich means that all users can see the notebook. It can be set toprivatewhich means that only authenticated users can see the notebook. It can be set to the list of users, for exampleusername1, username2, username3, which means that only users with username on the list can see the notebook. The last option is list the groups of users that can see the notebook, for examplegroup1, group2- all users in thegroup1andgroup2will be able to see the notebook. You can mix group names and user names in theshareparameter. The users and groups should be created in the Admin Panel. The sharing feature is only available to commercial users.output- the type of the resulting notebook. It can beapporslides. The default is set toapp.params- the parameters that will be used in the notebook. They will be displayed as interactive widgets in the sidebar. Each parameter should have an unique name that corresponds to the variable name used in the code. Read more about available widgets inparamsin thedocumentation.Define widget with YAMLAvailable widgetsWidgets in Mercury aretext,slider,range,select,checkbox,numeric,file.Widget name is a variable nameDefinition of the widget (inparams) starts with the widget name. It will correspond to the variable in the code. The name should be a valid Python variable.Widget input typeTo define the widget you need to select the input type. It can be:text,slider,range,select,checkbox,numeric,file.Widget labelFor each input we need to define alabel. It will be a text displayed above (or near) the widget.Widgets documentation 🧰You can read more about widgets in ourdocumentation.Output filesYou can easily create files in your notebook and allow your users to download them.The example notebook:The first RAW cell.title:My appdescription:App with file downloadparams:output_dir:output:dirThe next cell should have a variable containing the directory name. The variable should be exactly the same as in YAML. This variable will have assigned a new directory name that will be created for your user during notebook execution. Please remember to define all variables that are interactive in Mercury in one cell, just after the YAML header (that's the only requirement to make it work, but is very important).output_dir="example_output_directory"In the next cells, just produce files to theoutput_dir:importoswithopen(os.path.join(output_dir,"my_file.txt"),"w")asfout:fout.write("This is a test")In the Mercury application, there will be additional menu in the top withOutput filesbutton. Please click there to see your files. Each file in the directory can be downloaded.Welcome messageThere is an option to set a custom welcome message. Like in the example screenshot below.The custom welcome message can be set as Markdown text (with GitHub flavour). To set custom message please create awelcome.mdfile and include your Markdown text there. When deploying please set theWELCOMEenvironment variable pointing to your file. For example, in Heroku it will beWELCOME=welcome.md. The example repository with welcome message ishere. The example demo showing a Data Science Portfolio ishere.If you don't set the welcome message a simpleWelcome!will be displayed. We belive that setting welcome message will give you a great opportunity for customization.Running locallyServe all notebooks (first option)To run Mercury with all notebooks in the current directory please just run:mercury runIt will serve Mercury website athttp://127.0.0.1:8000with all notebooks.You can change the default8000PORT when running themercury:mercury run 127.0.0.1:<your-port-here>Manually add notebooks (second option)To run Mercury locally just run:mercury runserver --runworkerThe above command will run server and worker (without any notebooks). It will serve Mercury website athttp://127.0.0.1:8000. It won't display any notebooks because we didn't add any. Please stop the Mercury server (and worker) for a moment with (Ctrl+C).Execute the following command to add a notebook to the Mercury database:mercury add <path_to_notebook>Please start the Mercury server to see your apps (created from notebooks).mercury runserver --runworkerNotebook development with automatic refreshThe Mercurywatchcommand is perfect when you create a new notebook and want to see what it will look like as a web app with live changes.Please run the following command:mercury watch <path_to_your_notebook>You can now open the web browser athttp://127.0.0.1:8000and find your notebook. When you change something in the notebook code, markdown, or YAML configuration and save the notebook, then it will be automatically refreshed in the web browser. You can track your changes without manual refreshing of the web app.Mercury commandsAddPlease useaddcommand to add a notebook to the Mercury. It needs a notebook paath as an argument.Example:mercury add notebook.ipynbDeletePlease usedeletecommand to remove notebook from the Mercury. It needs a notebook path as an argument.Example:mercury delete notebook.ipynbListPlease uselistcommand to display all notebooks in the Mercury.Example:mercury listRunning in productionRunning in production is easy. There are two ways it can be done:deploy withmercury runcommand,deploy withdocker-composePlease check ourdocumentationfor details.Running withdocker-composeThedocker-composemust be run from the Mercury main directory.Please copy.env.examplefile and name it.envfile. Please point theNOTEBOOKS_PATHto the directory with your notebooks. All notebooks from that path will be added to the Mercury before the server start. If therequirements.txtfile is available inNOTEBOOKS_PATHall packages from there will be installed.Please remember to change theDJANGO_SUPERUSER_USERNAMEandDJANGO_SUPERUSER_PASSWORD.To generate newSECRET_KEY(recommended), you can use:python -c 'from django.core.management.utils import get_random_secret_key; \
            print(get_random_secret_key())'Please leaveSERVE_STATIC=Falsebecause in thedocker-composeconfiguration static files are served with nginx.Thedocker-composewill automatically read environment variables from.envfile. To start the Mercury, please run:docker-compose up --buildTo run in detached mode (you can close the terminal) please run:docker-compose up --build -dTo stop the containers:docker-compose downMercury developmentThe Mercury project consists of three elements:Frontend is written in TypeScript with React+ReduxServer is written in Python with DjangoWorker is written in Python with CeleryEach element needs a separate terminal during development.FrontendThe user interface code is in thefrontenddirectory. Run all commands from there. Install dependencies:yarn installRun frontend:yarn startThe frontend is served athttp://localhost:3000.ServerThe server code is in themercurydirectory. Run all commands from there. Please set the virtual environment first:virtualenv menv
source menv/bin/activate
pip install -r requirements.txtApply migrations:python manage.py migrateRun the server in development mode (DEBUG=True):python manage.py runserverThe server is running athttp://127.0.0.1:8000.WorkerThe worker code is in themercurydirectory (in theapps/notebooks/tasks.pyandapps/tasks/tasks.pyfiles). Please activate first the virtual environment (it is using the same virtual environment as a server):source menv/bin/activateRun the worker:celery -A server worker --loglevel=info -P gevent --concurrency 1 -EMercury ProLooking for dedicated support, a commercial-friendly license, and more features? The Mercury Pro is for you. Please see the details atour website.