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.
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 (
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.
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.
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
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
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
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.
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.