API reference

Top-level Rest class

The Rest class can be used for publishing a xarray.Dataset object or a collection of Dataset objects.

The main interfaces to Xpublish that many users may use.

Rest([datasets, routers, cache_kws, ...])	Used to publish multiple Xarray Datasets via a REST API (FastAPI application).
Rest.app	Returns the fastapi.FastAPI application instance.
Rest.cache	Returns the cachey.Cache instance used by the FastAPI application.
Rest.plugins	Returns the loaded plugins
Rest.serve([host, port, log_level])	Serve this FastAPI application via uvicorn.run().
Rest.register_plugin(plugin[, plugin_name, ...])	Register a plugin with the xpublish system
Rest.dependencies()	FastAPI dependencies to pass to plugin router methods

There are also a handful of methods that are more likely to be used when subclassing xpublish.Rest to modify functionality, or are used by plugin dependencies.

Rest.setup_datasets(datasets)	Initialize datasets and dataset accessor function
Rest.get_datasets_from_plugins()	Return dataset ids from directly loaded datasets and plugins
Rest.get_dataset_from_plugins([dataset_id])	Attempt to load dataset from plugins, otherwise return dataset from passed in dictionary of datasets
Rest.setup_plugins([plugins])	Initialize and load plugins from entry_points unless explicitly provided
Rest.init_cache_kwargs(cache_kws)	Set up cache kwargs
Rest.init_app_kwargs(app_kws)	Set up FastAPI application kwargs
Rest.plugin_routers()	Load the app and dataset routers for plugins

There is also a specialized version of xpublish.Rest for use when only a single dataset is being served, instead of a collection of datasets.

SingleDatasetRest(dataset[, routers, ...])	Used to publish a single Xarray dataset via a REST API (FastAPI application).
SingleDatasetRest.setup_datasets(datasets)	Modifies the dataset loading to instead connect to the single dataset

For serving a single dataset the SingleDatasetRest is used instead.

SingleDatasetRest(dataset[, routers, ...])

Used to publish a single Xarray dataset via a REST API (FastAPI application).

Dataset.rest (xarray accessor)

This accessor extends xarray.Dataset with the same interface than SingleDatasetRest. It is a convenient method for publishing one single dataset. Proper use of this accessor should be like:

>>> import xarray as xr         # first import xarray
>>> import xpublish             # import xpublish (the dataset 'rest' accessor is registered)
>>> ds = xr.Dataset()           # create or load an xarray Dataset
>>> ds.rest(...)                # call the 'rest' accessor on the dataset
>>> ds.rest.<meth_or_prop>      # access to the methods and properties listed below

Calling the accessor

Dataset.rest(**kwargs)

Initialize this accessor by setting optional configuration values.

Properties

Dataset.rest.app	Returns the fastapi.FastAPI application instance.
Dataset.rest.cache	Returns the cachey.Cache instance used by the FastAPI application.

Methods

Dataset.rest.serve(**kwargs)

Serve this FastAPI application via uvicorn.run().

FastAPI dependencies

The functions below are defined in module xpublish.dependencies and can be used as FastAPI dependencies when creating custom API endpoints directly.

When creating routers with plugins, instead use xpublish.Dependency that will be passed in to the Plugin.app_router or Plugin.dataset_router method.

get_dataset_ids()	FastAPI dependency for getting the list of ids (string keys) of the collection of datasets being served.
get_dataset(dataset_id)	FastAPI dependency for accessing the published xarray dataset object.
get_cache()	FastAPI dependency for accessing the application's cache.
get_zvariables([dataset, cache])	FastAPI dependency that returns a dictionary of zarr encoded variables.
get_zmetadata([dataset, cache, zvariables])	FastAPI dependency that returns a consolidated zmetadata dictionary.
get_plugins()	FastAPI dependency that returns the a dictionary of loaded plugins
get_plugin_manager()	Return the active plugin manager