CFTimeIndex calendar in repr

doc/whats-new.rst

@@ -25,6 +25,10 @@ Breaking changes
 
 New Features
 ~~~~~~~~~~~~
+- Build CFTimeIndex.__repr__ explicitly as pandas.Index. Add ``calendar`` as a new
+  property for ``CFTimeIndex`` and show in ``calendar`` and ``length`` in
+  ``CFTimeIndex.__repr__`` (:issue:`2416`, :pull:`4092`)
+  `Aaron Spring <https://github.com/aaronspring>`
 
 
 Bug fixes
@@ -173,7 +177,6 @@ Enhancements
   (:pull:`3905`)
   By `Maximilian Roos <https://github.com/max-sixty>`_
 
-
 Bug fixes
 ~~~~~~~~~
 - Fix errors combining attrs in :py:func:`open_mfdataset` (:issue:`4009`, :pull:`4173`)

xarray/coding/cftimeindex.py

@@ -50,6 +50,8 @@
 from xarray.core.utils import is_scalar
 
 from ..core.common import _contains_cftime_datetimes
+from ..core.formatting import format_times
+from ..core.options import OPTIONS
 from .times import _STANDARD_CALENDARS, cftime_to_nptime, infer_calendar_name
 
 
@@ -259,6 +261,54 @@ def __new__(cls, data, name=None):
         result._cache = {}
         return result
 
+    def __repr__(self):
+        """
+        Return a string representation for this object.
+        """
+        klass_name = type(self).__name__
+        display_width = OPTIONS["display_width"]
+        offset = len(klass_name) + 2
+        ITEMS_IN_REPR_MAX = 100
+
+        if len(self) <= ITEMS_IN_REPR_MAX:
+            datastr = format_times(
+                self.values, display_width, offset=offset, first_row_offset=0
+            )
+        else:
+            SHOW_ITEMS_FRONT_END = 10
+            front_str = format_times(
+                self.values[:SHOW_ITEMS_FRONT_END],
+                display_width,
+                offset=offset,
+                first_row_offset=0,
+                last_row_end=",",
+            )
+            end_str = format_times(
+                self.values[-SHOW_ITEMS_FRONT_END:],
+                display_width,
+                offset=offset,
+                first_row_offset=offset,
+            )
+            datastr = "\n".join([front_str, f"{' '*offset}...", end_str])
+
+        attrs = {
+            "dtype": f"'{self.dtype}'",
+            "length": f"{len(self)}",
+            "calendar": f"'{self.calendar}'",
+        }
+        attrs_str = [f"{k}={v}" for k, v in attrs.items()]
+        attrs_str = f",{' '}".join(attrs_str)
+        # oneliner only if smaller than display_width
+        full_repr_str = f"{klass_name}([{datastr}], {attrs_str})"
+        if len(full_repr_str) <= display_width:
+            return full_repr_str
+        else:
+            # if attrs_str too long, one per line
+            if len(attrs_str) >= display_width - offset:
+                attrs_str = attrs_str.replace(",", f",\n{' '*(offset-2)}")
+            full_repr_str = f"{klass_name}([{datastr}],\n{' '*(offset-1)}{attrs_str})"
+            return full_repr_str
+
     def _partial_date_slice(self, resolution, parsed):
         """Adapted from
         pandas.tseries.index.DatetimeIndex._partial_date_slice
@@ -582,6 +632,12 @@ def asi8(self):
             dtype=np.int64,
         )
 
+    @property
+    def calendar(self):
+        from .times import infer_calendar_name
+
+        return infer_calendar_name(self)
+
     def _round_via_method(self, freq, method):
         """Round dates using a specified method."""
         from .cftime_offsets import CFTIME_TICKS, to_offset

xarray/core/formatting.py

@@ -216,6 +216,37 @@ def format_array_flat(array, max_width: int):
     return pprint_str
 
 
+def format_row(times, indent=0, separator=", ", row_end=",\n"):
+    """Format a single row from format_times."""
+    return indent * " " + separator.join(map(str, times)) + row_end
+
+
+def format_times(
+    index,
+    max_width,
+    offset,
+    separator=", ",
+    first_row_offset=0,
+    intermediate_row_end=",\n",
+    last_row_end="",
+):
+    """Format values of cftimeindex as pd.Index."""
+    CFTIME_REPR_LENGTH = 19
+    n_per_row = max(max_width // (CFTIME_REPR_LENGTH + len(separator)), 1)
+    n_rows = int(np.ceil(len(index) / n_per_row))
+
+    representation = ""
+    for row in range(n_rows):
+        indent = first_row_offset if row == 0 else offset
+        row_end = last_row_end if row == n_rows - 1 else intermediate_row_end
+        times_for_row = index[row * n_per_row : (row + 1) * n_per_row]
+        representation = representation + format_row(
+            times_for_row, indent=indent, separator=separator, row_end=row_end
+        )
+
+    return representation
+
+
 _KNOWN_TYPE_REPRS = {np.ndarray: "np.ndarray"}
 with contextlib.suppress(ImportError):
     import sparse

xarray/tests/test_cftimeindex.py

@@ -13,6 +13,7 @@
     assert_all_valid_date_type,
     parse_iso8601,
 )
+from xarray.core.options import OPTIONS
 from xarray.tests import assert_array_equal, assert_identical
 
 from . import raises_regex, requires_cftime, requires_cftime_1_1_0
@@ -884,6 +885,135 @@ def test_cftimeindex_shift_invalid_freq():
         index.shift(1, 1)
 
 
+@requires_cftime
+@pytest.mark.parametrize(
+    ("calendar", "expected"),
+    [
+        ("noleap", "noleap"),
+        ("365_day", "noleap"),
+        ("360_day", "360_day"),
+        ("julian", "julian"),
+        ("gregorian", "gregorian"),
+        ("proleptic_gregorian", "proleptic_gregorian"),
+    ],
+)
+def test_cftimeindex_calendar_property(calendar, expected):
+    index = xr.cftime_range(start="2000", periods=3, calendar=calendar)
+    assert index.calendar == expected
+
+
+@requires_cftime
+@pytest.mark.parametrize(
+    ("calendar", "expected"),
+    [
+        ("noleap", "noleap"),
+        ("365_day", "noleap"),
+        ("360_day", "360_day"),
+        ("julian", "julian"),
+        ("gregorian", "gregorian"),
+        ("proleptic_gregorian", "proleptic_gregorian"),
+    ],
+)
+def test_cftimeindex_calendar_repr(calendar, expected):
+    """Test that cftimeindex has calendar property in repr."""
+    index = xr.cftime_range(start="2000", periods=3, calendar=calendar)
+    repr_str = index.__repr__()
+    assert f" calendar='{expected}'" in repr_str
+    assert "2000-01-01 00:00:00, 2000-01-02 00:00:00" in repr_str
+
+
+@requires_cftime
+@pytest.mark.parametrize("periods", [2, 40])
+def test_cftimeindex_periods_repr(periods):
+    """Test that cftimeindex has periods property in repr."""
+    index = xr.cftime_range(start="2000", periods=periods)
+    repr_str = index.__repr__()
+    assert f" length={periods}" in repr_str
+
+
+@requires_cftime
+@pytest.mark.parametrize("periods", [2, 3, 4, 100, 101])
+def test_cftimeindex_repr_formatting(periods):
+    """Test that cftimeindex.__repr__ is formatted as pd.Index.__repr__."""
+    index = xr.cftime_range(start="2000", periods=periods)
+    repr_str = index.__repr__()
+    # check for commata
+    assert "2000-01-01 00:00:00, 2000-01-02 00:00:00" in repr_str
+    # check oneline repr
+    if len(repr_str) <= OPTIONS["display_width"]:
+        assert "\n" not in repr_str
+    # if time items in first line only
+    elif periods * 19 < OPTIONS["display_width"]:
+        assert "\n" in repr_str
+    else:
+        # check for times have same indent
+        lines = repr_str.split("\n")
+        firststr = "2000"
+        assert lines[0].find(firststr) == lines[1].find(firststr)
+        # check for attrs line has one less indent than times
+        assert lines[-1].find("dtype") + 1 == lines[0].find(firststr)
+    # check for ... separation dots
+    if periods > 100:
+        assert "..." in repr_str
+
+
+@requires_cftime
+@pytest.mark.parametrize("display_width", [40, 80, 100])
+@pytest.mark.parametrize("periods", [2, 3, 4, 100, 101])
+def test_cftimeindex_repr_formatting_width(periods, display_width):
+    """Test that cftimeindex is sensitive to OPTIONS['display_width']."""
+    index = xr.cftime_range(start="2000", periods=periods)
+    len_intro_str = len("CFTimeIndex(")
+    with xr.set_options(display_width=display_width):
+        repr_str = index.__repr__()
+        splitted = repr_str.split("\n")
+        for i, s in enumerate(splitted):
+            # check that lines not longer than OPTIONS['display_width']
+            assert len(s) <= display_width, f"{len(s)} {s} {display_width}"
+            if i > 0:
+                # check for initial spaces
+                assert s[:len_intro_str] == " " * len_intro_str
+
+
+@requires_cftime
+@pytest.mark.parametrize("periods", [22, 50, 100])
+def test_cftimeindex_repr_101_shorter(periods):
+    index_101 = xr.cftime_range(start="2000", periods=101)
+    index_periods = xr.cftime_range(start="2000", periods=periods)
+    index_101_repr_str = index_101.__repr__()
+    index_periods_repr_str = index_periods.__repr__()
+    assert len(index_101_repr_str) < len(index_periods_repr_str)
+
+
+@requires_cftime
+@pytest.mark.parametrize("periods", [3, 4, 100, 101])
+def test_cftimeindex_repr_compare_pandasIndex(periods):
+    """Test xr.cftimeindex.__repr__ against previous pandas.Index.__repr__. Small adjustments to similarize visuals like indent."""
+    cfindex = xr.cftime_range(start="2000", periods=periods)
+    pdindex = pd.Index(cfindex)
+    cfindex_repr_str = cfindex.__repr__()
+    pdindex_repr_str = pdindex.__repr__()
+    pdindex_repr_str = pdindex_repr_str.replace("Index", "CFTimeIndex")
+    pdindex_repr_str = pdindex_repr_str.replace(f"\n{' '*7}", f"\n{' '*13}")
+    if periods <= 3:
+        # pd.Index doesnt worry about display_width
+        cfindex_repr_str = cfindex_repr_str.replace("\n", "").replace(" " * 12, " ")
+    if periods > 3:
+        # indent similarly
+        pdindex_repr_str = pdindex_repr_str.replace("dtype", f"{' '*6}dtype")
+    # add length attribute if many periods
+    if periods <= 100:
+        lengthstr = f"length={periods}, "
+    else:
+        lengthstr = ""
+    pdindex_repr_str = pdindex_repr_str.replace(
+        ")", f", {lengthstr}calendar='gregorian')"
+    )
+    assert pdindex_repr_str == cfindex_repr_str, print(
+        f"pandas:\n{pdindex_repr_str}\n vs.\ncftime: \n{cfindex_repr_str}"
+    )
+
+
 @requires_cftime
 def test_parse_array_of_cftime_strings():
     from cftime import DatetimeNoLeap