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])	Attempts to load dataset from plugins.
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 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_plugins()	FastAPI dependency that returns the a dictionary of loaded plugins.
get_plugin_manager()	Return the active plugin manager.