From b704e9108a926714570b111bf6b485483152778f Mon Sep 17 00:00:00 2001 From: sshekhar563 Date: Mon, 22 Dec 2025 15:53:54 +0530 Subject: [PATCH 1/6] Add _repr_inline_ documentation to custom index guide Closes #11036 - Add new 'Custom representation' section explaining _repr_inline_ - Document method signature with max_width parameter - Include code example and real-world examples from RangeIndex/NDPointIndex - Update RasterIndex example to include _repr_inline_ implementation --- doc/internals/how-to-create-custom-index.rst | 41 ++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/doc/internals/how-to-create-custom-index.rst b/doc/internals/how-to-create-custom-index.rst index 2002915ac84..c475e7bef54 100644 --- a/doc/internals/how-to-create-custom-index.rst +++ b/doc/internals/how-to-create-custom-index.rst @@ -128,6 +128,43 @@ e.g., a kd-tree object may not be easily indexed. If ``Index.isel()`` is not implemented, the index in just dropped in the DataArray or Dataset resulting from the selection. +Custom representation +--------------------- + +When a :py:class:`Dataset` or :py:class:`DataArray` is displayed, Xarray shows +a summary of its indexes. By default, the base :py:class:`Index` class returns +just the class name. You can customize this by implementing the +:py:meth:`Index._repr_inline_` method, which should return a short, single-line +string representation of the index. + +The ``_repr_inline_`` method receives a ``max_width`` argument (number of +characters) that can be used to truncate the output if needed: + +.. code-block:: python + + class MyIndex(Index): + def __init__(self, data): + self._data = data + + def _repr_inline_(self, max_width: int) -> str: + # Return a concise representation + return f"MyIndex (size={len(self._data)})" + +Here are some examples from Xarray's built-in indexes: + +- ``RangeIndex`` returns: ``RangeIndex (start=0, stop=1, step=0.1)`` +- ``NDPointIndex`` returns: ``NDPointIndex (KDTree)`` + +This representation appears in the indexes section when displaying a Dataset or +DataArray: + +.. code-block:: none + + + ... + Indexes: + x MyIndex (size=10) + Alignment --------- @@ -198,6 +235,10 @@ regularly spaced 2-dimensional data) that internally relies on two return merge_sel_results(results) + def _repr_inline_(self, max_width: int) -> str: + dims = [idx.dim for idx in self._xy_indexes.values()] + return f"RasterIndex (dims={dims})" + This basic index only supports label-based selection. Providing a full-featured index by implementing the other ``Index`` methods should be pretty From 7a29216c0a1c2e448029bf10e9726278e88d6ba2 Mon Sep 17 00:00:00 2001 From: sshekhar563 Date: Tue, 23 Dec 2025 12:26:27 +0530 Subject: [PATCH 2/6] Address reviewer comments: use class name dynamically, jupyter-execute block, improve phrasing --- doc/internals/how-to-create-custom-index.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/internals/how-to-create-custom-index.rst b/doc/internals/how-to-create-custom-index.rst index c475e7bef54..484290adf42 100644 --- a/doc/internals/how-to-create-custom-index.rst +++ b/doc/internals/how-to-create-custom-index.rst @@ -138,9 +138,12 @@ just the class name. You can customize this by implementing the string representation of the index. The ``_repr_inline_`` method receives a ``max_width`` argument (number of -characters) that can be used to truncate the output if needed: +characters) that indicates the available space for the representation. If the +representation exceeds this width, it should be truncated: -.. code-block:: python +.. jupyter-execute:: + + from xarray import Index class MyIndex(Index): def __init__(self, data): @@ -148,7 +151,7 @@ characters) that can be used to truncate the output if needed: def _repr_inline_(self, max_width: int) -> str: # Return a concise representation - return f"MyIndex (size={len(self._data)})" + return f"{self.__class__.__name__} (size={len(self._data)})" Here are some examples from Xarray's built-in indexes: @@ -237,7 +240,7 @@ regularly spaced 2-dimensional data) that internally relies on two def _repr_inline_(self, max_width: int) -> str: dims = [idx.dim for idx in self._xy_indexes.values()] - return f"RasterIndex (dims={dims})" + return f"{self.__class__.__name__} (dims={dims})" This basic index only supports label-based selection. Providing a full-featured From 0a1fe1073be2831a443eeaf845756cd4ed36e86b Mon Sep 17 00:00:00 2001 From: sshekhar563 Date: Wed, 24 Dec 2025 12:18:57 +0530 Subject: [PATCH 3/6] Address dcherian's review: use type() instead of __class__, clarify max_width responsibility --- doc/internals/how-to-create-custom-index.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/internals/how-to-create-custom-index.rst b/doc/internals/how-to-create-custom-index.rst index 484290adf42..61382e539ca 100644 --- a/doc/internals/how-to-create-custom-index.rst +++ b/doc/internals/how-to-create-custom-index.rst @@ -140,6 +140,7 @@ string representation of the index. The ``_repr_inline_`` method receives a ``max_width`` argument (number of characters) that indicates the available space for the representation. If the representation exceeds this width, it should be truncated: +Output of the method must not exceed this width. .. jupyter-execute:: @@ -151,7 +152,7 @@ representation exceeds this width, it should be truncated: def _repr_inline_(self, max_width: int) -> str: # Return a concise representation - return f"{self.__class__.__name__} (size={len(self._data)})" + return f"{type(self).__name__} (size={len(self._data)})" Here are some examples from Xarray's built-in indexes: @@ -240,7 +241,7 @@ regularly spaced 2-dimensional data) that internally relies on two def _repr_inline_(self, max_width: int) -> str: dims = [idx.dim for idx in self._xy_indexes.values()] - return f"{self.__class__.__name__} (dims={dims})" + return f"{type(self).__name__} (dims={dims})" This basic index only supports label-based selection. Providing a full-featured From a061448efca2e0fa03b200aca642763d26d75f34 Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Wed, 24 Dec 2025 08:31:25 -0700 Subject: [PATCH 4/6] Apply suggestion from @jsignell Co-authored-by: Julia Signell --- doc/internals/how-to-create-custom-index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/internals/how-to-create-custom-index.rst b/doc/internals/how-to-create-custom-index.rst index 61382e539ca..ce3435d3292 100644 --- a/doc/internals/how-to-create-custom-index.rst +++ b/doc/internals/how-to-create-custom-index.rst @@ -138,8 +138,8 @@ just the class name. You can customize this by implementing the string representation of the index. The ``_repr_inline_`` method receives a ``max_width`` argument (number of -characters) that indicates the available space for the representation. If the -representation exceeds this width, it should be truncated: +characters) that indicates the available space for the representation. The +output of the method must not exceed this width. Output of the method must not exceed this width. .. jupyter-execute:: From 3773db6565fe4b316ef2d63c853dd050e59026c0 Mon Sep 17 00:00:00 2001 From: Siddhant Shekhar Date: Wed, 24 Dec 2025 21:14:18 +0530 Subject: [PATCH 5/6] Update doc/internals/how-to-create-custom-index.rst Co-authored-by: Deepak Cherian --- doc/internals/how-to-create-custom-index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/internals/how-to-create-custom-index.rst b/doc/internals/how-to-create-custom-index.rst index ce3435d3292..805ed13f780 100644 --- a/doc/internals/how-to-create-custom-index.rst +++ b/doc/internals/how-to-create-custom-index.rst @@ -156,8 +156,8 @@ Output of the method must not exceed this width. Here are some examples from Xarray's built-in indexes: -- ``RangeIndex`` returns: ``RangeIndex (start=0, stop=1, step=0.1)`` -- ``NDPointIndex`` returns: ``NDPointIndex (KDTree)`` +- :py:class:`~xarray.indexes.RangeIndex` returns: ``RangeIndex (start=0, stop=1, step=0.1)`` +- :py:class:`~xarray.indexes.NDPointIndex` returns: ``NDPointIndex (KDTree)`` This representation appears in the indexes section when displaying a Dataset or DataArray: From 23f85f28d6aef4de02ae9d3f48eba51174b7af39 Mon Sep 17 00:00:00 2001 From: sshekhar563 Date: Wed, 24 Dec 2025 21:48:39 +0530 Subject: [PATCH 6/6] Address reviewer comments: fix max_width description and add cross-references --- doc/internals/how-to-create-custom-index.rst | 27 +++++++++----------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/doc/internals/how-to-create-custom-index.rst b/doc/internals/how-to-create-custom-index.rst index 805ed13f780..5c4437274f5 100644 --- a/doc/internals/how-to-create-custom-index.rst +++ b/doc/internals/how-to-create-custom-index.rst @@ -140,10 +140,19 @@ string representation of the index. The ``_repr_inline_`` method receives a ``max_width`` argument (number of characters) that indicates the available space for the representation. The output of the method must not exceed this width. -Output of the method must not exceed this width. + +Here are some examples from Xarray's built-in indexes: + +- :py:class:`~xarray.indexes.RangeIndex` returns: ``RangeIndex (start=0, stop=1, step=0.1)`` +- :py:class:`~xarray.indexes.NDPointIndex` returns: ``NDPointIndex (KDTree)`` + +This representation appears in the indexes section when displaying a Dataset or +DataArray: .. jupyter-execute:: + import numpy as np + import xarray as xr from xarray import Index class MyIndex(Index): @@ -154,20 +163,8 @@ Output of the method must not exceed this width. # Return a concise representation return f"{type(self).__name__} (size={len(self._data)})" -Here are some examples from Xarray's built-in indexes: - -- :py:class:`~xarray.indexes.RangeIndex` returns: ``RangeIndex (start=0, stop=1, step=0.1)`` -- :py:class:`~xarray.indexes.NDPointIndex` returns: ``NDPointIndex (KDTree)`` - -This representation appears in the indexes section when displaying a Dataset or -DataArray: - -.. code-block:: none - - - ... - Indexes: - x MyIndex (size=10) + # Demonstrate how it looks in a DataArray + xr.DataArray(np.arange(10), dims="x").set_xindex("x", MyIndex) Alignment ---------