App Base Class API¶

Last Updated: May 11, 2016

Tethys apps are configured via the app class, which is contained in the app configuration file (app.py) of the app project. The app class must inherit from the TethysAppBase class to be loaded properly into CKAN. The following article contains the API documentation for the TethysAppBase class.

class tethys_apps.base.app_base.TethysAppBase¶

Base class used to define the app class for Tethys apps.

name¶

string

Name of the app.

index¶

string

Lookup term for the index URL of the app.

icon¶

string

Location of the image to use for the app icon.

package¶

string

Name of the app package.

root_url¶

string

Root URL of the app.

color¶

string

App theme color as RGB hexadecimal.

description¶

string

Description of the app.

tag [string]: A string for filtering apps.

enable_feedback¶

boolean

Shows feedback button on all app pages.

feedback_emails¶

list

A list of emails corresponding to where submitted feedback forms are sent.

classmethod create_persistent_store(persistent_store_name, spatial=False)¶

Creates a new persistent store database for this app.

Parameters:	persistent_store_name (string) – Name of the persistent store that will be created. spatial (bool) – Enable spatial extension on the database being created.
Returns:	True if successful.
Return type:	bool

Example:

from .app import MyFirstApp

result = MyFirstApp.create_persistent_store('example_db')

if result:
    engine = MyFirstApp.get_persistent_store_engine('example_db')

classmethod destroy_persistent_store(persistent_store_name)¶

Destroys (drops) a persistent store database from this app.

Parameters:	persistent_store_name (string) – Name of the persistent store that will be created.
Returns:	True if successful.
Return type:	bool

Example:

from .app import MyFirstApp

result = MyFirstApp.destroy_persistent_store('example_db')

if result:
    # App database 'example_db' was successfuly destroyed and no longer exists
    pass

classmethod get_app_workspace()¶

Get the file workspace (directory) for the app.

Returns:	An object representing the workspace.
Return type:	tethys_apps.base.TethysWorkspace

Example:

import os
from .app import MyFirstApp

def a_controller(request):
    """
    Example controller that uses get_app_workspace() method.
    """
    # Retrieve the workspace
    app_workspace = MyFirstApp.get_app_workspace()
    new_file_path = os.path.join(app_workspace.path, 'new_file.txt')

    with open(new_file_path, 'w') as a_file:
        a_file.write('...')

    context = {}

    return render(request, 'my_first_app/template.html', context)

classmethod get_handoff_manager()¶: Get the handoff manager for the app.

classmethod get_job_manager()¶: Get the job manager for the app

classmethod get_persistent_store_engine(persistent_store_name)¶

Creates an SQLAlchemy engine object for the app and persistent store given.

Parameters:	persistent_store_name (string) – Name of the persistent store for which to retrieve the engine.
Returns:	An SQLAlchemy engine object for the persistent store requested.
Return type:	object

Example:

from .app import MyFirstApp

engine = MyFirstApp.get_persistent_store_engine('example_db')

classmethod get_user_workspace(user)¶

Get the file workspace (directory) for a user.

Parameters:	user (User or HttpRequest) – User or request object.
Returns:	An object representing the workspace.
Return type:	tethys_apps.base.TethysWorkspace

Example:

import os
from .app import MyFirstApp

def a_controller(request):
    """
    Example controller that uses get_user_workspace() method.
    """
    # Retrieve the workspace
    user_workspace = MyFirstApp.get_user_workspace(request.user)
    new_file_path = os.path.join(user_workspace.path, 'new_file.txt')

    with open(new_file_path, 'w') as a_file:
        a_file.write('...')

    context = {}

    return render(request, 'my_first_app/template.html', context)

handoff_handlers()¶

Use this method to define handoff handlers for use in your app.

Returns:	A list or tuple of `HandoffHandler` objects.
Return type:	iterable

Example:

from tethys_sdk.handoff import HandoffHandler

def handoff_handlers(self):
    """
    Example handoff_handlers method.
    """
    handoff_handlers = (HandoffHandlers(name='example',
                                        handler='my_first_app.controllers.my_handler'),
    )

    return handoff_handlers

job_templates()¶

Use this method to define job templates to easily create and submit jobs in your app.

Returns:	A list or tuple of `JobTemplate` objects.
Return type:	iterable

Example:

from tethys_sdk.jobs import CondorJobTemplate
from tethys_sdk.compute import list_schedulers

def job_templates(cls):
    """
    Example job_templates method.
    """
    my_scheduler = list_schedulers()[0]

    job_templates = (CondorJobTemplate(name='example',
                                       parameters={'executable': '$(APP_WORKSPACE)/example_exe.py',
                                                   'condorpy_template_name': 'vanilla_transfer_files',
                                                   'attributes': {'transfer_input_files': ('../input_1.in', '../input_2.in'),
                                                                  'transfer_output_files': ('example_output1.out', 'example_output2.out'),
                                                                 },
                                                   'scheduler': my_scheduler,
                                                   'remote_input_files': ('$(APP_WORKSPACE)/example_exe.py', '$(APP_WORKSPACE)/input_1.in', '$(USER_WORKSPACE)/input_2.in'),
                                                  }
                                      ),
                    )

    return job_templates

classmethod list_persistent_stores()¶

Returns a list of existing persistent stores for this app.

Returns:	A list of persistent store names.
Return type:	list

Example:

from .app import MyFirstApp

persistent_stores = MyFirstApp.list_persistent_stores()

permissions()¶

Use this method to define permissions for your app.

Returns:	A list or tuple of `Permission` or `PermissionGroup` objects.
Return type:	iterable

Example:

from tethys_sdk.permissions import Permission, PermissionGroup

def permissions(self):
    """
    Example permissions method.
    """
    # Viewer Permissions
    view_map = Permission(
        name='view_map',
        description='View map'
    )

    delete_projects = Permission(
        name='delete_projects',
        description='Delete projects'
    )

    create_projects = Permission(
        name='create_projects',
        description='Create projects'
    )

    admin = PermissionGroup(
        name='admin',
        permissions=(delete_projects, create_projects)
    )


    permissions = (admin, view_map)

    return permissions

classmethod persistent_store_exists(persistent_store_name)¶

Returns True if a persistent store with the given name exists for this app.

Parameters:	persistent_store_name (string) – Name of the persistent store that will be created.
Returns:	True if persistent store exists.
Return type:	bool

Example:

from .app import MyFirstApp

result = MyFirstApp.persistent_store_exists('example_db')

if result:
    engine = MyFirstApp.get_persistent_store_engine('example_db')

persistent_stores()¶

Define this method to register persistent store databases for your app. You may define up to 5 persistent stores for an app.

Returns:	A list or tuple of `PersistentStore` objects. A persistent store database will be created for each object returned.
Return type:	iterable

Example:

from tethys_sdk.stores import PersistentStore

def persistent_stores(self):
    """
    Example persistent_stores method.
    """

    stores = (PersistentStore(name='example_db',
                              initializer='init_stores:init_example_db',
                              spatial=True
            ),
    )

    return stores

url_maps()¶

Use this method to define the URL Maps for your app. Your UrlMap objects must be created from a UrlMap class that is bound to the root_url of your app. Use the url_map_maker() function to create the bound UrlMap class. If you generate your app project from the scaffold, this will be done automatically.

Returns:	A list or tuple of `UrlMap` objects.
Return type:	iterable

Example:

from tethys_sdk.base import url_map_maker

def url_maps(self):
    """
    Example url_maps method.
    """
    # Create UrlMap class that is bound to the root url.
    UrlMap = url_map_maker(self.root_url)

    url_maps = (UrlMap(name='home',
                       url='my-first-app',
                       controller='my_first_app.controllers.home'
                       ),
    )

    return url_maps