App Project Structure

Last Updated: November 17, 2014

The source code for a Tethys app project is organized in a specific file structure. Figure 1 illustrates the key components of a Tethys app project called "my_first_app". The top level package is called the release package and it contains the app package for the app and other files that are needed to distribute the app. The key components of the release package and the app package will be explained in this article.

diagram of a Tethys app project for an app named my_first_app

Figure 1. An example of a Tethys app project for an app named "my_first_app".

Release Package

As the name suggests, the release package is the package that you will use to release and develop your app. The entire release package should be provided when you share your app with others.

The name of a release package follows a specific naming convention.The name of the directory should always start with "tethysapp-" followed by a unique name for the app. The name of the app may not have spaces, dashes, or other special characters (however, underscores are allowed). For example, Figure 1 shows the project structure for an app with name "my_first_app" and the name of the release package is "tethysapp-my_first_app".

The release package must contain a setup script (setup.py) and tethysapp namespace package at a minimum. This directory would also be a good place to put any accessory files for the app such as a README file or LICENSE file. No code that is required by the app to run should be in this directory.

The setup script to install your app and its dependencies. A basic setup script is generated as part of the scaffolding for a new app project. For more information on writing setup scripts refer to this article: Writing the Setup Script.

The tethysapp package is a Python namespace package. It provides a way to mimic the production environment during development of the app (i.e.: when the app is installed, it will reside in a namespace package called tethysapp). This package contains the app package, which has the same name as your app name by convention.

Caution

When you generate a new app project using the command line tool, you will notice that many of the directories contain a __init__.py file, many of which are empty. These are omitted in the diagram for simplicity. DO NOT DELETE THE __init__.py FILES. These files indicate to Python that the directories containing them are Python packages. Your app will not work properly without the __init__.py files.

The App Package

The app package contains all of the source code and resources that are needed by the Tethys Platform to run your app. The model.py, templates, and controllers.py modules and directories correspond with the Model View Controller approach that is used to build apps.

The data structures, classes, and methods that are used to define the data model model.py module. The templates directory contains all the Django HTML templates that are used to generate the views of the app. The controllers.py module contains Python files for each controller of the app. The public directory is used for static resources such as images, JavaScript and CSS files. The app.py file contains all the configuration parameters for the app.

To learn how to work with the files in the app package, see the Key Concepts tutorial.

Naming Conventions

There are a few naming conventions that need to be followed to avoid conflicts with other apps. The more obvious one is the app package name. Like all Python modules, app package names must be unique.

All templates should be contained in a directory that shares the same name as the app package within the templates directory (see Figure 1). This ensures that when your app calls for a template like home.html it finds the correct one and not an home.html from another app.