Distributing Apps

Last Updated: September 29, 2016

Once your app is complete, you will likely want to distribute it for others to use or at the very least install it in a production Tethys Platform environment. When you share your app with others, you will share the entire release package, which is the outermost directory of your app project. For these tutorials, your release package is called “tethysapp-my_first_app”.

The release package contains the source code for your app and a setup script (setup.py). You may also wish to include a README file and a LICENSE file in this directory. The setup script can be used to streamline installation of your app and any Python dependencies it may have. You already used the setup script without realizing it in the Create a New Tethys App Project tutorial when you installed your app for the first time (this command: python setup.py develop). A brief introduction to the setup script will be provided in this tutorial.

Setup Script

When you generate your app using the scaffold, it will automatically generate a setup script (setup.py). Open the setup script for your app located at ~/tethysdev/tethysapp-my_first_app/setup.py. It should look something like this:

import os
import sys
from setuptools import setup, find_packages
from tethys_apps.app_installation import custom_develop_command, custom_install_command

### Apps Definition ###
app_package = 'my_first_app'
release_package = 'tethysapp-' + app_package
app_class = 'my_first_app.app:MyFirstApp'
app_package_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'tethysapp', app_package)

### Python Dependencies ###
dependencies = []

setup(
    name=release_package,
    version='0.0',
    tags='',
    description='',
    long_description='',
    keywords='',
    author='',
    author_email='',
    url='',
    license='',
    packages=find_packages(exclude=['ez_setup', 'examples', 'tests']),
    namespace_packages=['tethysapp', 'tethysapp.' + app_package],
    include_package_data=True,
    zip_safe=False,
    install_requires=dependencies,
    cmdclass={
        'install': custom_install_command(app_package, app_package_dir, dependencies),
        'develop': custom_develop_command(app_package, app_package_dir, dependencies)
    }
)

As a general rule, you should never modify the parameters under the “Apps Definition” heading. These parameters are used by the setup script to find the source code for your app and changing their values could result in your app not working properly. If you use Python libraries that are external to your app or Tethys Platform, you will need add the library name to the dependencies list in the setup script. These libraries will automatically be installed when your app is installed.

The final part of the setup script makes a call to the setup() function that is provided by the setuptools library. You will see the metadata that you defined during the scaffold process listed here. As you release subsequent versions of your app, you may wish to increment the version parameter of this function.

Setup Script Installation

The setup script is used to install your app and there are two types of installation that can be performed: install and develop. The install type of installation hard copies the source code of your app into the site-packages directory of your Python installation. The site-packages directory is where Python keeps all of the code for external modules and libraries that have been installed.

This is the type of installation you would use for a completed app that is being installed in a production environment. To perform this type of installation, open a terminal, change into the release package directory of your app, and run the install command on the setup script as follows:

cd ~/tethysdev/tethysapp-my_first_app
python setup.py install

The install type of installation is not well suited for working with your app during development, because you would need to reinstall it (i.e.: run the commands above) every time you made a change to the app source code. This is why the develop type of installation exists. When an app is installed with the develop command, the source code for your app is only linked to the site-packages directory. This allows you to change your code and test the changes without reinstalling the app.

You already performed this type of installation on your app during the Create a New Tethys App Project tutorial. To perform this type of installation, open a terminal, change into the release package directory, and run the develop command on the setup script like so:

cd ~/tethysdev/tethysapp-my_first_app
python setup.py develop

Tip

For more information about setuptools and the setup script, see the Setuptools Documentation.