From b48dc55ea51270646b707b9ffc6c8a2aeca8a42e Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Tue, 6 Sep 2022 16:55:49 -0400 Subject: [PATCH 01/32] add backend desc and docs properties to BackendEntrypoint --- xarray/backends/common.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/xarray/backends/common.py b/xarray/backends/common.py index 52738c639e1..0580ea1ba81 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -374,6 +374,20 @@ class BackendEntrypoint: open_dataset_parameters: tuple | None = None """list of ``open_dataset`` method parameters""" + @property + def backend_description(description: str | None): + """ + Brief text description of backend + """ + return False + + @property + def backend_docs(docs: str | os.PathLike): + """ + URL to backend's documentation + """ + return False + def open_dataset( self, filename_or_obj: str | os.PathLike, From ea0af7fbd9c9c0178767c1ab24a338c3e80879d4 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Tue, 6 Sep 2022 17:17:30 -0400 Subject: [PATCH 02/32] add avail_engines function to api --- xarray/backends/api.py | 18 ++++++++++++++++++ xarray/backends/common.py | 4 ++-- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index ca040306bf0..edd02de5dcd 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -79,6 +79,24 @@ "zarr": backends.ZarrStore.open_group, } +def avail_engines() -> List: + """ + Return a list of available engines with metadata. + + For any registered backend that is available, get the backend name, + short text description, and link to the backend's documentation. + + Returns + ------- + List of lists + """ + engines = plugins.list_engines() + + eng_list = [] + for eng in engines: + eng_list.append([eng, engines[eng].backend_description, engines[eng].backend_docs]) + + return eng_list def _get_default_engine_remote_uri() -> Literal["netcdf4", "pydap"]: engine: Literal["netcdf4", "pydap"] diff --git a/xarray/backends/common.py b/xarray/backends/common.py index 0580ea1ba81..e61b943f8a2 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -379,14 +379,14 @@ def backend_description(description: str | None): """ Brief text description of backend """ - return False + return "" @property def backend_docs(docs: str | os.PathLike): """ URL to backend's documentation """ - return False + return "" def open_dataset( self, From f9e61d1f7c48644c787d0b0fc1c6e008b05b5745 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 6 Sep 2022 21:24:35 +0000 Subject: [PATCH 03/32] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- xarray/backends/api.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index edd02de5dcd..ffbcfc604bb 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -79,13 +79,14 @@ "zarr": backends.ZarrStore.open_group, } + def avail_engines() -> List: """ Return a list of available engines with metadata. - + For any registered backend that is available, get the backend name, short text description, and link to the backend's documentation. - + Returns ------- List of lists @@ -94,10 +95,13 @@ def avail_engines() -> List: eng_list = [] for eng in engines: - eng_list.append([eng, engines[eng].backend_description, engines[eng].backend_docs]) + eng_list.append( + [eng, engines[eng].backend_description, engines[eng].backend_docs] + ) return eng_list + def _get_default_engine_remote_uri() -> Literal["netcdf4", "pydap"]: engine: Literal["netcdf4", "pydap"] try: From 7aa2d7042e9c3ce6e231cf382ce738828b846fc1 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 8 Sep 2022 11:38:47 -0400 Subject: [PATCH 04/32] convert engine list to pandas dataframe --- xarray/backends/api.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index ffbcfc604bb..b77394f90cf 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -4,6 +4,7 @@ from glob import glob from io import BytesIO from numbers import Number +import pandas as pd from typing import ( TYPE_CHECKING, Any, @@ -93,13 +94,13 @@ def avail_engines() -> List: """ engines = plugins.list_engines() - eng_list = [] + eng_dict = {} for eng in engines: - eng_list.append( - [eng, engines[eng].backend_description, engines[eng].backend_docs] - ) - - return eng_list + eng_dict[eng] = [engines[eng].backend_description, engines[eng].backend_docs] + + eng_df = pd.DataFrame.from_dict(data=eng_dict, orient="index", columns=["Description","Documentation"])#.set_index("Engine") + eng_df.columns.name="Engine" + return eng_df def _get_default_engine_remote_uri() -> Literal["netcdf4", "pydap"]: From c8dfb2f5f22ea4cc663a1a908aa7deb959327fe9 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 8 Sep 2022 11:52:40 -0400 Subject: [PATCH 05/32] alphabetize (loosely) input/output functions in api.rst --- doc/api.rst | 52 +++++++++++++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index 11ae5de8531..741eb76a57d 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -588,30 +588,32 @@ 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 ----------------- @@ -619,29 +621,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 From e2fc425e802836cb76161979a8e757d240d7c015 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 8 Sep 2022 11:54:16 -0400 Subject: [PATCH 06/32] add new function to api docs --- doc/api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index 741eb76a57d..fed844415dc 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -588,6 +588,7 @@ Dataset methods .. autosummary:: :toctree: generated/ + avail_engines load_dataset open_dataset open_mfdataset @@ -612,8 +613,6 @@ Dataset methods Dataset.load Dataset.persist Dataset.unify_chunks - - DataArray methods ----------------- @@ -621,6 +620,7 @@ DataArray methods .. autosummary:: :toctree: generated/ + avail_engines load_dataarray open_dataarray DataArray.as_numpy From a0fc0c2bc0b859c2c95048c451d667b3e4bcd993 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 8 Sep 2022 12:02:27 -0400 Subject: [PATCH 07/32] add new properties to docstring --- xarray/backends/common.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/xarray/backends/common.py b/xarray/backends/common.py index e61b943f8a2..d01cc0a4305 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -369,6 +369,12 @@ 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. + - ``backend_description`` property: it shall return a short string describing the engine, + ``""`` otherwise. + The implementation of this property is not mandatory. + - ``backend_docs`` property: it shall return a string with the URL to the backend's documentation, + ``""`` otherwise. + The implementation of this property is not mandatory. """ open_dataset_parameters: tuple | None = None From d4057174cc16e47f29404b04b3b47eafff1b5985 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 8 Sep 2022 12:26:28 -0400 Subject: [PATCH 08/32] add new available backend properties to docs --- doc/api-hidden.rst | 2 ++ doc/internals/how-to-add-new-backend.rst | 27 ++++++++++++++++++++++-- doc/whats-new.rst | 4 ++++ 3 files changed, 31 insertions(+), 2 deletions(-) diff --git a/doc/api-hidden.rst b/doc/api-hidden.rst index 30bc9f858f2..2eab06ec50f 100644 --- a/doc/api-hidden.rst +++ b/doc/api-hidden.rst @@ -559,6 +559,8 @@ backends.DummyFileManager.close backends.BackendArray + backends.BackendEntrypoint.backend_description + backends.BackendEntrypoint.backend_docs backends.BackendEntrypoint.guess_can_open backends.BackendEntrypoint.open_dataset diff --git a/doc/internals/how-to-add-new-backend.rst b/doc/internals/how-to-add-new-backend.rst index bb497a1c062..9a3df87bbf4 100644 --- a/doc/internals/how-to-add-new-backend.rst +++ b/doc/internals/how-to-add-new-backend.rst @@ -22,11 +22,13 @@ BackendEntrypoint subclassing +++++++++++++++++++++++++++++ Your ``BackendEntrypoint`` sub-class is the primary interface with Xarray, and -it should implement the following attributes and methods: +it should implement the following attributes, methods, and properties: - the ``open_dataset`` method (mandatory) - the ``open_dataset_parameters`` attribute (optional) -- the ``guess_can_open`` method (optional). +- the ``guess_can_open`` method (optional) +- the ``backend_description`` property (optional) +- the ``backend_docs`` property (optional). This is what a ``BackendEntrypoint`` subclass should look like: @@ -55,6 +57,14 @@ This is what a ``BackendEntrypoint`` subclass should look like: return False return ext in {".my_format", ".my_fmt"} + @property + def backend_description(self): + return "Use .my_format files in Xarray" + + @property + def backend_docs(self): + return "https://link_to/your_backend/documentation" + ``BackendEntrypoint`` subclass methods and attributes are detailed in the following. .. _RST open_dataset: @@ -168,6 +178,19 @@ 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: + +backend_description and backend_docs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``backend_description`` is used to provide a short text description of the backend. +``backend_docs`` is used to include a link to the backend's documentation or code. + +These properties are surfaced to the user via ``xarray.avail_engines``, +which returns a table of backends available in the users' current environment. +If ``backend_description`` or ``backend_docs`` are not defined, an empty string is returned +and users will only see the backend's name in the list of available engines. + .. _RST decoders: Decoders diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 9ce51e48983..55f284fe740 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -205,6 +205,10 @@ New Features By `Joe Hamman `_. - Upload development versions to `TestPyPI `_. By `Justus Magin `_. +- :py:meth:`xarray.avail_engines` surfaces the new :py:class:`BackendEntrypoint` ``backend_description`` + and ``backend_docs`` properties to let users know which backends are available in their current environment. + (:issue:`6577`, :pull:`7000`) + By `Jessica Scheick `_. Breaking changes ~~~~~~~~~~~~~~~~ From 73580dce6b7f567a12993b6714e99a7e6b29abbc Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 8 Sep 2022 16:28:19 +0000 Subject: [PATCH 09/32] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- xarray/backends/api.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index b77394f90cf..741eb03f2bd 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -4,7 +4,6 @@ from glob import glob from io import BytesIO from numbers import Number -import pandas as pd from typing import ( TYPE_CHECKING, Any, @@ -23,6 +22,7 @@ ) import numpy as np +import pandas as pd from .. import backends, conventions from ..core import indexing @@ -97,9 +97,11 @@ def avail_engines() -> List: eng_dict = {} for eng in engines: eng_dict[eng] = [engines[eng].backend_description, engines[eng].backend_docs] - - eng_df = pd.DataFrame.from_dict(data=eng_dict, orient="index", columns=["Description","Documentation"])#.set_index("Engine") - eng_df.columns.name="Engine" + + eng_df = pd.DataFrame.from_dict( + data=eng_dict, orient="index", columns=["Description", "Documentation"] + ) # .set_index("Engine") + eng_df.columns.name = "Engine" return eng_df From 6af2891e5d29dcc1d1c31addfaf15b5b0a970b25 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 8 Sep 2022 12:36:28 -0400 Subject: [PATCH 10/32] remove redundant 'backend' from attribute names --- doc/api-hidden.rst | 4 ++-- doc/internals/how-to-add-new-backend.rst | 18 +++++++++--------- doc/whats-new.rst | 4 ++-- xarray/backends/api.py | 10 +++++----- xarray/backends/common.py | 8 ++++---- 5 files changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/api-hidden.rst b/doc/api-hidden.rst index 2eab06ec50f..637e5bab6f9 100644 --- a/doc/api-hidden.rst +++ b/doc/api-hidden.rst @@ -559,8 +559,8 @@ backends.DummyFileManager.close backends.BackendArray - backends.BackendEntrypoint.backend_description - backends.BackendEntrypoint.backend_docs + backends.BackendEntrypoint.description + backends.BackendEntrypoint.docs backends.BackendEntrypoint.guess_can_open backends.BackendEntrypoint.open_dataset diff --git a/doc/internals/how-to-add-new-backend.rst b/doc/internals/how-to-add-new-backend.rst index 9a3df87bbf4..5bc1ec9d879 100644 --- a/doc/internals/how-to-add-new-backend.rst +++ b/doc/internals/how-to-add-new-backend.rst @@ -27,8 +27,8 @@ it should implement the following attributes, methods, and properties: - the ``open_dataset`` method (mandatory) - the ``open_dataset_parameters`` attribute (optional) - the ``guess_can_open`` method (optional) -- the ``backend_description`` property (optional) -- the ``backend_docs`` property (optional). +- the ``description`` property (optional) +- the ``docs`` property (optional). This is what a ``BackendEntrypoint`` subclass should look like: @@ -58,11 +58,11 @@ This is what a ``BackendEntrypoint`` subclass should look like: return ext in {".my_format", ".my_fmt"} @property - def backend_description(self): + def description(self): return "Use .my_format files in Xarray" @property - def backend_docs(self): + def docs(self): return "https://link_to/your_backend/documentation" ``BackendEntrypoint`` subclass methods and attributes are detailed in the following. @@ -180,15 +180,15 @@ Xarray :py:meth:`~xarray.open_dataset`, and returns a boolean. .. _RST properties: -backend_description and backend_docs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +description and docs +^^^^^^^^^^^^^^^^^^^^ -``backend_description`` is used to provide a short text description of the backend. -``backend_docs`` is used to include a link to the backend's documentation or code. +``description`` is used to provide a short text description of the backend. +``docs`` is used to include a link to the backend's documentation or code. These properties are surfaced to the user via ``xarray.avail_engines``, which returns a table of backends available in the users' current environment. -If ``backend_description`` or ``backend_docs`` are not defined, an empty string is returned +If ``description`` or ``docs`` are not defined, an empty string is returned and users will only see the backend's name in the list of available engines. .. _RST decoders: diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 55f284fe740..fb818f92e11 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -205,8 +205,8 @@ New Features By `Joe Hamman `_. - Upload development versions to `TestPyPI `_. By `Justus Magin `_. -- :py:meth:`xarray.avail_engines` surfaces the new :py:class:`BackendEntrypoint` ``backend_description`` - and ``backend_docs`` properties to let users know which backends are available in their current environment. +- :py:meth:`xarray.avail_engines` surfaces the new :py:class:`BackendEntrypoint` ``description`` + and ``docs`` properties to let users know which backends are available in their current environment. (:issue:`6577`, :pull:`7000`) By `Jessica Scheick `_. diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 741eb03f2bd..66c1e996f5f 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -96,12 +96,12 @@ def avail_engines() -> List: eng_dict = {} for eng in engines: - eng_dict[eng] = [engines[eng].backend_description, engines[eng].backend_docs] - + eng_dict[eng] = [engines[eng].description, engines[eng].docs] + eng_df = pd.DataFrame.from_dict( - data=eng_dict, orient="index", columns=["Description", "Documentation"] - ) # .set_index("Engine") - eng_df.columns.name = "Engine" + data=eng_dict, orient="index", columns=["Description","Documentation"] + )#.set_index("Engine") + eng_df.columns.name="Engine" return eng_df diff --git a/xarray/backends/common.py b/xarray/backends/common.py index d01cc0a4305..0fd5be008b4 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -369,10 +369,10 @@ 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. - - ``backend_description`` property: it shall return a short string describing the engine, + - ``description`` property: it shall return a short string describing the engine, ``""`` otherwise. The implementation of this property is not mandatory. - - ``backend_docs`` property: it shall return a string with the URL to the backend's documentation, + - ``docs`` property: it shall return a string with the URL to the backend's documentation, ``""`` otherwise. The implementation of this property is not mandatory. """ @@ -381,14 +381,14 @@ class BackendEntrypoint: """list of ``open_dataset`` method parameters""" @property - def backend_description(description: str | None): + def description(description: str | None): """ Brief text description of backend """ return "" @property - def backend_docs(docs: str | os.PathLike): + def docs(docs: str | os.PathLike): """ URL to backend's documentation """ From 897c2046052f7adcc7a344cce6af6c175a5dc3f3 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 8 Sep 2022 16:48:16 +0000 Subject: [PATCH 11/32] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- xarray/backends/api.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 66c1e996f5f..b5ba61bf2e3 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -97,11 +97,11 @@ def avail_engines() -> List: eng_dict = {} for eng in engines: eng_dict[eng] = [engines[eng].description, engines[eng].docs] - + eng_df = pd.DataFrame.from_dict( - data=eng_dict, orient="index", columns=["Description","Documentation"] - )#.set_index("Engine") - eng_df.columns.name="Engine" + data=eng_dict, orient="index", columns=["Description", "Documentation"] + ) # .set_index("Engine") + eng_df.columns.name = "Engine" return eng_df From 623bb3183d32608a054accb1802f063a4bfca351 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 8 Sep 2022 13:01:02 -0400 Subject: [PATCH 12/32] turn properties into attributes as per PR review --- doc/api-hidden.rst | 2 -- doc/internals/how-to-add-new-backend.rst | 16 ++++++---------- xarray/backends/common.py | 16 ++++------------ 3 files changed, 10 insertions(+), 24 deletions(-) diff --git a/doc/api-hidden.rst b/doc/api-hidden.rst index 637e5bab6f9..30bc9f858f2 100644 --- a/doc/api-hidden.rst +++ b/doc/api-hidden.rst @@ -559,8 +559,6 @@ backends.DummyFileManager.close backends.BackendArray - backends.BackendEntrypoint.description - backends.BackendEntrypoint.docs backends.BackendEntrypoint.guess_can_open backends.BackendEntrypoint.open_dataset diff --git a/doc/internals/how-to-add-new-backend.rst b/doc/internals/how-to-add-new-backend.rst index 5bc1ec9d879..c9cde968122 100644 --- a/doc/internals/how-to-add-new-backend.rst +++ b/doc/internals/how-to-add-new-backend.rst @@ -22,13 +22,13 @@ BackendEntrypoint subclassing +++++++++++++++++++++++++++++ Your ``BackendEntrypoint`` sub-class is the primary interface with Xarray, and -it should implement the following attributes, methods, and properties: +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 ``description`` property (optional) -- the ``docs`` property (optional). +- the ``description`` attribute (optional) +- the ``docs`` attribute (optional). This is what a ``BackendEntrypoint`` subclass should look like: @@ -57,13 +57,9 @@ This is what a ``BackendEntrypoint`` subclass should look like: return False return ext in {".my_format", ".my_fmt"} - @property - def description(self): - return "Use .my_format files in Xarray" + description = "Use .my_format files in Xarray" - @property - def docs(self): - return "https://link_to/your_backend/documentation" + docs = "https://link_to/your_backend/documentation" ``BackendEntrypoint`` subclass methods and attributes are detailed in the following. @@ -186,7 +182,7 @@ description and docs ``description`` is used to provide a short text description of the backend. ``docs`` is used to include a link to the backend's documentation or code. -These properties are surfaced to the user via ``xarray.avail_engines``, +These attributes are surfaced to the user via ``xarray.avail_engines``, which returns a table of backends available in the users' current environment. If ``description`` or ``docs`` are not defined, an empty string is returned and users will only see the backend's name in the list of available engines. diff --git a/xarray/backends/common.py b/xarray/backends/common.py index 0fd5be008b4..0cf7061842d 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -380,19 +380,11 @@ class BackendEntrypoint: open_dataset_parameters: tuple | None = None """list of ``open_dataset`` method parameters""" - @property - def description(description: str | None): - """ - Brief text description of backend - """ - return "" + description: str = "" + """Brief text description of backend""" - @property - def docs(docs: str | os.PathLike): - """ - URL to backend's documentation - """ - return "" + docs: str = "" + """URL to backend's documentation""" def open_dataset( self, From 33412c4f56c8fe11f4550db8847b0fcecca8ecf5 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 8 Sep 2022 15:11:06 -0400 Subject: [PATCH 13/32] fix docstring formatting for attributes --- xarray/backends/common.py | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/xarray/backends/common.py b/xarray/backends/common.py index 0cf7061842d..9dae41c614b 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -369,22 +369,24 @@ 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. - - ``description`` property: it shall return a short string describing the engine, - ``""`` otherwise. - The implementation of this property is not mandatory. - - ``docs`` property: it shall return a string with the URL to the backend's documentation, - ``""`` otherwise. - The implementation of this property 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. + docs : str + A string with the URL to the backend's documentation. + The setting of this attribute is not mandatory. """ open_dataset_parameters: tuple | None = None - """list of ``open_dataset`` method parameters""" - description: str = "" - """Brief text description of backend""" - docs: str = "" - """URL to backend's documentation""" def open_dataset( self, From 06861fafd904054cc341949b7305174cd2aed2a4 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 8 Sep 2022 16:03:37 -0400 Subject: [PATCH 14/32] add str to BackendEntrypoint class --- xarray/backends/api.py | 4 ++-- xarray/backends/common.py | 8 ++++++++ 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index b5ba61bf2e3..7aaf9f38e25 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -90,7 +90,7 @@ def avail_engines() -> List: Returns ------- - List of lists + DataFrame """ engines = plugins.list_engines() @@ -100,7 +100,7 @@ def avail_engines() -> List: eng_df = pd.DataFrame.from_dict( data=eng_dict, orient="index", columns=["Description", "Documentation"] - ) # .set_index("Engine") + ) eng_df.columns.name = "Engine" return eng_df diff --git a/xarray/backends/common.py b/xarray/backends/common.py index 9dae41c614b..cd90c71255e 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -388,6 +388,14 @@ class BackendEntrypoint: description: str = "" docs: str = "" + def __str__(self) -> str: + txt = f"Backend type: {type(self).__name__}." + if self.description: + txt += f"\n{self.description}" + if self.docs: + txt += f"\nFind more info at {self.docs}" + return txt + def open_dataset( self, filename_or_obj: str | os.PathLike, From 1dd69acc98046f99faec11974a22e2135d236319 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 8 Sep 2022 20:05:13 +0000 Subject: [PATCH 15/32] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- xarray/backends/common.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xarray/backends/common.py b/xarray/backends/common.py index cd90c71255e..335b8b7d405 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -369,7 +369,7 @@ 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 ---------- From 4fdfad1cd32f2a7aa47268ff954207400348bf8a Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Fri, 9 Sep 2022 14:15:34 -0400 Subject: [PATCH 16/32] update output type for avail_engines function --- xarray/backends/api.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 7aaf9f38e25..59ec2a5b03c 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -81,7 +81,7 @@ } -def avail_engines() -> List: +def avail_engines() -> pd.DataFrame: """ Return a list of available engines with metadata. From 02de4306fcf4992c0cb0717121ac220a4d97e5bf Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Mon, 12 Sep 2022 14:50:33 -0400 Subject: [PATCH 17/32] update docs and code based on PR review --- doc/api.rst | 5 +++-- doc/internals/how-to-add-new-backend.rst | 9 ++++++--- doc/whats-new.rst | 4 ++-- xarray/backends/api.py | 11 ++++++----- xarray/backends/common.py | 8 ++++---- 5 files changed, 21 insertions(+), 16 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index fed844415dc..9faf31b1521 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -588,7 +588,7 @@ Dataset methods .. autosummary:: :toctree: generated/ - avail_engines + show_engines load_dataset open_dataset open_mfdataset @@ -620,7 +620,7 @@ DataArray methods .. autosummary:: :toctree: generated/ - avail_engines + show_engines load_dataarray open_dataarray DataArray.as_numpy @@ -1088,6 +1088,7 @@ Advanced API Dataset.set_close backends.BackendArray backends.BackendEntrypoint + backends.list_engines These backends provide a low-level interface for lazily loading data from external file-formats or protocols, and can be manually invoked to create diff --git a/doc/internals/how-to-add-new-backend.rst b/doc/internals/how-to-add-new-backend.rst index d675019ed1d..12f2e8f4919 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 @@ -180,11 +183,11 @@ description and docs ^^^^^^^^^^^^^^^^^^^^ ``description`` is used to provide a short text description of the backend. -``docs`` is used to include a link to the backend's documentation or code. +``url`` is used to include a link to the backend's documentation or code. -These attributes are surfaced to the user via ``xarray.avail_engines``, +These attributes are surfaced to the user via :py:func:`show_engines`, which returns a table of backends available in the users' current environment. -If ``description`` or ``docs`` are not defined, an empty string is returned +If ``description`` or ``url`` are not defined, an empty string is returned and users will only see the backend's name in the list of available engines. .. _RST decoders: diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 89fd78449ec..8374c1a5d66 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -211,8 +211,8 @@ New Features By `Joe Hamman `_. - Upload development versions to `TestPyPI `_. By `Justus Magin `_. -- :py:meth:`xarray.avail_engines` surfaces the new :py:class:`BackendEntrypoint` ``description`` - and ``docs`` properties to let users know which backends are available in their current environment. +- :py:meth:`xarray.show_engines` surfaces the new :py:class:`BackendEntrypoint` ``description`` + and ``url`` properties to let users know which backends are available in their current environment. (:issue:`6577`, :pull:`7000`) By `Jessica Scheick `_. diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 59ec2a5b03c..415065d40ff 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -81,7 +81,7 @@ } -def avail_engines() -> pd.DataFrame: +def show_engines() -> pd.DataFrame: """ Return a list of available engines with metadata. @@ -91,12 +91,13 @@ def avail_engines() -> pd.DataFrame: Returns ------- DataFrame + + See Also + -------- + plugins.list_engines() """ engines = plugins.list_engines() - - eng_dict = {} - for eng in engines: - eng_dict[eng] = [engines[eng].description, engines[eng].docs] + eng_dict = {eng:[engines[eng].description, engines[eng].url] for eng in engines} eng_df = pd.DataFrame.from_dict( data=eng_dict, orient="index", columns=["Description", "Documentation"] diff --git a/xarray/backends/common.py b/xarray/backends/common.py index 335b8b7d405..0f37228719e 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -379,21 +379,21 @@ class BackendEntrypoint: description : str A short string describing the engine. The setting of this attribute is not mandatory. - docs : str + url : str A string with the URL to the backend's documentation. The setting of this attribute is not mandatory. """ open_dataset_parameters: tuple | None = None description: str = "" - docs: str = "" + url: str = "" def __str__(self) -> str: txt = f"Backend type: {type(self).__name__}." if self.description: txt += f"\n{self.description}" - if self.docs: - txt += f"\nFind more info at {self.docs}" + if self.url: + txt += f"\nLearn more at {self.url}" return txt def open_dataset( From b410eecd0b8ccf19475dbfaabee3add7727ad82f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 12 Sep 2022 18:52:12 +0000 Subject: [PATCH 18/32] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/internals/how-to-add-new-backend.rst | 2 +- xarray/backends/api.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/internals/how-to-add-new-backend.rst b/doc/internals/how-to-add-new-backend.rst index 12f2e8f4919..25f0f47b588 100644 --- a/doc/internals/how-to-add-new-backend.rst +++ b/doc/internals/how-to-add-new-backend.rst @@ -16,7 +16,7 @@ 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 +You can see what backends are currently available in your working environment with :py:class:`~xarray.backends.list_engines()`. .. _RST backend_entrypoint: diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 415065d40ff..71e8ec69afc 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -97,7 +97,7 @@ def show_engines() -> pd.DataFrame: plugins.list_engines() """ engines = plugins.list_engines() - eng_dict = {eng:[engines[eng].description, engines[eng].url] for eng in engines} + eng_dict = {eng: [engines[eng].description, engines[eng].url] for eng in engines} eng_df = pd.DataFrame.from_dict( data=eng_dict, orient="index", columns=["Description", "Documentation"] From 0a48f2022bd4b8b58928dc5ef24b7870ad028c43 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Mon, 12 Sep 2022 14:56:29 -0400 Subject: [PATCH 19/32] commit unsaved changes for last commit --- doc/internals/how-to-add-new-backend.rst | 6 +++--- doc/whats-new.rst | 3 ++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/internals/how-to-add-new-backend.rst b/doc/internals/how-to-add-new-backend.rst index 25f0f47b588..b25c6ac7b3c 100644 --- a/doc/internals/how-to-add-new-backend.rst +++ b/doc/internals/how-to-add-new-backend.rst @@ -31,7 +31,7 @@ it should implement the following attributes and methods: - the ``open_dataset_parameters`` attribute (optional) - the ``guess_can_open`` method (optional) - the ``description`` attribute (optional) -- the ``docs`` attribute (optional). +- the ``url`` attribute (optional). This is what a ``BackendEntrypoint`` subclass should look like: @@ -62,7 +62,7 @@ This is what a ``BackendEntrypoint`` subclass should look like: description = "Use .my_format files in Xarray" - docs = "https://link_to/your_backend/documentation" + url = "https://link_to/your_backend/documentation" ``BackendEntrypoint`` subclass methods and attributes are detailed in the following. @@ -179,7 +179,7 @@ Xarray :py:meth:`~xarray.open_dataset`, and returns a boolean. .. _RST properties: -description and docs +description and url ^^^^^^^^^^^^^^^^^^^^ ``description`` is used to provide a short text description of the backend. diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 8374c1a5d66..de00986a77c 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -212,7 +212,8 @@ New Features - Upload development versions to `TestPyPI `_. By `Justus Magin `_. - :py:meth:`xarray.show_engines` surfaces the new :py:class:`BackendEntrypoint` ``description`` - and ``url`` properties to let users know which backends are available in their current environment. + and ``url`` attributes to let users know which backends are available in their current environment. + Improves overall documentation around accessing backends. (:issue:`6577`, :pull:`7000`) By `Jessica Scheick `_. From c3c157f8f61e3a535d25a470f9842f4b3a83600b Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 15 Sep 2022 11:47:02 -0400 Subject: [PATCH 20/32] remove api function and update docs post dev discussion to just return a dict --- doc/api.rst | 2 -- doc/internals/how-to-add-new-backend.rst | 6 ++---- doc/whats-new.rst | 7 +++--- xarray/backends/api.py | 27 +----------------------- xarray/backends/common.py | 2 +- xarray/backends/plugins.py | 13 ++++++++++++ 6 files changed, 20 insertions(+), 37 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index 9faf31b1521..2bd7b744237 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -588,7 +588,6 @@ Dataset methods .. autosummary:: :toctree: generated/ - show_engines load_dataset open_dataset open_mfdataset @@ -620,7 +619,6 @@ DataArray methods .. autosummary:: :toctree: generated/ - show_engines load_dataarray open_dataarray DataArray.as_numpy diff --git a/doc/internals/how-to-add-new-backend.rst b/doc/internals/how-to-add-new-backend.rst index b25c6ac7b3c..a106232958e 100644 --- a/doc/internals/how-to-add-new-backend.rst +++ b/doc/internals/how-to-add-new-backend.rst @@ -185,10 +185,8 @@ 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 to the user via :py:func:`show_engines`, -which returns a table of backends available in the users' current environment. -If ``description`` or ``url`` are not defined, an empty string is returned -and users will only see the backend's name in the list of available engines. +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: diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 12c9a71242e..4477694418e 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -216,10 +216,9 @@ New Features By `Joe Hamman `_. - Upload development versions to `TestPyPI `_. By `Justus Magin `_. -- :py:meth:`xarray.show_engines` surfaces the new :py:class:`BackendEntrypoint` ``description`` - and ``url`` attributes to let users know which backends are available in their current environment. - Improves overall documentation around accessing backends. - (:issue:`6577`, :pull:`7000`) +- Improves overall documentation around available backends, including adding docstrings for :py:meth:`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 `_. Breaking changes diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 3489bd61613..cb8d35b0a0d 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -25,7 +25,7 @@ import pandas as pd from .. import backends, conventions -from ..core import indexing +from ..core import indexing, formatting from ..core.combine import ( _infer_concat_order_from_positions, _nested_combine, @@ -81,31 +81,6 @@ } -def show_engines() -> pd.DataFrame: - """ - Return a list of available engines with metadata. - - For any registered backend that is available, get the backend name, - short text description, and link to the backend's documentation. - - Returns - ------- - DataFrame - - See Also - -------- - plugins.list_engines() - """ - engines = plugins.list_engines() - eng_dict = {eng: [engines[eng].description, engines[eng].url] for eng in engines} - - eng_df = pd.DataFrame.from_dict( - data=eng_dict, orient="index", columns=["Description", "Documentation"] - ) - eng_df.columns.name = "Engine" - return eng_df - - def _get_default_engine_remote_uri() -> Literal["netcdf4", "pydap"]: engine: Literal["netcdf4", "pydap"] try: diff --git a/xarray/backends/common.py b/xarray/backends/common.py index 0f37228719e..ad9299f7080 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -389,7 +389,7 @@ class BackendEntrypoint: url: str = "" def __str__(self) -> str: - txt = f"Backend type: {type(self).__name__}." + txt = f"Backend type: {type(self).__name__}" if self.description: txt += f"\n{self.description}" if self.url: diff --git a/xarray/backends/plugins.py b/xarray/backends/plugins.py index c1f70b24c80..77254573d74 100644 --- a/xarray/backends/plugins.py +++ b/xarray/backends/plugins.py @@ -99,6 +99,19 @@ def build_engines(entrypoints): @functools.lru_cache(maxsize=1) def list_engines(): # New selection mechanism introduced with Python 3.10. See GH6514. + """ + 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"]``. + + """ if sys.version_info >= (3, 10): entrypoints = entry_points(group="xarray.backends") else: From 3d37077b064e97b61a1a004fb36fedee290cf973 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 15 Sep 2022 15:48:42 +0000 Subject: [PATCH 21/32] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/whats-new.rst | 2 +- xarray/backends/api.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 4477694418e..e17dd6d226d 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -216,7 +216,7 @@ New Features By `Joe Hamman `_. - Upload development versions to `TestPyPI `_. By `Justus Magin `_. -- Improves overall documentation around available backends, including adding docstrings for :py:meth:`xarray.backends.list_engines()` +- Improves overall documentation around available backends, including adding docstrings for :py:meth:`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 `_. diff --git a/xarray/backends/api.py b/xarray/backends/api.py index cb8d35b0a0d..28193616a56 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -25,7 +25,7 @@ import pandas as pd from .. import backends, conventions -from ..core import indexing, formatting +from ..core import formatting, indexing from ..core.combine import ( _infer_concat_order_from_positions, _nested_combine, From f40660e351aebc344a49b1dfefd716df881a72cd Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 15 Sep 2022 11:50:43 -0400 Subject: [PATCH 22/32] remove missed imports --- xarray/backends/api.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 28193616a56..d2929519852 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -22,10 +22,9 @@ ) import numpy as np -import pandas as pd from .. import backends, conventions -from ..core import formatting, indexing +from ..core import indexing from ..core.combine import ( _infer_concat_order_from_positions, _nested_combine, From 1d78879314345df3d074864b392f5d1e005deaf4 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Mon, 19 Sep 2022 16:19:31 -0400 Subject: [PATCH 23/32] Apply suggestions from code review - move comment Co-authored-by: Illviljan <14371165+Illviljan@users.noreply.github.com> --- xarray/backends/plugins.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xarray/backends/plugins.py b/xarray/backends/plugins.py index 77254573d74..a9f7cdf45b8 100644 --- a/xarray/backends/plugins.py +++ b/xarray/backends/plugins.py @@ -98,7 +98,6 @@ def build_engines(entrypoints): @functools.lru_cache(maxsize=1) def list_engines(): - # New selection mechanism introduced with Python 3.10. See GH6514. """ Return a dictionary of available engines and their BackendEntrypoint objects. @@ -110,7 +109,8 @@ def list_engines(): ----- 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") From 089393f5eda7da758a6d83b1a0f4f8cbaeea2432 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 19 Sep 2022 20:20:59 +0000 Subject: [PATCH 24/32] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- xarray/backends/plugins.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xarray/backends/plugins.py b/xarray/backends/plugins.py index a9f7cdf45b8..cac857e028b 100644 --- a/xarray/backends/plugins.py +++ b/xarray/backends/plugins.py @@ -109,7 +109,7 @@ def list_engines(): ----- 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): From 331acf5e7933f94f8c2c575c22e4e248d881b3ec Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Tue, 20 Sep 2022 15:00:08 -0400 Subject: [PATCH 25/32] add list engines typing --- xarray/backends/plugins.py | 2 +- xarray/core/types.py | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/xarray/backends/plugins.py b/xarray/backends/plugins.py index cac857e028b..e083819cc22 100644 --- a/xarray/backends/plugins.py +++ b/xarray/backends/plugins.py @@ -97,7 +97,7 @@ def build_engines(entrypoints): @functools.lru_cache(maxsize=1) -def list_engines(): +def list_engines() -> Mapping[str, T_Backend]: """ Return a dictionary of available engines and their BackendEntrypoint objects. diff --git a/xarray/core/types.py b/xarray/core/types.py index 8a75572522a..f720895e60c 100644 --- a/xarray/core/types.py +++ b/xarray/core/types.py @@ -6,6 +6,7 @@ if TYPE_CHECKING: + from ..backends.common import BackendEntrypoint from .common import AbstractArray, DataWithCoords from .dataarray import DataArray from .dataset import Dataset @@ -39,6 +40,7 @@ Ellipsis: 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") From 98b85dc1c4c51b0b49b2450e095a8233b08ef4c8 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Tue, 20 Sep 2022 15:21:23 -0400 Subject: [PATCH 26/32] change str to repr and improve layout --- xarray/backends/common.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/xarray/backends/common.py b/xarray/backends/common.py index ad9299f7080..1704218d583 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -388,12 +388,12 @@ class BackendEntrypoint: description: str = "" url: str = "" - def __str__(self) -> str: - txt = f"Backend type: {type(self).__name__}" + def __repr__(self) -> str: + txt = f"<{type(self).__name__}>" if self.description: - txt += f"\n{self.description}" + txt += f"\n {self.description}" if self.url: - txt += f"\nLearn more at {self.url}" + txt += f"\n Learn more at {self.url}" return txt def open_dataset( From fc4c93a7091026c991e18424db1c70bc1eb50021 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 20 Sep 2022 19:23:10 +0000 Subject: [PATCH 27/32] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- xarray/core/types.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xarray/core/types.py b/xarray/core/types.py index f720895e60c..eaaf24a6e02 100644 --- a/xarray/core/types.py +++ b/xarray/core/types.py @@ -40,7 +40,7 @@ Ellipsis: Any = None -T_Backend = TypeVar('T_Backend', bound="BackendEntrypoint") +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") From b9785839762c3c4837ff302c66c1cad65481ba51 Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 13 Oct 2022 15:46:36 -0400 Subject: [PATCH 28/32] deal with issues from changes on main --- doc/whats-new.rst | 8 ++++---- xarray/backends/plugins.py | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index aca0b8d8c99..5ffe04df2c5 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -210,6 +210,10 @@ New Features By `Tom White `_. - Allow string formatting of scalar DataArrays. (:pull:`5981`) By `fmaussion `_. +- 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 `_. Bug fixes ~~~~~~~~~ @@ -311,10 +315,6 @@ New Features By `Joe Hamman `_. - Upload development versions to `TestPyPI `_. By `Justus Magin `_. -- Improves overall documentation around available backends, including adding docstrings for :py:meth:`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 `_. Breaking changes ~~~~~~~~~~~~~~~~ diff --git a/xarray/backends/plugins.py b/xarray/backends/plugins.py index 979d49233aa..374383f55c8 100644 --- a/xarray/backends/plugins.py +++ b/xarray/backends/plugins.py @@ -104,7 +104,7 @@ def build_engines(entrypoints) -> dict[str, BackendEntrypoint]: @functools.lru_cache(maxsize=1) -def list_engines() -> Mapping[str, BackendEntrypoint]: +def list_engines() -> dict[str, BackendEntrypoint]: """ Return a dictionary of available engines and their BackendEntrypoint objects. From 0fdff0c87a63b5d5c25cbbdad2e743002630dbfc Mon Sep 17 00:00:00 2001 From: Jessica Scheick Date: Thu, 13 Oct 2022 15:50:49 -0400 Subject: [PATCH 29/32] actually put release notes in right place --- doc/whats-new.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 5ffe04df2c5..4785b45ec01 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -76,6 +76,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 ~~~~~~~~~~~~~~~~ @@ -210,10 +215,6 @@ New Features By `Tom White `_. - Allow string formatting of scalar DataArrays. (:pull:`5981`) By `fmaussion `_. -- 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 `_. Bug fixes ~~~~~~~~~ From 6f8878972722fb77b96f74894aeaff5c2656f7fa Mon Sep 17 00:00:00 2001 From: dcherian Date: Mon, 17 Oct 2022 09:31:43 -0600 Subject: [PATCH 30/32] Fix whats-new --- doc/whats-new.rst | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 7ccb9ea4525..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 ~~~~~~~~~~~~~~~~ @@ -118,16 +123,6 @@ Bug fixes - Support for open_dataset backends that return datasets containing multi-indexes (:issue:`7139`, :pull:`7150`) By `Lukas Bindreiter `_. -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 -~~~~~~~~~~~~~~~~ .. _whats-new.2022.09.0: From fdd13460ea475f57b3bfce7c1be87fe5d3ceac05 Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Mon, 17 Oct 2022 09:33:09 -0600 Subject: [PATCH 31/32] Apply suggestions from code review Co-authored-by: Mick --- xarray/backends/common.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/xarray/backends/common.py b/xarray/backends/common.py index 0cbdc29794c..e2faef481b6 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -389,9 +389,9 @@ class BackendEntrypoint: available: ClassVar[bool] = True - open_dataset_parameters: tuple | None = None - description: str = "" - url: str = "" + open_dataset_parameters: ClassVar[tuple | None] = None + description: ClassVar[str] = "" + url: ClassVar[str] = "" def __repr__(self) -> str: txt = f"<{type(self).__name__}>" From bf5ad18044fcd00bdf85a143ef8217f019419c4f Mon Sep 17 00:00:00 2001 From: dcherian Date: Mon, 17 Oct 2022 10:04:23 -0600 Subject: [PATCH 32/32] Revert "Apply suggestions from code review" This reverts commit fdd13460ea475f57b3bfce7c1be87fe5d3ceac05. --- xarray/backends/common.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/xarray/backends/common.py b/xarray/backends/common.py index e2faef481b6..0cbdc29794c 100644 --- a/xarray/backends/common.py +++ b/xarray/backends/common.py @@ -389,9 +389,9 @@ class BackendEntrypoint: available: ClassVar[bool] = True - open_dataset_parameters: ClassVar[tuple | None] = None - description: ClassVar[str] = "" - url: ClassVar[str] = "" + open_dataset_parameters: tuple | None = None + description: str = "" + url: str = "" def __repr__(self) -> str: txt = f"<{type(self).__name__}>"