Migrating Apps from Tethys 2 to 3
Porting your App to Python 3.6+
Porting Python 2 apps to Python 3 can be done in a systematic way, and is usually less complicated than expected. We recommend using the 2to3 Python program to translate your Python 2 apps into Python 3 automatically.
New Tethys App Installation
Tethys 3 facilitates app installation by providing a new install
command. This command replaces the previous
Python setup.py <install/develop>. Some of the main changes to the app installation process are updates to the
directory structure of the app, the setup.py
file, and the addition of new functionality to facilitate the
installation and setup of apps including app service configuration using a predefined custim yml file or an interactive
mode.
Tethys apps are now python package that are installed in the tethys conda environment and can be imported as shown below:
# imports test_app
from tethysapp import test_app
Init.py
The __init__.py
files in the file structure of old tethys apps need to be slightly modified to work with the new
install
command.

Figure 1. An example of a Tethys app project for an app named "my_first_app".
The __init__.py
from the Project
and the tethysapp
directories need to be deleted.
The __init__.py
from the App Package
directory needs to be empty.
For example:
Remove the following contents from tethysapp-my_first_app/tethysapp/my_first_app/__init__.py
:
# this is a namespace package
try:
import pkg_resources
pkg_resources.declare_namespace(__name__)
except ImportError:
import pkgutil
__path__ = pkgutil.extend_path(__path__, __name__)
Setup.py
The setup.py file has been simplified. In addition, the find_packages
function has been replaced with the
find_namespace_packages
. A new function find_resource_files
is used to carry additional package data such as
templates along with the setup installation.
Example of new setup.py
file:
from setuptools import setup, find_namespace_packages
from tethys_apps.app_installation import find_resource_files
# -- Apps Definition -- #
app_package = 'test_app'
release_package = 'tethysapp-' + app_package
# -- Python Dependencies -- #
dependencies = []
# -- Get Resource File -- #
resource_files = find_resource_files('tethysapp/' + app_package + '/templates', 'tethysapp/' + app_package)
resource_files += find_resource_files('tethysapp/' + app_package + '/public', 'tethysapp/' + app_package)
setup(
name=release_package,
version='0.0.1',
description='',
long_description='',
keywords='',
author='',
author_email='',
url='',
license='',
packages=find_namespace_packages(),
package_data={'': resource_files},
include_package_data=True,
zip_safe=False,
install_requires=dependencies,
)
Note
Do not list app dependencies in the setup.py
. Dependencies should now be listed using the install.yml
file
(see Application Installation).
App Base Template
If you'd like your app to support setting the app icon to use an image from an external source (e.g. "http://example.com/example.jpg"), you'll need to update the base.html located in your templates directory. Either remove the app_icon block or change it to:
{% block app_icon %}
{# The path you provided in your app.py is accessible through the tethys_app.icon context variable #}
<img src="{% if 'http' in tethys_app.icon %}{{ tethys_app.icon }}{% else %}{% static tethys_app.icon %}{% endif %}" />
{% endblock %}
App Installation
Tethys apps are now installed using the install
command. See Application Installation for an example of
how to use the install
command, how to use yml
files in combination with the install
command, and a list of
available parameters.
# Install Tethys App
tethys install
# Install Tethys App with develop
tethys install -d
# Skip interactive mode
tethys install -q
# Tethys install with custom options
tethys install -d -f install.yml
Presentation
Use this presentation in workshops and training courses to provide an overview of the app migration process: Migrate Apps from Tethys 2 to Tethys 3 Presentation.