xpublish.Rest#

class xpublish.Rest(datasets=None, routers=None, cache_kws=None, app_kws=None, plugins=None)[source]#

Used to publish multiple Xarray Datasets via a REST API (FastAPI application).

To publish a single dataset via its own FastAPI application, you might want to use the xarray.Dataset.rest accessor for more convenience. Additionally the xpublish.SingleDatasetRest class allows has a simplified interface for single dataset access.

NOTE: The urls of the application’s API endpoints differ whether a single dataset or a mapping (collection) of datasets is given. In the latter case, all dataset-specific endpoint urls have the prefix /datasets/{dataset_id}, where {dataset_id} corresponds to the keys of the mapping (converted to strings). Still in the latter case, the endpoint /datasets is added and returns the list of all dataset ids.

__init__(datasets=None, routers=None, cache_kws=None, app_kws=None, plugins=None)[source]#

Initialize a REST object for publishing Xarray Datasets.

Parameters:

  • datasets (Optional[Dict[str, Dataset]]) – A mapping of datasets objects to be served. If a mapping is given, keys are used as dataset ids and are converted to strings. See also the notes below.

  • routers (Optional[List[APIRouter]]) – A list of dataset-specific fastapi.APIRouter instances to include in the fastAPI application. These routers are in addition to any loaded via plugins. The items of the list may also be tuples with the following format: [(router1, {'prefix': '/foo', 'tags': ['foo', 'bar']})], where the 1st tuple element is a fastapi.APIRouter instance and the 2nd element is a dictionary that is used to pass keyword arguments to fastapi.FastAPI.include_router().

  • cache_kws (Optional[Dict]) – Dictionary of keyword arguments to be passed to cachey.Cache.__init__(). By default, the cache size is set to 1MB, but this can be changed with available_bytes.

  • app_kws (Optional[Dict]) – Dictionary of keyword arguments to be passed to fastapi.FastAPI.__init__().

  • plugins (Optional[Dict[str, Plugin]]) – Optional dictionary of loaded, configured plugins. Overrides automatic loading of plugins. If no plugins are desired, set to an empty dict.

Methods

__init__([datasets, routers, cache_kws, ...])

Initialize a REST object for publishing Xarray Datasets.

dependencies()

FastAPI dependencies to pass to plugin router methods.

get_dataset_from_plugins([dataset_id])

Attempts to load dataset from plugins.

get_datasets_from_plugins()

Return dataset ids from directly loaded datasets and plugins.

init_app_kwargs(app_kws)

Set up FastAPI application kwargs.

init_cache_kwargs(cache_kws)

Set up cache kwargs.

plugin_routers()

Load the app and dataset routers for plugins.

register_plugin(plugin[, plugin_name, overwrite])

Register a plugin with the xpublish system.

serve([host, port, log_level])

Serve this FastAPI application via uvicorn.run().

setup_datasets(datasets)

Initialize datasets and dataset accessor function.

setup_plugins([plugins])

Initialize and load plugins from entry_points unless explicitly provided.

Attributes

app

Returns the fastapi.FastAPI application instance.

cache

Returns the cachey.Cache instance used by the FastAPI application.

plugins

Returns the loaded plugins.