diff --git a/doc/api.rst b/doc/api.rst index 74f127ccf72..b47e11c71b9 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -592,30 +592,30 @@ Dataset methods .. autosummary:: :toctree: generated/ - open_dataset load_dataset + open_dataset open_mfdataset open_rasterio open_zarr - Dataset.to_netcdf - Dataset.to_pandas - Dataset.as_numpy - Dataset.to_zarr save_mfdataset + Dataset.as_numpy + Dataset.from_dataframe + Dataset.from_dict Dataset.to_array Dataset.to_dataframe Dataset.to_dask_dataframe Dataset.to_dict - Dataset.from_dataframe - Dataset.from_dict + Dataset.to_netcdf + Dataset.to_pandas + Dataset.to_zarr + Dataset.chunk Dataset.close Dataset.compute - Dataset.persist - Dataset.load - Dataset.chunk - Dataset.unify_chunks Dataset.filter_by_attrs Dataset.info + Dataset.load + Dataset.persist + Dataset.unify_chunks DataArray methods ----------------- @@ -623,29 +623,29 @@ DataArray methods .. autosummary:: :toctree: generated/ - open_dataarray load_dataarray + open_dataarray + DataArray.as_numpy + DataArray.from_cdms2 + DataArray.from_dict + DataArray.from_iris + DataArray.from_series + DataArray.to_cdms2 + DataArray.to_dataframe DataArray.to_dataset + DataArray.to_dict + DataArray.to_index + DataArray.to_iris + DataArray.to_masked_array DataArray.to_netcdf + DataArray.to_numpy DataArray.to_pandas DataArray.to_series - DataArray.to_dataframe - DataArray.to_numpy - DataArray.as_numpy - DataArray.to_index - DataArray.to_masked_array - DataArray.to_cdms2 - DataArray.to_iris - DataArray.from_iris - DataArray.to_dict - DataArray.from_series - DataArray.from_cdms2 - DataArray.from_dict + DataArray.chunk DataArray.close DataArray.compute DataArray.persist DataArray.load - DataArray.chunk DataArray.unify_chunks Coordinates objects @@ -1093,6 +1093,7 @@ Advanced API Dataset.set_close backends.BackendArray backends.BackendEntrypoint + backends.list_engines Default, pandas-backed indexes built-in Xarray: diff --git a/doc/internals/how-to-add-new-backend.rst b/doc/internals/how-to-add-new-backend.rst index 2c92f46a139..a106232958e 100644 --- a/doc/internals/how-to-add-new-backend.rst +++ b/doc/internals/how-to-add-new-backend.rst @@ -16,6 +16,9 @@ If you also want to support lazy loading and dask see :ref:`RST lazy_loading`. Note that the new interface for backends is available from Xarray version >= 0.18 onwards. +You can see what backends are currently available in your working environment +with :py:class:`~xarray.backends.list_engines()`. + .. _RST backend_entrypoint: BackendEntrypoint subclassing @@ -26,7 +29,9 @@ it should implement the following attributes and methods: - the ``open_dataset`` method (mandatory) - the ``open_dataset_parameters`` attribute (optional) -- the ``guess_can_open`` method (optional). +- the ``guess_can_open`` method (optional) +- the ``description`` attribute (optional) +- the ``url`` attribute (optional). This is what a ``BackendEntrypoint`` subclass should look like: @@ -55,6 +60,10 @@ This is what a ``BackendEntrypoint`` subclass should look like: return False return ext in {".my_format", ".my_fmt"} + description = "Use .my_format files in Xarray" + + url = "https://link_to/your_backend/documentation" + ``BackendEntrypoint`` subclass methods and attributes are detailed in the following. .. _RST open_dataset: @@ -168,6 +177,17 @@ that always returns ``False``. Backend ``guess_can_open`` takes as input the ``filename_or_obj`` parameter of Xarray :py:meth:`~xarray.open_dataset`, and returns a boolean. +.. _RST properties: + +description and url +^^^^^^^^^^^^^^^^^^^^ + +``description`` is used to provide a short text description of the backend. +``url`` is used to include a link to the backend's documentation or code. + +These attributes are surfaced when a user prints :py:class:`~xarray.backends.BackendEntrypoint`. +If ``description`` or ``url`` are not defined, an empty string is returned. + .. _RST decoders: Decoders diff --git a/doc/whats-new.rst b/doc/whats-new.rst index aefb6adfc2b..070903a0d83 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -47,6 +47,11 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Improves overall documentation around available backends, including adding docstrings for :py:func:`xarray.backends.list_engines` + Add :py:meth:`__str__` to surface the new :py:class:`BackendEntrypoint` ``description`` + and ``url`` attributes. (:issue:`6577`, :pull:`7000`) + By `Jessica Scheick `_. + Internal Changes ~~~~~~~~~~~~~~~~ diff --git a/xarray/backends/common.py b/xarray/backends/common.py index 901a85a5682..0cbdc29794c 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -372,12 +372,34 @@ class BackendEntrypoint: - ``guess_can_open`` method: it shall return ``True`` if the backend is able to open ``filename_or_obj``, ``False`` otherwise. The implementation of this method is not mandatory. + + Attributes + ---------- + + open_dataset_parameters : tuple, default None + A list of ``open_dataset`` method parameters. + The setting of this attribute is not mandatory. + description : str + A short string describing the engine. + The setting of this attribute is not mandatory. + url : str + A string with the URL to the backend's documentation. + The setting of this attribute is not mandatory. """ available: ClassVar[bool] = True open_dataset_parameters: tuple | None = None - """list of ``open_dataset`` method parameters""" + description: str = "" + url: str = "" + + def __repr__(self) -> str: + txt = f"<{type(self).__name__}>" + if self.description: + txt += f"\n {self.description}" + if self.url: + txt += f"\n Learn more at {self.url}" + return txt def open_dataset( self, diff --git a/xarray/backends/plugins.py b/xarray/backends/plugins.py index e40c65413c6..374383f55c8 100644 --- a/xarray/backends/plugins.py +++ b/xarray/backends/plugins.py @@ -105,7 +105,20 @@ def build_engines(entrypoints) -> dict[str, BackendEntrypoint]: @functools.lru_cache(maxsize=1) def list_engines() -> dict[str, BackendEntrypoint]: + """ + Return a dictionary of available engines and their BackendEntrypoint objects. + + Returns + ------- + dictionary + + Notes + ----- + This function lives in the backends namespace (``engs=xr.backends.list_engines()``). + If available, more information is available about each backend via ``engs["eng_name"]``. + # New selection mechanism introduced with Python 3.10. See GH6514. + """ if sys.version_info >= (3, 10): entrypoints = entry_points(group="xarray.backends") else: diff --git a/xarray/core/types.py b/xarray/core/types.py index 243a69d7eb2..2b65f4d23e6 100644 --- a/xarray/core/types.py +++ b/xarray/core/types.py @@ -20,6 +20,7 @@ if TYPE_CHECKING: from numpy.typing import ArrayLike + from ..backends.common import BackendEntrypoint from .common import AbstractArray, DataWithCoords from .dataarray import DataArray from .dataset import Dataset @@ -85,6 +86,7 @@ def dtype(self) -> np.dtype: DTypeLikeSave: Any = None +T_Backend = TypeVar("T_Backend", bound="BackendEntrypoint") T_Dataset = TypeVar("T_Dataset", bound="Dataset") T_DataArray = TypeVar("T_DataArray", bound="DataArray") T_Variable = TypeVar("T_Variable", bound="Variable")