API: IncompatibleFrequency subclass TypeError (#61875)

Author: jbrockmendel

ci/code_checks.sh

@@ -74,6 +74,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Series.dt PR01" `# Accessors are implemented as classes, but we do not document the Parameters section` \
         -i "pandas.Period.freq GL08" \
         -i "pandas.Period.ordinal GL08" \
+        -i "pandas.errors.IncompatibleFrequency SA01,SS06,EX01" \
         -i "pandas.core.groupby.DataFrameGroupBy.plot PR02" \
         -i "pandas.core.groupby.SeriesGroupBy.plot PR02" \
         -i "pandas.core.resample.Resampler.quantile PR01,PR07" \

doc/source/reference/testing.rst

@@ -36,6 +36,7 @@ Exceptions and warnings
    errors.DuplicateLabelError
    errors.EmptyDataError
    errors.IncompatibilityWarning
+   errors.IncompatibleFrequency
    errors.IndexingError
    errors.InvalidColumnName
    errors.InvalidComparison

doc/source/whatsnew/v3.0.0.rst

@@ -414,6 +414,7 @@ Other API changes
 - Index set operations (like union or intersection) will now ignore the dtype of
   an empty ``RangeIndex`` or empty ``Index`` with object dtype when determining
   the dtype of the resulting Index (:issue:`60797`)
+- :class:`IncompatibleFrequency` now subclasses ``TypeError`` instead of ``ValueError``. As a result, joins with mismatched frequencies now cast to object like other non-comparable joins, and arithmetic with indexes with mismatched frequencies align (:issue:`55782`)
 - Comparison operations between :class:`Index` and :class:`Series` now consistently return :class:`Series` regardless of which object is on the left or right (:issue:`36759`)
 - Numpy functions like ``np.isinf`` that return a bool dtype when called on a :class:`Index` object now return a bool-dtype :class:`Index` instead of ``np.ndarray`` (:issue:`52676`)
 

pandas/_libs/tslibs/period.pyi

@@ -15,7 +15,7 @@ from pandas._typing import (
 INVALID_FREQ_ERR_MSG: str
 DIFFERENT_FREQ: str
 
-class IncompatibleFrequency(ValueError): ...
+class IncompatibleFrequency(TypeError): ...
 
 def periodarr_to_dt64arr(
     periodarr: npt.NDArray[np.int64],  # const int64_t[:]

pandas/_libs/tslibs/period.pyx

@@ -1625,7 +1625,11 @@ DIFFERENT_FREQ = ("Input has different freq={other_freq} "
                   "from {cls}(freq={own_freq})")
 
 
-class IncompatibleFrequency(ValueError):
+class IncompatibleFrequency(TypeError):
+    """
+    Raised when trying to compare or operate between Periods with different
+    frequencies.
+    """
     pass
 
 

pandas/core/arrays/datetimelike.py

@@ -544,7 +544,7 @@ def _validate_comparison_value(self, other):
             other = self._scalar_type(other)
             try:
                 self._check_compatible_with(other)
-            except (TypeError, IncompatibleFrequency) as err:
+            except TypeError as err:
                 # e.g. tzawareness mismatch
                 raise InvalidComparison(other) from err
 
@@ -558,7 +558,7 @@ def _validate_comparison_value(self, other):
             try:
                 other = self._validate_listlike(other, allow_object=True)
                 self._check_compatible_with(other)
-            except (TypeError, IncompatibleFrequency) as err:
+            except TypeError as err:
                 if is_object_dtype(getattr(other, "dtype", None)):
                     # We will have to operate element-wise
                     pass

pandas/core/indexes/base.py

@@ -38,7 +38,6 @@
     no_default,
 )
 from pandas._libs.tslibs import (
-    IncompatibleFrequency,
     OutOfBoundsDatetime,
     Timestamp,
     tz_compare,
@@ -3139,7 +3138,7 @@ def _union(self, other: Index, sort: bool | None):
             #  test_union_same_value_duplicated_in_both fails)
             try:
                 return self._outer_indexer(other)[0]
-            except (TypeError, IncompatibleFrequency):
+            except TypeError:
                 # incomparable objects; should only be for object dtype
                 value_list = list(lvals)
 

pandas/errors/__init__.py

@@ -9,6 +9,7 @@
 from pandas._config.config import OptionError
 
 from pandas._libs.tslibs import (
+    IncompatibleFrequency,
     OutOfBoundsDatetime,
     OutOfBoundsTimedelta,
 )
@@ -917,6 +918,7 @@ class InvalidComparison(Exception):
     "DuplicateLabelError",
     "EmptyDataError",
     "IncompatibilityWarning",
+    "IncompatibleFrequency",
     "IndexingError",
     "IntCastingNaNError",
     "InvalidColumnName",

pandas/tests/indexes/period/test_indexing.py

@@ -502,7 +502,7 @@ def test_get_indexer2(self):
         )
 
         msg = "Input has different freq=None from PeriodArray\\(freq=h\\)"
-        with pytest.raises(ValueError, match=msg):
+        with pytest.raises(libperiod.IncompatibleFrequency, match=msg):
             idx.get_indexer(target, "nearest", tolerance="1 minute")
 
         tm.assert_numpy_array_equal(

pandas/tests/indexes/period/test_join.py

@@ -1,7 +1,4 @@
 import numpy as np
-import pytest
-
-from pandas._libs.tslibs import IncompatibleFrequency
 
 from pandas import (
     DataFrame,
@@ -51,8 +48,9 @@ def test_join_does_not_recur(self):
         tm.assert_index_equal(res, expected)
 
     def test_join_mismatched_freq_raises(self):
+        # pre-GH#55782 this raises IncompatibleFrequency
         index = period_range("1/1/2000", "1/20/2000", freq="D")
         index3 = period_range("1/1/2000", "1/20/2000", freq="2D")
-        msg = r".*Input has different freq=2D from Period\(freq=D\)"
-        with pytest.raises(IncompatibleFrequency, match=msg):
-            index.join(index3)
+        result = index.join(index3)
+        expected = index.astype(object).join(index3.astype(object))
+        tm.assert_index_equal(result, expected)