From dac661d8e1aaae17f07cdf1624189267f5bf287c Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Wed, 9 Jul 2025 07:41:32 -0700 Subject: [PATCH 1/3] Fix docs build. A couple of xarray-tutorial paths have changed. --- xarray/core/dataarray.py | 2 +- xarray/core/dataset.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 0bfb0b7ab1c..73b0eb19a64 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -6915,7 +6915,7 @@ def groupby( :ref:`groupby` Users guide explanation of how to group and bin data. - :doc:`xarray-tutorial:intermediate/01-high-level-computation-patterns` + :doc:`xarray-tutorial:intermediate/computation/01-high-level-computation-patterns` Tutorial on :py:func:`~xarray.DataArray.Groupby` for windowed computation :doc:`xarray-tutorial:fundamentals/03.2_groupby_with_xarray` diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index 6de626a159b..6a2fe7f4adc 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -9941,7 +9941,7 @@ def groupby( :ref:`groupby` Users guide explanation of how to group and bin data. - :doc:`xarray-tutorial:intermediate/01-high-level-computation-patterns` + :doc:`xarray-tutorial:intermediate/computation/01-high-level-computation-patterns` Tutorial on :py:func:`~xarray.Dataset.Groupby` for windowed computation. :doc:`xarray-tutorial:fundamentals/03.2_groupby_with_xarray` From 0bda19a33439c7fa47b8486f5fa801851b5eff29 Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Wed, 9 Jul 2025 08:00:04 -0700 Subject: [PATCH 2/3] Update Custom Indexes section in api.rst --- doc/api-hidden.rst | 16 ---------- doc/api.rst | 46 +++++++++++++++++++++++------ xarray/core/coordinate_transform.py | 5 ++-- xarray/core/indexes.py | 5 ++-- 4 files changed, 43 insertions(+), 29 deletions(-) diff --git a/doc/api-hidden.rst b/doc/api-hidden.rst index 9a6037cf3c4..5b9fa70d6b7 100644 --- a/doc/api-hidden.rst +++ b/doc/api-hidden.rst @@ -515,22 +515,6 @@ CFTimeIndex.values CFTimeIndex.year - Index.from_variables - Index.concat - Index.stack - Index.unstack - Index.create_variables - Index.should_add_coord_to_array - Index.to_pandas_index - Index.isel - Index.sel - Index.join - Index.reindex_like - Index.equals - Index.roll - Index.rename - Index.copy - indexes.RangeIndex.start indexes.RangeIndex.stop indexes.RangeIndex.step diff --git a/doc/api.rst b/doc/api.rst index c578919dcce..b57ba90a7d5 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -1571,12 +1571,22 @@ Custom Indexes ============== .. currentmodule:: xarray +Default, pandas-backed indexes built-in to Xarray: + +.. autosummary:: + :toctree: generated/ + + indexes.PandasIndex + indexes.PandasMultiIndex + + +More complex indexes built-in to Xarray: + .. autosummary:: :toctree: generated/ CFTimeIndex indexes.RangeIndex - indexes.CoordinateTransformIndex indexes.NDPointIndex Creating custom indexes @@ -1590,12 +1600,38 @@ Creating custom indexes indexes.RangeIndex.arange indexes.RangeIndex.linspace +The Index base class for building custom indexes: + +.. autosummary:: + :toctree: generated/ + + Index.from_variables + Index.concat + Index.stack + Index.unstack + Index.create_variables + Index.should_add_coord_to_array + Index.to_pandas_index + Index.isel + Index.sel + Index.join + Index.reindex_like + Index.equals + Index.roll + Index.rename + Index.copy + Building custom indexes ----------------------- + +These classes are building blocks for more complex Indexes: + .. autosummary:: :toctree: generated/ indexes.CoordinateTransform + indexes.CoordinateTransformIndex + indexes.NDPointIndex Tutorial ======== @@ -1702,14 +1738,6 @@ Advanced API .. Missing: .. ``DataTree.set_close`` -Default, pandas-backed indexes built-in Xarray: - -.. autosummary:: - :toctree: generated/ - - indexes.PandasIndex - indexes.PandasMultiIndex - These backends provide a low-level interface for lazily loading data from external file-formats or protocols, and can be manually invoked to create arguments for the ``load_store`` and ``dump_to_store`` Dataset methods: diff --git a/xarray/core/coordinate_transform.py b/xarray/core/coordinate_transform.py index d1e434c3d64..02cbbc11caa 100644 --- a/xarray/core/coordinate_transform.py +++ b/xarray/core/coordinate_transform.py @@ -9,8 +9,9 @@ class CoordinateTransform: """Abstract coordinate transform with dimension & coordinate names. - EXPERIMENTAL (not ready for public use yet). - + .. caution:: + This API is experimental and subject to change. Please report any bugs or surprising + behaviour you encounter. """ coord_names: tuple[Hashable, ...] diff --git a/xarray/core/indexes.py b/xarray/core/indexes.py index 9684f371e00..c233c6911e4 100644 --- a/xarray/core/indexes.py +++ b/xarray/core/indexes.py @@ -1455,14 +1455,15 @@ def rename(self, name_dict, dims_dict): class CoordinateTransformIndex(Index): """Helper class for creating Xarray indexes based on coordinate transforms. - EXPERIMENTAL (not ready for public use yet). - - wraps a :py:class:`CoordinateTransform` instance - takes care of creating the index (lazy) coordinates - supports point-wise label-based selection - supports exact alignment only, by comparing indexes based on their transform (not on their explicit coordinate labels) + .. caution:: + This API is experimental and subject to change. Please report any bugs or surprising + behaviour you encounter. """ transform: CoordinateTransform From e05f0858955b24305e88d11b7b243937186926c1 Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Wed, 9 Jul 2025 09:50:31 -0700 Subject: [PATCH 3/3] Move user-facing API up to Indexes section --- doc/api.rst | 72 +++++++++++++++++++++++++++++------------------------ 1 file changed, 39 insertions(+), 33 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index b57ba90a7d5..f4a6dc6677d 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -978,6 +978,40 @@ and DataTree objects, respectively. core.coordinates.DataArrayCoordinates core.coordinates.DataTreeCoordinates +Indexes +======= + +Default, pandas-backed indexes built-in to Xarray: + +.. autosummary:: + :toctree: generated/ + + indexes.PandasIndex + indexes.PandasMultiIndex + + +More complex indexes built-in to Xarray: + +.. autosummary:: + :toctree: generated/ + + CFTimeIndex + indexes.RangeIndex + indexes.NDPointIndex + + +Creating indexes +---------------- +.. autosummary:: + :toctree: generated/ + + cftime_range + date_range + date_range_like + indexes.RangeIndex.arange + indexes.RangeIndex.linspace + + Universal functions =================== @@ -1571,35 +1605,18 @@ Custom Indexes ============== .. currentmodule:: xarray -Default, pandas-backed indexes built-in to Xarray: - -.. autosummary:: - :toctree: generated/ - - indexes.PandasIndex - indexes.PandasMultiIndex - +Building custom indexes +----------------------- -More complex indexes built-in to Xarray: +These classes are building blocks for more complex Indexes: .. autosummary:: :toctree: generated/ - CFTimeIndex - indexes.RangeIndex + indexes.CoordinateTransform + indexes.CoordinateTransformIndex indexes.NDPointIndex -Creating custom indexes ------------------------ -.. autosummary:: - :toctree: generated/ - - cftime_range - date_range - date_range_like - indexes.RangeIndex.arange - indexes.RangeIndex.linspace - The Index base class for building custom indexes: .. autosummary:: @@ -1621,17 +1638,6 @@ The Index base class for building custom indexes: Index.rename Index.copy -Building custom indexes ------------------------ - -These classes are building blocks for more complex Indexes: - -.. autosummary:: - :toctree: generated/ - - indexes.CoordinateTransform - indexes.CoordinateTransformIndex - indexes.NDPointIndex Tutorial ========