Table Of Contents

App Settings API¶

Last Updated: May 2017

The App Settings API allows developers to create settings for their apps that can be configured in the admin interface of the Tethys Portal in which the app is installed. Examples of what App Settings could be used for include enabling or disabling functionality, assigning constant values or assumptions that are used throughout the app, or customizing the look and feel of the app. App Settings are only be accessible by Tethys Portal administrators in production, so they should be thought of as global settings for the app that are not customizable on a user by user basis.

As of Tethys Platform 2.0.0, Tethys Services such as databases and map servers are configured through App Settings. Tethys Service App Settings can be thought of as sockets for a particular type of Tethys Service (e.g. PostGIS database, GeoServer, CKAN). Tethys Portal administrators can "plug-in" the appropriate type of Tethys Service from the pool of Tethys Services during installation and setup of the app in the portal. This slight paradigm shift gives Tethys Portal administrators more control over the resources they manage for a Portal instance and how they are distributed across the apps.

Custom Settings¶

Custom Settings are used to create scalar-valued settings for an app. Four basic types of values are supported including string, boolean, integer, and float. Create Custom Settings by implementing the custom_setting() method in your app class. This method should return a list of CustomSettings objects:

TethysAppBase.custom_settings()

Override this method to define custom settings for use in your app.

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

Example:

from tethys_sdk.app_settings import CustomSetting

class MyFirstApp(TethysAppBase):

    def custom_settings(self):
        """
        Example custom_settings method.
        """
        custom_settings = (
            CustomSetting(
                name='default_name',
                type=CustomSetting.TYPE_STRING
                description='Default model name.',
                required=True
            ),
            CustomSetting(
                name='max_count',
                type=CustomSetting.TYPE_INTEGER,
                description='Maximum allowed count in a method.',
                required=False
            ),
            CustomSetting(
                name='change_factor',
                type=CustomSetting.TYPE_FLOAT,
                description='Change factor that is applied to some process.',
                required=True
            ),
            CustomSetting(
                name='enable_feature',
                type=CustomSetting.TYPE_BOOLEAN,
                description='Enable this feature when True.',
                required=True
            )
        )

        return custom_settings

To retrieve the value of a Custom Setting, import your app class and call the get_custom_setting() class method:

classmethod TethysAppBase.get_custom_setting(name)

Retrieves the value of a CustomSetting for the app.

Parameters: name (str) -- The name of the CustomSetting as defined in the app.py.
Returns: Value of the CustomSetting or None if no value assigned.
Return type: variable

Example:

from my_first_app.app import MyFirstApp as app

max_count = app.get_custom_setting('max_count')

Persistent Store Settings¶

Persistent Store Settings are used to request databases and connections to database servers for use in your app (e.g. PostgreSQL, PostGIS). Create Persistent Store Settings by implementing the persistent_store_settings() method in your app class. This method should return a list of PersistentStoreConnectionSetting and PersistentStoreDatabaseSetting objects:

TethysAppBase.persistent_store_settings()

Override this method to define a persistent store service connections and databases for your app.

Returns: A list or tuple of PersistentStoreDatabaseSetting or PersistentStoreConnectionSetting objects.
Return type: iterable

Example:

from tethys_sdk.app_settings import PersistentStoreDatabaseSetting, PersistentStoreConnectionSetting

class MyFirstApp(TethysAppBase):

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

        ps_settings = (
            # Connection only, no database
            PersistentStoreConnectionSetting(
                name='primary',
                description='Connection with superuser role needed.',
                required=True
            ),
            # Connection only, no database
            PersistentStoreConnectionSetting(
                name='creator',
                description='Create database role only.',
                required=False
            ),
            # Spatial database
            PersistentStoreDatabaseSetting(
                name='spatial_db',
                description='for storing important spatial stuff',
                required=True,
                initializer='appsettings.model.init_spatial_db',
                spatial=True,
            ),
            # Non-spatial database
            PersistentStoreDatabaseSetting(
                name='temp_db',
                description='for storing temporary stuff',
                required=False,
                initializer='appsettings.model.init_temp_db',
                spatial=False,
            )
        )

        return ps_settings

To retrieve a connection to a Persistent Store, import your app class and call either the get_persistent_store_database() or get_persistent_store_connection class methods:

classmethod TethysAppBase.get_persistent_store_database(name, as_url=False, as_sessionmaker=False)

Gets an SQLAlchemy Engine or URL object for the named persistent store database given.

Parameters

name (string) -- Name of the PersistentStoreConnectionSetting as defined in app.py.
as_url (bool) -- Return SQLAlchemy URL object instead of engine object if True. Defaults to False.
as_sessionmaker (bool) -- Returns SessionMaker class bound to the engine if True. Defaults to False.

Returns

An SQLAlchemy Engine or URL object for the persistent store requested.

Return type

sqlalchemy.Engine or sqlalchemy.URL

Example:

from my_first_app.app import MyFirstApp as app

db_engine = app.get_persistent_store_database('example_db')
db_url = app.get_persistent_store_database('example_db', as_url=True)
SessionMaker = app.get_persistent_store_database('example_db', as_sessionmaker=True)
session = SessionMaker()

classmethod TethysAppBase.get_persistent_store_connection(name, as_url=False, as_sessionmaker=False)

Gets an SQLAlchemy Engine or URL object for the named persistent store connection.

Parameters

name (string) -- Name of the PersistentStoreConnectionSetting as defined in app.py.
as_url (bool) -- Return SQLAlchemy URL object instead of engine object if True. Defaults to False.
as_sessionmaker (bool) -- Returns SessionMaker class bound to the engine if True. Defaults to False.

Returns

An SQLAlchemy Engine or URL object for the persistent store requested.

Return type

sqlalchemy.Engine or sqlalchemy.URL

Example:

from my_first_app.app import MyFirstApp as app

conn_engine = app.get_persistent_store_connection('primary')
conn_url = app.get_persistent_store_connection('primary', as_url=True)
SessionMaker = app.get_persistent_store_database('primary', as_sessionmaker=True)
session = SessionMaker()

Tip

See the Persistent Stores API and the Spatial Persistent Stores API for more details on how to use Persistent Stores in your apps.

Dataset Service Settings¶

Dataset Service Settings are used to request specific types of dataset services for use in your app (e.g. CKAN, HydroShare). Create Dataset Service Settings by implementing the dataset_service_settings() method in your app class. This method should return a list of DatasetServiceSetting objects:

TethysAppBase.dataset_service_settings()

Override this method to define dataset service connections for use in your app.

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

Example:

from tethys_sdk.app_settings import DatasetServiceSetting

class MyFirstApp(TethysAppBase):

    def dataset_service_settings(self):
        """
        Example dataset_service_settings method.
        """
        ds_settings = (
            DatasetServiceSetting(
                name='primary_ckan',
                description='Primary CKAN service for app to use.',
                engine=DatasetServiceSetting.CKAN,
                required=True,
            ),
            DatasetServiceSetting(
                name='hydroshare',
                description='HydroShare service for app to use.',
                engine=DatasetServiceSetting.HYDROSHARE,
                required=False
            )
        )

        return ds_settings

To retrieve a connection to a Dataset Service, import your app class and call the get_dataset_service() class method:

classmethod TethysAppBase.get_dataset_service(name, as_public_endpoint=False, as_endpoint=False, as_engine=False)

Retrieves dataset service engine assigned to named DatasetServiceSetting for the app.

Parameters

name (str) -- name fo the DatasetServiceSetting as defined in the app.py.
as_endpoint (bool) -- Returns endpoint url string if True, Defaults to False.
as_public_endpoint (bool) -- Returns public endpoint url string if True. Defaults to False.
as_engine (bool) -- Returns tethys_dataset_services.engine of appropriate type if True. Defaults to False.

Returns

DatasetService assigned to setting if no other options are specified.

Return type

DatasetService

Example:

from my_first_app.app import MyFirstApp as app

ckan_engine = app.get_dataset_service('primary_ckan', as_engine=True)

Tip

See the Dataset Services API for more details on how to use Dataset Services in your apps.

Spatial Dataset Service Settings¶

Spatial Dataset Service Settings are used to request specific types of spatial dataset services for use in your app (e.g. geoserver). Create Spatial Dataset Service Settings by implementing the spatial_dataset_service_settings() method in your app class. This method should return a list of SpatialDatasetServiceSetting objects:

TethysAppBase.spatial_dataset_service_settings()

Override this method to define spatial dataset service connections for use in your app.

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

Example:

from tethys_sdk.app_settings import SpatialDatasetServiceSetting

class MyFirstApp(TethysAppBase):

    def spatial_dataset_service_settings(self):
        """
        Example spatial_dataset_service_settings method.
        """
        sds_settings = (
            SpatialDatasetServiceSetting(
                name='primary_geoserver',
                description='spatial dataset service for app to use',
                engine=SpatialDatasetServiceSetting.GEOSERVER,
                required=True,
            ),
        )

        return sds_settings

To retrieve a connection to a Spatial Dataset Service, import your app class and call the get_spatial_dataset_service() class method:

classmethod TethysAppBase.get_spatial_dataset_service(name, as_public_endpoint=False, as_endpoint=False, as_wms=False, as_wfs=False, as_engine=False)

Retrieves spatial dataset service engine assigned to named SpatialDatasetServiceSetting for the app.

Parameters

name (str) -- name fo the SpatialDatasetServiceSetting as defined in the app.py.
as_endpoint (bool) -- Returns endpoint url string if True, Defaults to False.
as_public_endpoint (bool) -- Returns public endpoint url string if True. Defaults to False.
as_wfs (bool) -- Returns OGC-WFS enpdoint url for spatial dataset service if True. Defaults to False.
as_wms (bool) -- Returns OGC-WMS enpdoint url for spatial dataset service if True. Defaults to False.
as_engine (bool) -- Returns tethys_dataset_services.engine of appropriate type if True. Defaults to False.

Returns

SpatialDatasetService assigned to setting if no other options are specified.

Return type

SpatialDatasetService

Example:

from my_first_app.app import MyFirstApp as app

geoserver_engine = app.get_spatial_dataset_service('primary_geoserver', as_engine=True)

Tip

See the Spatial Dataset Services API for more details on how to use Spatial Dataset Services in your apps.

Web Processing Service Settings¶

Web Processing Service Settings are used to request specific types of dataset services for use in your app (e.g. CKAN, HydroShare). Create Web Processing Service Settings by implementing the web_processing_service_settings() method in your app class. This method should return a list of WebProcessingServiceSetting objects:

TethysAppBase.web_processing_service_settings()

Override this method to define web processing service connections for use in your app.

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

Example:

from tethys_sdk.app_settings import WebProcessingServiceSetting

class MyFirstApp(TethysAppBase):

    def web_processing_service_settings(self):
        """
        Example wps_services method.
        """
        wps_services = (
            WebProcessingServiceSetting(
                name='primary_52n',
                description='WPS service for app to use',
                required=True,
            ),
        )

        return wps_services

To retrieve a connection to a Web Processing Service, import your app class and call the get_web_processing_service() class method:

classmethod TethysAppBase.get_web_processing_service(name, as_public_endpoint=False, as_endpoint=False, as_engine=False)

Retrieves web processing service engine assigned to named WebProcessingServiceSetting for the app.

Parameters

name (str) -- name fo the WebProcessingServiceSetting as defined in the app.py.
as_endpoint (bool) -- Returns endpoint url string if True, Defaults to False.
as_public_endpoint (bool) -- Returns public endpoint url string if True. Defaults to False.
as_engine (bool) -- Returns owslib.wps.WebProcessingService engine if True. Defaults to False.

Returns

WpsService assigned to setting if no other options are specified.

Return type

WpsService

Example:

from my_first_app.app import MyFirstApp as app

wps_engine = app.get_web_processing_service('primary_52n')

Tip

See the Web Processing Services API for more details on how to use Dataset Services in your apps.

API Documentation¶

Settings Objects¶

tethys_sdk.app_settings.CustomSetting¶: alias of <MagicMock id='139722765467856'>

tethys_sdk.app_settings.PersistentStoreConnectionSetting¶: alias of <MagicMock id='139722763582032'>

tethys_sdk.app_settings.PersistentStoreDatabaseSetting¶: alias of <MagicMock id='139722758230992'>

tethys_sdk.app_settings.DatasetServiceSetting¶: alias of <MagicMock id='139722771802384'>

tethys_sdk.app_settings.SpatialDatasetServiceSetting¶: alias of <MagicMock id='139722763230800'>

tethys_sdk.app_settings.WebProcessingServiceSetting¶: alias of <MagicMock id='139722754389904'>

Settings Declaration Methods¶

TethysAppBase.custom_settings()¶

Override this method to define custom settings for use in your app.

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

Example:

from tethys_sdk.app_settings import CustomSetting

class MyFirstApp(TethysAppBase):

    def custom_settings(self):
        """
        Example custom_settings method.
        """
        custom_settings = (
            CustomSetting(
                name='default_name',
                type=CustomSetting.TYPE_STRING
                description='Default model name.',
                required=True
            ),
            CustomSetting(
                name='max_count',
                type=CustomSetting.TYPE_INTEGER,
                description='Maximum allowed count in a method.',
                required=False
            ),
            CustomSetting(
                name='change_factor',
                type=CustomSetting.TYPE_FLOAT,
                description='Change factor that is applied to some process.',
                required=True
            ),
            CustomSetting(
                name='enable_feature',
                type=CustomSetting.TYPE_BOOLEAN,
                description='Enable this feature when True.',
                required=True
            )
        )

        return custom_settings

TethysAppBase.persistent_store_settings()¶

Override this method to define a persistent store service connections and databases for your app.

Returns: A list or tuple of PersistentStoreDatabaseSetting or PersistentStoreConnectionSetting objects.
Return type: iterable

Example:

from tethys_sdk.app_settings import PersistentStoreDatabaseSetting, PersistentStoreConnectionSetting

class MyFirstApp(TethysAppBase):

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

        ps_settings = (
            # Connection only, no database
            PersistentStoreConnectionSetting(
                name='primary',
                description='Connection with superuser role needed.',
                required=True
            ),
            # Connection only, no database
            PersistentStoreConnectionSetting(
                name='creator',
                description='Create database role only.',
                required=False
            ),
            # Spatial database
            PersistentStoreDatabaseSetting(
                name='spatial_db',
                description='for storing important spatial stuff',
                required=True,
                initializer='appsettings.model.init_spatial_db',
                spatial=True,
            ),
            # Non-spatial database
            PersistentStoreDatabaseSetting(
                name='temp_db',
                description='for storing temporary stuff',
                required=False,
                initializer='appsettings.model.init_temp_db',
                spatial=False,
            )
        )

        return ps_settings

TethysAppBase.dataset_service_settings()¶

Override this method to define dataset service connections for use in your app.

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

Example:

from tethys_sdk.app_settings import DatasetServiceSetting

class MyFirstApp(TethysAppBase):

    def dataset_service_settings(self):
        """
        Example dataset_service_settings method.
        """
        ds_settings = (
            DatasetServiceSetting(
                name='primary_ckan',
                description='Primary CKAN service for app to use.',
                engine=DatasetServiceSetting.CKAN,
                required=True,
            ),
            DatasetServiceSetting(
                name='hydroshare',
                description='HydroShare service for app to use.',
                engine=DatasetServiceSetting.HYDROSHARE,
                required=False
            )
        )

        return ds_settings

TethysAppBase.spatial_dataset_service_settings()¶

Override this method to define spatial dataset service connections for use in your app.

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

Example:

from tethys_sdk.app_settings import SpatialDatasetServiceSetting

class MyFirstApp(TethysAppBase):

    def spatial_dataset_service_settings(self):
        """
        Example spatial_dataset_service_settings method.
        """
        sds_settings = (
            SpatialDatasetServiceSetting(
                name='primary_geoserver',
                description='spatial dataset service for app to use',
                engine=SpatialDatasetServiceSetting.GEOSERVER,
                required=True,
            ),
        )

        return sds_settings

TethysAppBase.web_processing_service_settings()¶

Override this method to define web processing service connections for use in your app.

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

Example:

from tethys_sdk.app_settings import WebProcessingServiceSetting

class MyFirstApp(TethysAppBase):

    def web_processing_service_settings(self):
        """
        Example wps_services method.
        """
        wps_services = (
            WebProcessingServiceSetting(
                name='primary_52n',
                description='WPS service for app to use',
                required=True,
            ),
        )

        return wps_services

Settings Getter Methods¶

classmethod TethysAppBase.get_custom_setting(name)¶

Retrieves the value of a CustomSetting for the app.

Parameters: name (str) -- The name of the CustomSetting as defined in the app.py.
Returns: Value of the CustomSetting or None if no value assigned.
Return type: variable

Example:

from my_first_app.app import MyFirstApp as app

max_count = app.get_custom_setting('max_count')

classmethod TethysAppBase.get_persistent_store_database(name, as_url=False, as_sessionmaker=False)¶

Gets an SQLAlchemy Engine or URL object for the named persistent store database given.

Parameters

name (string) -- Name of the PersistentStoreConnectionSetting as defined in app.py.
as_url (bool) -- Return SQLAlchemy URL object instead of engine object if True. Defaults to False.
as_sessionmaker (bool) -- Returns SessionMaker class bound to the engine if True. Defaults to False.

Returns

An SQLAlchemy Engine or URL object for the persistent store requested.

Return type

sqlalchemy.Engine or sqlalchemy.URL

Example:

from my_first_app.app import MyFirstApp as app

db_engine = app.get_persistent_store_database('example_db')
db_url = app.get_persistent_store_database('example_db', as_url=True)
SessionMaker = app.get_persistent_store_database('example_db', as_sessionmaker=True)
session = SessionMaker()

classmethod TethysAppBase.get_persistent_store_connection(name, as_url=False, as_sessionmaker=False)¶

Gets an SQLAlchemy Engine or URL object for the named persistent store connection.

Parameters

name (string) -- Name of the PersistentStoreConnectionSetting as defined in app.py.
as_url (bool) -- Return SQLAlchemy URL object instead of engine object if True. Defaults to False.
as_sessionmaker (bool) -- Returns SessionMaker class bound to the engine if True. Defaults to False.

Returns

An SQLAlchemy Engine or URL object for the persistent store requested.

Return type

sqlalchemy.Engine or sqlalchemy.URL

Example:

from my_first_app.app import MyFirstApp as app

conn_engine = app.get_persistent_store_connection('primary')
conn_url = app.get_persistent_store_connection('primary', as_url=True)
SessionMaker = app.get_persistent_store_database('primary', as_sessionmaker=True)
session = SessionMaker()

classmethod TethysAppBase.get_dataset_service(name, as_public_endpoint=False, as_endpoint=False, as_engine=False)¶

Retrieves dataset service engine assigned to named DatasetServiceSetting for the app.

Parameters

name (str) -- name fo the DatasetServiceSetting as defined in the app.py.
as_endpoint (bool) -- Returns endpoint url string if True, Defaults to False.
as_public_endpoint (bool) -- Returns public endpoint url string if True. Defaults to False.
as_engine (bool) -- Returns tethys_dataset_services.engine of appropriate type if True. Defaults to False.

Returns

DatasetService assigned to setting if no other options are specified.

Return type

DatasetService

Example:

from my_first_app.app import MyFirstApp as app

ckan_engine = app.get_dataset_service('primary_ckan', as_engine=True)

classmethod TethysAppBase.get_spatial_dataset_service(name, as_public_endpoint=False, as_endpoint=False, as_wms=False, as_wfs=False, as_engine=False)¶

Retrieves spatial dataset service engine assigned to named SpatialDatasetServiceSetting for the app.

Parameters

name (str) -- name fo the SpatialDatasetServiceSetting as defined in the app.py.
as_endpoint (bool) -- Returns endpoint url string if True, Defaults to False.
as_public_endpoint (bool) -- Returns public endpoint url string if True. Defaults to False.
as_wfs (bool) -- Returns OGC-WFS enpdoint url for spatial dataset service if True. Defaults to False.
as_wms (bool) -- Returns OGC-WMS enpdoint url for spatial dataset service if True. Defaults to False.
as_engine (bool) -- Returns tethys_dataset_services.engine of appropriate type if True. Defaults to False.

Returns

SpatialDatasetService assigned to setting if no other options are specified.

Return type

SpatialDatasetService

Example:

from my_first_app.app import MyFirstApp as app

geoserver_engine = app.get_spatial_dataset_service('primary_geoserver', as_engine=True)

classmethod TethysAppBase.get_web_processing_service(name, as_public_endpoint=False, as_endpoint=False, as_engine=False)¶

Retrieves web processing service engine assigned to named WebProcessingServiceSetting for the app.

Parameters

name (str) -- name fo the WebProcessingServiceSetting as defined in the app.py.
as_endpoint (bool) -- Returns endpoint url string if True, Defaults to False.
as_public_endpoint (bool) -- Returns public endpoint url string if True. Defaults to False.
as_engine (bool) -- Returns owslib.wps.WebProcessingService engine if True. Defaults to False.

Returns

WpsService assigned to setting if no other options are specified.

Return type

WpsService

Example:

from my_first_app.app import MyFirstApp as app

wps_engine = app.get_web_processing_service('primary_52n')

Table Of Contents

App Settings API

App Templating API

Compute API