DEPR: PeriodIndex.is_full

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jbrockmendel

doc/source/whatsnew/v3.1.0.rst

@@ -97,6 +97,7 @@ Other API changes
 
 Deprecations
 ~~~~~~~~~~~~
+- Deprecated :attr:`PeriodIndex.is_full` (:issue:`64938`)
 - Deprecated :attr:`Timestamp.dayofweek`, :attr:`Timestamp.dayofyear`, :attr:`Timestamp.daysinmonth` in favor of :attr:`Timestamp.day_of_week`, :attr:`Timestamp.day_of_year`, :attr:`Timestamp.days_in_month`, respectively. The same deprecation applies to the corresponding attributes on :class:`Period`, :class:`DatetimeIndex`, :class:`PeriodIndex`, and :attr:`Series.dt` (:issue:`46768`)
 - Deprecated :meth:`.DataFrameGroupBy.agg` and :meth:`.Resampler.agg` unpacking a scalar when the provided ``func`` returns a Series or array of length 1; in the future this will result in the Series or array being in the result. Users should unpack the scalar in ``func`` itself (:issue:`64014`)
 - Deprecated :meth:`ExcelFile.parse`, use :func:`read_excel` instead (:issue:`58247`)

pandas/core/indexes/period.py

@@ -8,6 +8,7 @@
     TYPE_CHECKING,
     Self,
 )
+import warnings
 
 import numpy as np
 
@@ -22,10 +23,12 @@
     to_offset,
 )
 from pandas._libs.tslibs.dtypes import OFFSET_TO_PERIOD_FREQSTR
+from pandas.errors import Pandas4Warning
 from pandas.util._decorators import (
     cache_readonly,
     set_module,
 )
+from pandas.util._exceptions import find_stack_level
 
 from pandas.core.dtypes.common import (
     is_integer,
@@ -567,9 +570,19 @@ def asof_locs(self, where: Index, mask: npt.NDArray[np.bool_]) -> np.ndarray:
     @property
     def is_full(self) -> bool:
         """
-        Returns True if this PeriodIndex is range-like in that all Periods
-        between start and end are present, in order.
+        Returns True if this PeriodIndex is monotonic increasing and has
+        no gaps, allowing duplicates.
+
+        .. deprecated:: 3.1.0
+            PeriodIndex.is_full is deprecated and will be removed in
+            a future version.
         """
+        warnings.warn(
+            "PeriodIndex.is_full is deprecated and will be removed in a "
+            "future version.",
+            Pandas4Warning,
+            stacklevel=find_stack_level(),
+        )
         if len(self) == 0:
             return True
         if not self.is_monotonic_increasing:

pandas/tests/indexes/period/methods/test_is_full.py

@@ -1,23 +1,38 @@
 import pytest
 
+from pandas.errors import Pandas4Warning
+
 from pandas import PeriodIndex
+import pandas._testing as tm
+
+msg = "PeriodIndex.is_full is deprecated"
 
 
-def test_is_full():
-    index = PeriodIndex([2005, 2007, 2009], freq="Y")
-    assert not index.is_full
+class TestIsFull:
+    def test_is_full(self):
+        index = PeriodIndex([2005, 2007, 2009], freq="Y")
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            assert not index.is_full
 
-    index = PeriodIndex([2005, 2006, 2007], freq="Y")
-    assert index.is_full
+        index = PeriodIndex([2005, 2006, 2007], freq="Y")
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            assert index.is_full
 
-    index = PeriodIndex([2005, 2005, 2007], freq="Y")
-    assert not index.is_full
+        index = PeriodIndex([2005, 2005, 2007], freq="Y")
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            assert not index.is_full
 
-    index = PeriodIndex([2005, 2005, 2006], freq="Y")
-    assert index.is_full
+        index = PeriodIndex([2005, 2005, 2006], freq="Y")
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            assert index.is_full
 
-    index = PeriodIndex([2006, 2005, 2005], freq="Y")
-    with pytest.raises(ValueError, match="Index is not monotonic"):
-        index.is_full
+    def test_is_full_not_monotonic(self):
+        index = PeriodIndex([2006, 2005, 2005], freq="Y")
+        with pytest.raises(ValueError, match="Index is not monotonic"):
+            with tm.assert_produces_warning(Pandas4Warning, match=msg):
+                index.is_full
 
-    assert index[:0].is_full
+    def test_is_full_empty(self):
+        index = PeriodIndex([], freq="Y")
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            assert index.is_full