How to include a package entry point to run a dash app from the command line?

Hi,

This post follows a this previous question.

The aim is to describe a minimal working example of a python package that includes a Dash application and includes a command line to run the application. This command line is automatically created by using an entry point defined from the configuration file of setup tools. The command line is put in your PATH at the package installation and can be use from anywhere.

The dash application is available in the following repository and the README gives lots of details (I hope). There are two branches, the min branch is … minimal, trying to use only one file for the application and the main branch provides exactly the same application but in a more structured repository:

The structure of the package is general enough to cover the following use cases:

  • deployment on a web service (such as heroku) live demo here
  • run the application locally after cloning the repository using git
  • install the package from a package manager or a GUI and run it using a command line
  • provide a environment.yml file that can be used to install the application

I will describe here several key points. You have to keep in mind that it concerns a package that will be installed in your python environment.

MANIFEST file

The MANIFEST.in file is crucial to be sure that files which are not python source code files will be installed in your python environment. In the particular case of the dash application, it is important for css files and for example pictures or data you want to include in the application. These files must be listed in the MANIFEST.in file. The check-manifest project may help to write this file without forgiven any file.

At the end the files are copied in envs/dashmwe/lib/python3.9/site-packages/nba_stat_app.

Entry point

In order to automatically implement during the package installation a command line that runs the application we will use the entry_points options of the setuptools. You first have to write a function that runs the application. In this repository, this function is in the run_app.py file. It uses the webbrowser module, from the python standard library to open the default browser and reach the url of the running dash application. You can personalize the port and url.

This function (here the main() function in run_app.py) will be the one called by the command line. Moreover, python needs to be able to import this function, so the module file must be installed in the environment.

import webbrowser
from threading import Timer
from nba_stat_app.app import app

def main():
    """ Run the app from an entry point defined in setup.cfg
    TODO: need to check port is available
    """

    # set up the url and a threading Timer
    host = "localhost"
    port = 8080
    folder = "dash-nba"
    url = f"http://{host}:{port}/{folder}/"
    Timer(10, webbrowser.open_new(url))

    # run app
    app.run(host=host, port=port, debug=False)

Then, you have to define the entry point in the setup.cfg file as follow:

[options.entry_points]
console_scripts=
    run_app = nba_stat_app.run_app:main

Here, run_app will be the name of the command line implemented by setuptools. You can defined it as you whish. You may see that we look for the run_app module as a submodule of the nba_stat_app and then we call the main() function of this module.

In this present case, the run_app command is implemented and you can use the application from the command line as follow:

(base) $> conda activate my_env
(my_env) $> run_app

Thank you in advance for any feedback !

2 Likes