API reference

Top-level Rest class

The Rest class can be used for publishing a a collection of xarray.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

Plugins

Plugins are inherit from the Plugin class, and implement various hooks.

`Plugin`	Xpublish plugins provide ways to extend the core of xpublish with new routers and other functionality.
`hookimpl`	Decorator helper class for marking functions as hook implementations.
`hookspec`	Decorator helper class for marking functions as hook specifications.
`Dependencies`	A set of dependencies that are passed into plugin routers.
`plugins.hooks.PluginSpec`	Plugin extension points
`plugins.manage.find_default_plugins`([...])	Find Xpublish plugins from entry point group xpublish.plugin
`plugins.manage.load_default_plugins`([...])	Find and initialize plugins from entry point group xpublish.plugin
`plugins.manage.configure_plugins`(plugins[, ...])	Initialize and configure plugins with given dictionary of configurations