list available backends and basic descriptors (#7000)

Co-authored-by: Illviljan <[email protected]>
Co-authored-by: Mick <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Deepak Cherian <[email protected]>
Co-authored-by: dcherian <[email protected]>

Author: 5 people

doc/api.rst

@@ -592,60 +592,60 @@ 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
 -----------------
 
 .. 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:
 

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

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 <https://github.com/jessicas11>`_.
+
 
 Internal Changes
 ~~~~~~~~~~~~~~~~

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,

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:

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")