API reference#

Top-level Rest class#

The Rest class can be used for publishing a xarray.Dataset or xarray.DataTree object, or a collection of either. A bare Dataset is wrapped in a single-node DataTree internally so the rest of the library operates uniformly on hierarchical data.

The main interfaces to Xpublish that many users may use.

`Rest`([datasets, routers, cache_kws, ...])	Used to publish multiple Xarray Datasets / DataTrees 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 functions.
`Rest.get_datasets_from_plugins`()	Return dataset ids from directly loaded datasets and plugins.
`Rest.get_dataset_from_plugins`(dataset_id[, ...])	Resolve a Dataset by `dataset_id` (and optional `group`).
`Rest.get_datatree_from_plugins`(dataset_id[, ...])	Resolve a DataTree by `dataset_id` (and optional `group`).
`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 or DataTree via a REST API (FastAPI application).
`SingleDatasetRest.setup_datasets`(datasets)	Modifies dataset loading to instead connect to the single dataset/DataTree.

For serving a single dataset the SingleDatasetRest is used instead.

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

Used to publish a single Xarray Dataset or DataTree 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().

DataTree.rest (xarray accessor)#

The same accessor is registered on xarray.DataTree, exposing the same interface for publishing a single hierarchical tree:

>>> import xarray as xr
>>> import xpublish
>>> dt = xr.DataTree()          # or load one with xr.open_datatree(...)
>>> dt.rest(...)                # configure (optional)
>>> dt.rest.serve()             # serve the tree

Calling the accessor

DataTree.rest(**kwargs)

Initialize this accessor by setting optional configuration values.

Properties

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

Methods

DataTree.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_datatree`(dataset_id)	FastAPI dependency for accessing the published xarray DataTree 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.

When a route declares a {group_path:path} segment, get_dataset returns the Dataset at that node of the underlying DataTree (or the root dataset if no group_path is present). get_datatree returns the subtree rooted at the requested group.