DEPR: Deprecate passing integer-dtype data to PeriodArray/PeriodIndex (pandas-dev#64227)

In a future version, integer data will be treated as period ordinals
instead of year values, consistent with DatetimeArray behavior and the
EA protocol. During the deprecation period, the current behavior is
preserved with a Pandas4Warning.

closes pandas-dev#64227

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

Author: jbrockmendel

doc/source/whatsnew/v3.1.0.rst

@@ -122,6 +122,7 @@ Deprecations
   :meth:`DataFrame.var`, :meth:`DataFrame.sem`, :meth:`DataFrame.sum`,
   :meth:`DataFrame.prod` (and their :class:`Series` equivalents); this will raise in
   a future version of pandas (:issue:`53098`)
+- Deprecated passing integer-dtype data to :class:`PeriodIndex`, :func:`period_array`, and :meth:`PeriodArray._from_sequence`. In a future version, integers will be treated as period ordinals instead of year values. Use strings instead, e.g. ``PeriodIndex(["2020", "2021"], freq="Y")`` (:issue:`64227`)
 - Deprecated the inference of ``datetime64`` dtype from data containing ``datetime.date`` objects when used in comparisons or :meth:`Index.equals` with :class:`DatetimeIndex`. Use :func:`pandas.to_datetime` to explicitly convert to ``datetime64`` instead (:issue:`65056`)
 -
 

pandas/core/arrays/period.py

@@ -302,6 +302,16 @@ def _from_sequence(
             return cls(ordinals, dtype=dtype)
 
         elif arrdata.dtype.kind in "iu":
+            warnings.warn(
+                "Passing integer-dtype data to PeriodArray/PeriodIndex is "
+                "deprecated. In a future version, integer data will be treated "
+                "as period ordinals instead of year values. To retain the "
+                "current behavior, use "
+                "PeriodIndex(data.astype(str), freq=...) or explicitly "
+                "construct Period objects.",
+                Pandas4Warning,
+                stacklevel=find_stack_level(),
+            )
             arr = arrdata.astype(np.int64, copy=False)
             ordinals = libperiod.from_calendar_ordinals(arr, dtype)  # type: ignore[arg-type]
             return cls(ordinals, dtype=dtype)
@@ -1363,13 +1373,6 @@ def period_array(
     ['2017', '2018', 'NaT']
     Length: 3, dtype: period[Y-DEC]
 
-    Integers that look like years are handled
-
-    >>> period_array([2000, 2001, 2002], dtype=PeriodDtype("D"))
-    <PeriodArray>
-    ['2000-01-01', '2001-01-01', '2002-01-01']
-    Length: 3, dtype: period[D]
-
     Datetime-like strings may also be passed
 
     >>> period_array(

pandas/tests/arrays/period/test_constructors.py

@@ -4,6 +4,7 @@
 from pandas._libs.tslibs import iNaT
 from pandas._libs.tslibs.offsets import MonthEnd
 from pandas._libs.tslibs.period import IncompatibleFrequency
+from pandas.errors import Pandas4Warning
 
 import pandas as pd
 import pandas._testing as tm
@@ -18,7 +19,6 @@
     [
         ([pd.Period("2017", "D")], None, [17167]),
         ([pd.Period("2017", "D")], "D", [17167]),
-        ([2017], "D", [17167]),
         (["2017"], "D", [17167]),
         ([pd.Period("2017", "D")], pd.tseries.offsets.Day(), [17167]),
         ([pd.Period("2017", "D"), None], None, [17167, iNaT]),
@@ -111,25 +111,34 @@ def test_period_array_freq_mismatch():
         PeriodArray(arr, dtype=dtype)
 
 
-def test_from_sequence_allows_i8():
-    # GH#64227 this used to be allowed for PeriodIndex and period_array
-    # but not PeriodArray._from_sequence
+def test_from_sequence_int_deprecation():
+    # GH#64227 passing integer data is deprecated; integers will be treated
+    # as period ordinals in a future version instead of year values.
     arr = period_array(["1975", "1976"], dtype="period[D]")
 
-    expected = pd.PeriodIndex([pd.Period(x, freq=arr.freq) for x in arr.asi8]).array
-
-    result1 = pd.PeriodIndex(arr.asi8, dtype=arr.dtype).array
-    result2 = period_array(arr.asi8, dtype=arr.dtype)
-    result3 = PeriodArray._from_sequence(arr.asi8, dtype=arr.dtype)
-    # FIXME: GH#64227 this goes through a different path and gives different behavior
-    # result4 = PeriodArray._from_sequence(arr.asi8.astype(object), dtype=arr.dtype)
-    result5 = PeriodArray._from_sequence(list(arr.asi8), dtype=arr.dtype)
+    # During deprecation, integer inputs are still treated as year values
+    expected_years = pd.PeriodIndex(
+        [pd.Period(x, freq=arr.freq) for x in arr.asi8]
+    ).array
 
-    tm.assert_period_array_equal(result1, expected)
-    tm.assert_period_array_equal(result2, expected)
-    tm.assert_period_array_equal(result3, expected)
-    # tm.assert_period_array_equal(result4, expected)
-    tm.assert_period_array_equal(result5, expected)
+    msg = "Passing integer-dtype data to PeriodArray/PeriodIndex is deprecated"
+    with tm.assert_produces_warning(Pandas4Warning, match=msg):
+        result1 = pd.PeriodIndex(arr.asi8, dtype=arr.dtype).array
+    with tm.assert_produces_warning(Pandas4Warning, match=msg):
+        result2 = period_array(arr.asi8, dtype=arr.dtype)
+    with tm.assert_produces_warning(Pandas4Warning, match=msg):
+        result3 = PeriodArray._from_sequence(arr.asi8, dtype=arr.dtype)
+    with tm.assert_produces_warning(Pandas4Warning, match=msg):
+        result5 = PeriodArray._from_sequence(list(arr.asi8), dtype=arr.dtype)
+
+    tm.assert_period_array_equal(result1, expected_years)
+    tm.assert_period_array_equal(result2, expected_years)
+    tm.assert_period_array_equal(result3, expected_years)
+    tm.assert_period_array_equal(result5, expected_years)
+
+    # Object array path treats integers as ordinals (target behavior, no warning)
+    result4 = PeriodArray._from_sequence(arr.asi8.astype(object), dtype=arr.dtype)
+    tm.assert_period_array_equal(result4, arr)
 
 
 def test_from_td64nat_sequence_raises():

pandas/tests/base/test_conversion.py

@@ -203,7 +203,7 @@ def test_iter_box_period(self):
             "datetime64[ns, US/Central]",
         ),
         (
-            pd.PeriodIndex([2018, 2019], freq="Y"),
+            pd.PeriodIndex(["2018", "2019"], freq="Y"),
             PeriodArray,
             pd.core.dtypes.dtypes.PeriodDtype("Y-DEC"),
         ),

pandas/tests/indexes/multi/test_integrity.py

@@ -80,7 +80,8 @@ def test_values_multiindex_datetimeindex():
 def test_values_multiindex_periodindex():
     # Test to ensure we hit the boxing / nobox part of MI.values
     ints = np.arange(2007, 2012)
-    pidx = pd.PeriodIndex(ints, freq="D")
+    strs = [str(x) for x in ints]
+    pidx = pd.PeriodIndex(strs, freq="D")
 
     idx = MultiIndex.from_arrays([ints, pidx])
     result = idx.values

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

@@ -4,19 +4,19 @@
 
 
 def test_is_full():
-    index = PeriodIndex([2005, 2007, 2009], freq="Y")
+    index = PeriodIndex(["2005", "2007", "2009"], freq="Y")
     assert not index.is_full
 
-    index = PeriodIndex([2005, 2006, 2007], freq="Y")
+    index = PeriodIndex(["2005", "2006", "2007"], freq="Y")
     assert index.is_full
 
-    index = PeriodIndex([2005, 2005, 2007], freq="Y")
+    index = PeriodIndex(["2005", "2005", "2007"], freq="Y")
     assert not index.is_full
 
-    index = PeriodIndex([2005, 2005, 2006], freq="Y")
+    index = PeriodIndex(["2005", "2005", "2006"], freq="Y")
     assert index.is_full
 
-    index = PeriodIndex([2006, 2005, 2005], freq="Y")
+    index = PeriodIndex(["2006", "2005", "2005"], freq="Y")
     with pytest.raises(ValueError, match="Index is not monotonic"):
         index.is_full
 

pandas/tests/indexes/period/test_constructors.py

@@ -247,10 +247,13 @@ def test_constructor_fromarraylike(self):
         tm.assert_index_equal(PeriodIndex(list(idx.values)), idx)
 
         msg = "freq not specified and cannot be inferred"
-        with pytest.raises(ValueError, match=msg):
-            PeriodIndex(idx.asi8)
-        with pytest.raises(ValueError, match=msg):
-            PeriodIndex(list(idx.asi8))
+        depr_msg = "Passing integer-dtype data"
+        with tm.assert_produces_warning(Pandas4Warning, match=depr_msg):
+            with pytest.raises(ValueError, match=msg):
+                PeriodIndex(idx.asi8)
+        with tm.assert_produces_warning(Pandas4Warning, match=depr_msg):
+            with pytest.raises(ValueError, match=msg):
+                PeriodIndex(list(idx.asi8))
 
         msg = "'Period' object is not iterable"
         with pytest.raises(TypeError, match=msg):
@@ -629,7 +632,7 @@ def test_recreate_from_data(self, freq):
         tm.assert_index_equal(idx, org)
 
     def test_map_with_string_constructor(self):
-        raw = [2005, 2007, 2009]
+        raw = ["2005", "2007", "2009"]
         index = PeriodIndex(raw, freq="Y")
 
         expected = Index([str(num) for num in raw])

pandas/tests/indexes/period/test_partial_slicing.py

@@ -14,7 +14,7 @@
 class TestPeriodIndex:
     def test_getitem_periodindex_duplicates_string_slice(self):
         # monotonic
-        idx = PeriodIndex([2000, 2007, 2007, 2009, 2009], freq="Y-JUN")
+        idx = PeriodIndex(["2000", "2007", "2007", "2009", "2009"], freq="Y-JUN")
         ts = Series(np.random.default_rng(2).standard_normal(len(idx)), index=idx)
         original = ts.copy()
 
@@ -25,7 +25,7 @@ def test_getitem_periodindex_duplicates_string_slice(self):
         tm.assert_series_equal(ts, original)
 
         # not monotonic
-        idx = PeriodIndex([2000, 2007, 2007, 2009, 2007], freq="Y-JUN")
+        idx = PeriodIndex(["2000", "2007", "2007", "2009", "2007"], freq="Y-JUN")
         ts = Series(np.random.default_rng(2).standard_normal(len(idx)), index=idx)
 
         result = ts["2007"]

pandas/tests/indexes/period/test_period.py

@@ -130,8 +130,8 @@ def test_is_(self):
         assert not index.is_(index - 0)
 
     def test_index_unique(self):
-        idx = PeriodIndex([2000, 2007, 2007, 2009, 2009], freq="Y-JUN")
-        expected = PeriodIndex([2000, 2007, 2009], freq="Y-JUN")
+        idx = PeriodIndex(["2000", "2007", "2007", "2009", "2009"], freq="Y-JUN")
+        expected = PeriodIndex(["2000", "2007", "2009"], freq="Y-JUN")
         tm.assert_index_equal(idx.unique(), expected)
         assert idx.nunique() == 3
 
@@ -184,7 +184,7 @@ def test_with_multi_index(self):
     def test_map(self):
         # test_map_dictlike generally tests
 
-        index = PeriodIndex([2005, 2007, 2009], freq="Y")
+        index = PeriodIndex(["2005", "2007", "2009"], freq="Y")
         result = index.map(lambda x: x.ordinal)
         exp = Index([x.ordinal for x in index])
         tm.assert_index_equal(result, exp)

pandas/tests/indexes/test_base.py

@@ -1736,7 +1736,13 @@ def test_validate_1d_input(dtype):
         *[[lambda x: Index(x, dtype=dtyp), {}] for dtyp in tm.ALL_REAL_NUMPY_DTYPES],
         [DatetimeIndex, {}],
         [TimedeltaIndex, {}],
-        [PeriodIndex, {"freq": "Y"}],
+        pytest.param(
+            PeriodIndex,
+            {"freq": "Y"},
+            marks=pytest.mark.filterwarnings(
+                "ignore:Passing integer-dtype data:pandas.errors.Pandas4Warning"
+            ),
+        ),
     ],
 )
 def test_construct_from_memoryview(klass, extra_kwargs):