Backends descriptions (#7200)

headtr1ck · web-flow · commit 0a75d131d4a6 · 2022-10-26T10:01:04.000-06:00
* add backendEntrypoints descriptions

* add zarr and store backends

* add docstrings to backend classes

* add to whats.new
diff --git a/doc/api-hidden.rst b/doc/api-hidden.rst
@@ -483,6 +483,12 @@
    backends.NetCDF4DataStore.is_remote
    backends.NetCDF4DataStore.lock
 
+   backends.NetCDF4BackendEntrypoint.available
+   backends.NetCDF4BackendEntrypoint.description
+   backends.NetCDF4BackendEntrypoint.url
+   backends.NetCDF4BackendEntrypoint.guess_can_open
+   backends.NetCDF4BackendEntrypoint.open_dataset
+
    backends.H5NetCDFStore.autoclose
    backends.H5NetCDFStore.close
    backends.H5NetCDFStore.encode
@@ -510,6 +516,27 @@
    backends.H5NetCDFStore.sync
    backends.H5NetCDFStore.ds
 
+   backends.H5netcdfBackendEntrypoint.available
+   backends.H5netcdfBackendEntrypoint.description
+   backends.H5netcdfBackendEntrypoint.url
+   backends.H5netcdfBackendEntrypoint.guess_can_open
+   backends.H5netcdfBackendEntrypoint.open_dataset
+
+   backends.PseudoNetCDFDataStore.close
+   backends.PseudoNetCDFDataStore.get_attrs
+   backends.PseudoNetCDFDataStore.get_dimensions
+   backends.PseudoNetCDFDataStore.get_encoding
+   backends.PseudoNetCDFDataStore.get_variables
+   backends.PseudoNetCDFDataStore.open
+   backends.PseudoNetCDFDataStore.open_store_variable
+   backends.PseudoNetCDFDataStore.ds
+
+   backends.PseudoNetCDFBackendEntrypoint.available
+   backends.PseudoNetCDFBackendEntrypoint.description
+   backends.PseudoNetCDFBackendEntrypoint.url
+   backends.PseudoNetCDFBackendEntrypoint.guess_can_open
+   backends.PseudoNetCDFBackendEntrypoint.open_dataset
+
    backends.PydapDataStore.close
    backends.PydapDataStore.get_attrs
    backends.PydapDataStore.get_dimensions
@@ -519,6 +546,12 @@
    backends.PydapDataStore.open
    backends.PydapDataStore.open_store_variable
 
+   backends.PydapBackendEntrypoint.available
+   backends.PydapBackendEntrypoint.description
+   backends.PydapBackendEntrypoint.url
+   backends.PydapBackendEntrypoint.guess_can_open
+   backends.PydapBackendEntrypoint.open_dataset
+
    backends.ScipyDataStore.close
    backends.ScipyDataStore.encode
    backends.ScipyDataStore.encode_attribute
@@ -541,6 +574,39 @@
    backends.ScipyDataStore.sync
    backends.ScipyDataStore.ds
 
+   backends.ScipyBackendEntrypoint.available
+   backends.ScipyBackendEntrypoint.description
+   backends.ScipyBackendEntrypoint.url
+   backends.ScipyBackendEntrypoint.guess_can_open
+   backends.ScipyBackendEntrypoint.open_dataset
+
+   backends.ZarrStore.close
+   backends.ZarrStore.encode_attribute
+   backends.ZarrStore.encode_variable
+   backends.ZarrStore.get_attrs
+   backends.ZarrStore.get_dimensions
+   backends.ZarrStore.get_variables
+   backends.ZarrStore.open_group
+   backends.ZarrStore.open_store_variable
+   backends.ZarrStore.set_attributes
+   backends.ZarrStore.set_dimensions
+   backends.ZarrStore.set_variables
+   backends.ZarrStore.store
+   backends.ZarrStore.sync
+   backends.ZarrStore.ds
+
+   backends.ZarrBackendEntrypoint.available
+   backends.ZarrBackendEntrypoint.description
+   backends.ZarrBackendEntrypoint.url
+   backends.ZarrBackendEntrypoint.guess_can_open
+   backends.ZarrBackendEntrypoint.open_dataset
+
+   backends.StoreBackendEntrypoint.available
+   backends.StoreBackendEntrypoint.description
+   backends.StoreBackendEntrypoint.url
+   backends.StoreBackendEntrypoint.guess_can_open
+   backends.StoreBackendEntrypoint.open_dataset
+
    backends.FileManager.acquire
    backends.FileManager.acquire_context
    backends.FileManager.close
diff --git a/doc/api.rst b/doc/api.rst
@@ -1109,12 +1109,28 @@ arguments for the ``load_store`` and ``dump_to_store`` Dataset methods:
 
    backends.NetCDF4DataStore
    backends.H5NetCDFStore
+   backends.PseudoNetCDFDataStore
    backends.PydapDataStore
    backends.ScipyDataStore
+   backends.ZarrStore
    backends.FileManager
    backends.CachingFileManager
    backends.DummyFileManager
 
+These BackendEntrypoints provide a basic interface to the most commonly
+used filetypes in the xarray universe.
+
+.. autosummary::
+   :toctree: generated/
+
+   backends.NetCDF4BackendEntrypoint
+   backends.H5netcdfBackendEntrypoint
+   backends.PseudoNetCDFBackendEntrypoint
+   backends.PydapBackendEntrypoint
+   backends.ScipyBackendEntrypoint
+   backends.StoreBackendEntrypoint
+   backends.ZarrBackendEntrypoint
+
 Deprecated / Pending Deprecation
 ================================
 
diff --git a/doc/whats-new.rst b/doc/whats-new.rst
@@ -66,6 +66,8 @@ Documentation
   By `Tom Nicholas <https://github.com/TomNicholas>`_.
 - Rename ``axes`` to ``axs`` in plotting to align with ``matplotlib.pyplot.subplots``. (:pull:`7194`)
   By `Jimmy Westling <https://github.com/illviljan>`_.
+- Add documentation of specific BackendEntrypoints (:pull:`7200`).
+  By `Michael Niklas <https://github.com/headtr1ck>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~
diff --git a/xarray/backends/__init__.py b/xarray/backends/__init__.py
@@ -6,15 +6,16 @@
 from .cfgrib_ import CfGribDataStore
 from .common import AbstractDataStore, BackendArray, BackendEntrypoint
 from .file_manager import CachingFileManager, DummyFileManager, FileManager
-from .h5netcdf_ import H5NetCDFStore
+from .h5netcdf_ import H5netcdfBackendEntrypoint, H5NetCDFStore
 from .memory import InMemoryDataStore
-from .netCDF4_ import NetCDF4DataStore
+from .netCDF4_ import NetCDF4BackendEntrypoint, NetCDF4DataStore
 from .plugins import list_engines
-from .pseudonetcdf_ import PseudoNetCDFDataStore
-from .pydap_ import PydapDataStore
+from .pseudonetcdf_ import PseudoNetCDFBackendEntrypoint, PseudoNetCDFDataStore
+from .pydap_ import PydapBackendEntrypoint, PydapDataStore
 from .pynio_ import NioDataStore
-from .scipy_ import ScipyDataStore
-from .zarr import ZarrStore
+from .scipy_ import ScipyBackendEntrypoint, ScipyDataStore
+from .store import StoreBackendEntrypoint
+from .zarr import ZarrBackendEntrypoint, ZarrStore
 
 __all__ = [
     "AbstractDataStore",
@@ -32,5 +33,12 @@
     "H5NetCDFStore",
     "ZarrStore",
     "PseudoNetCDFDataStore",
+    "H5netcdfBackendEntrypoint",
+    "NetCDF4BackendEntrypoint",
+    "PseudoNetCDFBackendEntrypoint",
+    "PydapBackendEntrypoint",
+    "ScipyBackendEntrypoint",
+    "StoreBackendEntrypoint",
+    "ZarrBackendEntrypoint",
     "list_engines",
 ]
diff --git a/xarray/backends/h5netcdf_.py b/xarray/backends/h5netcdf_.py
@@ -352,7 +352,32 @@ def close(self, **kwargs):
 
 
 class H5netcdfBackendEntrypoint(BackendEntrypoint):
+    """
+    Backend for netCDF files based on the h5netcdf package.
+
+    It can open ".nc", ".nc4", ".cdf" files but will only be
+    selected as the default if the "netcdf4" engine is not available.
+
+    Additionally it can open valid HDF5 files, see
+    https://h5netcdf.org/#invalid-netcdf-files for more info.
+    It will not be detected as valid backend for such files, so make
+    sure to specify ``engine="h5netcdf"`` in ``open_dataset``.
+
+    For more information about the underlying library, visit:
+    https://h5netcdf.org
+
+    See Also
+    --------
+    backends.H5NetCDFStore
+    backends.NetCDF4BackendEntrypoint
+    backends.ScipyBackendEntrypoint
+    """
+
     available = has_h5netcdf
+    description = (
+        "Open netCDF (.nc, .nc4 and .cdf) and most HDF5 files using h5netcdf in Xarray"
+    )
+    url = "https://docs.xarray.dev/en/stable/generated/xarray.backends.H5netcdfBackendEntrypoint.html"
 
     def guess_can_open(self, filename_or_obj):
         magic_number = try_read_magic_number_from_file_or_path(filename_or_obj)
diff --git a/xarray/backends/netCDF4_.py b/xarray/backends/netCDF4_.py
@@ -516,7 +516,32 @@ def close(self, **kwargs):
 
 
 class NetCDF4BackendEntrypoint(BackendEntrypoint):
+    """
+    Backend for netCDF files based on the netCDF4 package.
+
+    It can open ".nc", ".nc4", ".cdf" files and will be choosen
+    as default for these files.
+
+    Additionally it can open valid HDF5 files, see
+    https://h5netcdf.org/#invalid-netcdf-files for more info.
+    It will not be detected as valid backend for such files, so make
+    sure to specify ``engine="netcdf4"`` in ``open_dataset``.
+
+    For more information about the underlying library, visit:
+    https://unidata.github.io/netcdf4-python
+
+    See Also
+    --------
+    backends.NetCDF4DataStore
+    backends.H5netcdfBackendEntrypoint
+    backends.ScipyBackendEntrypoint
+    """
+
     available = has_netcdf4
+    description = (
+        "Open netCDF (.nc, .nc4 and .cdf) and most HDF5 files using netCDF4 in Xarray"
+    )
+    url = "https://docs.xarray.dev/en/stable/generated/xarray.backends.NetCDF4BackendEntrypoint.html"
 
     def guess_can_open(self, filename_or_obj):
         if isinstance(filename_or_obj, str) and is_remote_uri(filename_or_obj):
diff --git a/xarray/backends/pseudonetcdf_.py b/xarray/backends/pseudonetcdf_.py
@@ -104,7 +104,35 @@ def close(self):
 
 
 class PseudoNetCDFBackendEntrypoint(BackendEntrypoint):
+    """
+    Backend for netCDF-like data formats in the air quality field
+    based on the PseudoNetCDF package.
+
+    It can open:
+    - CAMx
+    - RACM2 box-model outputs
+    - Kinetic Pre-Processor outputs
+    - ICARTT Data files (ffi1001)
+    - CMAQ Files
+    - GEOS-Chem Binary Punch/NetCDF files
+    - and many more
+
+    This backend is not selected by default for any files, so make
+    sure to specify ``engine="pseudonetcdf"`` in ``open_dataset``.
+
+    For more information about the underlying library, visit:
+    https://pseudonetcdf.readthedocs.io
+
+    See Also
+    --------
+    backends.PseudoNetCDFDataStore
+    """
+
     available = has_pseudonetcdf
+    description = (
+        "Open many atmospheric science data formats using PseudoNetCDF in Xarray"
+    )
+    url = "https://docs.xarray.dev/en/stable/generated/xarray.backends.PseudoNetCDFBackendEntrypoint.html"
 
     # *args and **kwargs are not allowed in open_backend_dataset_ kwargs,
     # unless the open_dataset_parameters are explicitly defined like this:
diff --git a/xarray/backends/pydap_.py b/xarray/backends/pydap_.py
@@ -139,7 +139,24 @@ def get_dimensions(self):
 
 
 class PydapBackendEntrypoint(BackendEntrypoint):
+    """
+    Backend for steaming datasets over the internet using
+    the Data Access Protocol, also known as DODS or OPeNDAP
+    based on the pydap package.
+
+    This backend is selected by default for urls.
+
+    For more information about the underlying library, visit:
+    https://www.pydap.org
+
+    See Also
+    --------
+    backends.PydapDataStore
+    """
+
     available = has_pydap
+    description = "Open remote datasets via OPeNDAP using pydap in Xarray"
+    url = "https://docs.xarray.dev/en/stable/generated/xarray.backends.PydapBackendEntrypoint.html"
 
     def guess_can_open(self, filename_or_obj):
         return isinstance(filename_or_obj, str) and is_remote_uri(filename_or_obj)
diff --git a/xarray/backends/scipy_.py b/xarray/backends/scipy_.py
@@ -241,7 +241,29 @@ def close(self):
 
 
 class ScipyBackendEntrypoint(BackendEntrypoint):
+    """
+    Backend for netCDF files based on the scipy package.
+
+    It can open ".nc", ".nc4", ".cdf" and ".gz" files but will only be
+    selected as the default if the "netcdf4" and "h5netcdf" engines are
+    not available. It has the advantage that is is a lightweight engine
+    that has no system requirements (unlike netcdf4 and h5netcdf).
+
+    Additionally it can open gizp compressed (".gz") files.
+
+    For more information about the underlying library, visit:
+    https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.netcdf_file.html
+
+    See Also
+    --------
+    backends.ScipyDataStore
+    backends.NetCDF4BackendEntrypoint
+    backends.H5netcdfBackendEntrypoint
+    """
+
     available = has_scipy
+    description = "Open netCDF files (.nc, .nc4, .cdf and .gz) using scipy in Xarray"
+    url = "https://docs.xarray.dev/en/stable/generated/xarray.backends.ScipyBackendEntrypoint.html"
 
     def guess_can_open(self, filename_or_obj):
 
diff --git a/xarray/backends/store.py b/xarray/backends/store.py
@@ -7,6 +7,8 @@
 
 class StoreBackendEntrypoint(BackendEntrypoint):
     available = True
+    description = "Open AbstractDataStore instances in Xarray"
+    url = "https://docs.xarray.dev/en/stable/generated/xarray.backends.StoreBackendEntrypoint.html"
 
     def guess_can_open(self, filename_or_obj):
         return isinstance(filename_or_obj, AbstractDataStore)
diff --git a/xarray/backends/zarr.py b/xarray/backends/zarr.py
@@ -808,7 +808,20 @@ def open_zarr(
 
 
 class ZarrBackendEntrypoint(BackendEntrypoint):
+    """
+    Backend for ".zarr" files based on the zarr package.
+
+    For more information about the underlying library, visit:
+    https://zarr.readthedocs.io/en/stable
+
+    See Also
+    --------
+    backends.ZarrStore
+    """
+
     available = has_zarr
+    description = "Open zarr files (.zarr) using zarr in Xarray"
+    url = "https://docs.xarray.dev/en/stable/generated/xarray.backends.ZarrBackendEntrypoint.html"
 
     def guess_can_open(self, filename_or_obj):
         try:
