App Settings API
Last Updated: May 2023
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
CustomSettings
are used to create scalar-valued settings for an app. Five basic types of values are supported including string
, boolean
, integer
, float
, and UUID
. There are two additional types of CustomSettings
: SecretCustomSettings
and JSONCustomSettings
. The values of SecretCustomSettings
are encrypted before being saved to the database to more securly store sensitive values like passwords and API keys. The JSONCustomSettings
store JSON strings, but are retrieved as JSON dictionaries for storing more complex configuration for apps. Create CustomSettings
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, SecretCustomSetting, JSONCustomSetting 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 ), CustomSetting( name='feature_id', type=CustomSetting.TYPE_UUID, description='Feature ID.', required=True ), SecretCustomSetting( name='api_key', description='API key for data service.', required=True ), JSONCustomSetting( name='app_configuration', description='Primary app configuration.', required=True, default={"display_plots": True, "default_dataset": "streamflow"} ), ) return custom_settings
To retrieve the value of a CustomSetting
, 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 .app import MyFirstApp as app max_count = app.get_custom_setting('max_count')
To set the value of a CustomSetting
dynamically, import your app class and call the set_custom_setting()
class method:
- classmethod TethysAppBase.set_custom_setting(name, value)
Assign the value of a CustomSetting for the app.
- Parameters:
name (str) -- The name of the CustomSetting as defined in the app.py.
value (str/int/float/boolean/uuid.UUID) -- the value of the customSetting.
Example:
from .app import MyFirstApp as app max_count = app.set_custom_setting('max_count', 5)
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
orPersistentStoreConnectionSetting
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 .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 .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 .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 .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 .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.
Scheduler Settings
Scheduler Settings are used to request connection information that will allow you to schedule processing using one of the job managements systems supported by Tethys Platform (e.g. HTCondor and Dask). Create a Scheduler Setting by implementing the scheduler_settings()
method in your app class. This method should return a list or tuple of SchedulerSetting objects.
- TethysAppBase.scheduler_settings()
Override this method to define HTCondor and Dask scheduler services for use in your app.
- Returns:
A list or tuple of
SchedulerSetting
objects.- Return type:
iterable
Example:
from tethys_sdk.app_settings import SchedulerSetting class MyFirstApp(TethysAppBase): def scheduler_settings(self): """ Example scheduler_settings method. """ scheduler_settings = ( SchedulerSetting( name='primary_condor_scheduler', description='Scheduler for HTCondor cluster.', engine=SchedulerSetting.HTCONDOR, required=False, ), SchedulerSetting( name='primary_dask_scheduler', description='Scheduler for Dask cluster.', engine=SchedulerSetting.DASK, required=True, ), ) return scheduler_settings
Using Scheduler Settings
To retrieve a scheduler, import your app class and call the get_scheduler()
class method:
- classmethod TethysAppBase.get_scheduler(name)
Retrieves a Scheduler assigned to the named SchedulerSetting.
- Parameters:
name (str) -- The name of the SchedulerSetting as defined in the app.py.
- Returns:
The Scheduler assigned to the named setting.
- Return type:
Scheduler
Example:
from .app import MyFirstApp as app scheduler = app.get_scheduler('primary_condor') job_manager = app.get_job_manager() job_manager.create_job( name='do_the_thing', job_type='CONDORJOB', scheduler=scheduler, ... )
Tip
See the Jobs API documentation for more details on how to use Schedulers in your apps.
API Documentation
Settings Objects
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, SecretCustomSetting, JSONCustomSetting 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 ), CustomSetting( name='feature_id', type=CustomSetting.TYPE_UUID, description='Feature ID.', required=True ), SecretCustomSetting( name='api_key', description='API key for data service.', required=True ), JSONCustomSetting( name='app_configuration', description='Primary app configuration.', required=True, default={"display_plots": True, "default_dataset": "streamflow"} ), ) 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
orPersistentStoreConnectionSetting
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
- TethysAppBase.scheduler_settings()
Override this method to define HTCondor and Dask scheduler services for use in your app.
- Returns:
A list or tuple of
SchedulerSetting
objects.- Return type:
iterable
Example:
from tethys_sdk.app_settings import SchedulerSetting class MyFirstApp(TethysAppBase): def scheduler_settings(self): """ Example scheduler_settings method. """ scheduler_settings = ( SchedulerSetting( name='primary_condor_scheduler', description='Scheduler for HTCondor cluster.', engine=SchedulerSetting.HTCONDOR, required=False, ), SchedulerSetting( name='primary_dask_scheduler', description='Scheduler for Dask cluster.', engine=SchedulerSetting.DASK, required=True, ), ) return scheduler_settings
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 .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 .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 .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 .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 .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 .app import MyFirstApp as app wps_engine = app.get_web_processing_service('primary_52n')
- classmethod TethysAppBase.get_scheduler(name)
Retrieves a Scheduler assigned to the named SchedulerSetting.
- Parameters:
name (str) -- The name of the SchedulerSetting as defined in the app.py.
- Returns:
The Scheduler assigned to the named setting.
- Return type:
Scheduler
Example:
from .app import MyFirstApp as app scheduler = app.get_scheduler('primary_condor') job_manager = app.get_job_manager() job_manager.create_job( name='do_the_thing', job_type='CONDORJOB', scheduler=scheduler, ... )