Repository navigation
Open
Labels
Description
Is your feature request related to a problem?
The BackendEntrypoint class at
xarray/xarray/backends/common.py
Lines 660 to 738 in 1424972
| class BackendEntrypoint: | |
| """ | |
| ``BackendEntrypoint`` is a class container and it is the main interface | |
| for the backend plugins, see :ref:`RST backend_entrypoint`. | |
| It shall implement: | |
| - ``open_dataset`` method: it shall implement reading from file, variables | |
| decoding and it returns an instance of :py:class:`~xarray.Dataset`. | |
| It shall take in input at least ``filename_or_obj`` argument and | |
| ``drop_variables`` keyword argument. | |
| For more details see :ref:`RST open_dataset`. | |
| - ``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. | |
| - ``open_datatree`` method: it shall implement reading from file, variables | |
| decoding and it returns an instance of :py:class:`~datatree.DataTree`. | |
| It shall take in input at least ``filename_or_obj`` argument. The | |
| implementation of this method is not mandatory. For more details see | |
| <reference to open_datatree documentation>. | |
| Attributes | |
| ---------- | |
| open_dataset_parameters : tuple, default: None | |
| A list of ``open_dataset`` method parameters. | |
| The setting of this attribute is not mandatory. | |
| description : str, default: "" | |
| A short string describing the engine. | |
| The setting of this attribute is not mandatory. | |
| url : str, default: "" | |
| A string with the URL to the backend's documentation. | |
| The setting of this attribute is not mandatory. | |
| """ | |
| open_dataset_parameters: ClassVar[tuple | None] = None | |
| description: ClassVar[str] = "" | |
| url: ClassVar[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, | |
| filename_or_obj: str | os.PathLike[Any] | ReadBuffer | AbstractDataStore, | |
| *, | |
| drop_variables: str | Iterable[str] | None = None, | |
| ) -> Dataset: | |
| """ | |
| Backend open_dataset method used by Xarray in :py:func:`~xarray.open_dataset`. | |
| """ | |
| raise NotImplementedError() | |
| def guess_can_open( | |
| self, | |
| filename_or_obj: str | os.PathLike[Any] | ReadBuffer | AbstractDataStore, | |
| ) -> bool: | |
| """ | |
| Backend open_dataset method used by Xarray in :py:func:`~xarray.open_dataset`. | |
| """ | |
| return False | |
| def open_datatree( | |
| self, | |
| filename_or_obj: str | os.PathLike[Any] | ReadBuffer | AbstractDataStore, | |
| *, | |
| drop_variables: str | Iterable[str] | None = None, | |
| ) -> DataTree: | |
| """ | |
| Backend open_datatree method used by Xarray in :py:func:`~xarray.open_datatree`. | |
| """ | |
| raise NotImplementedError() |
open_dataset and open_datatree methods, but not open_dataarray. Currently, someone implementing a BackendEntrypoint to do xarray.open_dataarray(..., engine="<something>") would have to implement open_dataset, and behind the scenes, this could result in a roundtrip xr.DataArray -> xr.Dataset -> xr.DataArray conversion, which can lead to some attributes/state getting lost along the way (xref #3268).
Describe the solution you'd like
Enable open_dataarray to be implemented directly, without a roundtrip conversion to/from xr.Dataset
Describe alternatives you've considered
No response
Activity
dncnmcdougall commentedon Aug 19, 2026
I have just run face first into this.
I am loading parts of a hdf5 file.
What makes this challenging is that the logic of the arguments is different depending on whether I am loading a Dataarray, Dataset or DataTree.
In addition, looking at the code, I see that the
Backend.open_dataset_parametersis used for bothopne_datasetandopen_datatree.It would not be difficult to split this into three options.
The only problem I can foresee is backwards comparability: if a new
Backend.open_dataarrayis introduced, old code usingopen_dataarray(...engine='thing')is secretly usingBackend.open_dataset. So if theopen_datasetandopen_dataarraymethods are different this code will break unexpectedly.But this can be overcome with warnings in client libraries, and giving
open_dataarraya default implementation that throwsNotImplementedErrorand then falling back toopen_datasetor something.Likewise for
Backend.open_datatree_parametersAre there any other design considerations?
Adds open_dataarray to BackendEntrypoint. pydata#10562
Adds open_dataarray to BackendEntrypoint. pydata#10562
Adds open_dataarray to BackendEntrypoint. pydata#10562
Adds open_dataarray to BackendEntrypoint. pydata#10562
Adds open_dataarray to BackendEntrypoint. pydata#10562