DEPR: how keyword in PeriodIndex.astype (#37982)

doc/source/whatsnew/v1.2.0.rst

@@ -476,6 +476,7 @@ Deprecations
 - :meth:`Categorical.is_dtype_equal` and :meth:`CategoricalIndex.is_dtype_equal` are deprecated, will be removed in a future version (:issue:`37545`)
 - :meth:`Series.slice_shift` and :meth:`DataFrame.slice_shift` are deprecated, use :meth:`Series.shift` or :meth:`DataFrame.shift` instead (:issue:`37601`)
 - Partial slicing on unordered :class:`DatetimeIndex` with keys, which are not in Index is deprecated and will be removed in a future version (:issue:`18531`)
+- The ``how`` keyword in :meth:`PeriodIndex.astype` is deprecated and will be removed in a future version, use ``index.to_timestamp(how=how)`` instead (:issue:`37982`)
 - Deprecated :meth:`Index.asi8` for :class:`Index` subclasses other than :class:`DatetimeIndex`, :class:`TimedeltaIndex`, and :class:`PeriodIndex` (:issue:`37877`)
 - The ``inplace`` parameter of :meth:`Categorical.remove_unused_categories` is deprecated and will be removed in a future version (:issue:`37643`)
 

pandas/core/indexes/period.py

@@ -1,9 +1,10 @@
 from datetime import datetime, timedelta
 from typing import Any, cast
+import warnings
 
 import numpy as np
 
-from pandas._libs import index as libindex
+from pandas._libs import index as libindex, lib
 from pandas._libs.tslibs import BaseOffset, Period, Resolution, Tick
 from pandas._libs.tslibs.parsing import DateParseError, parse_time_string
 from pandas._typing import DtypeObj
@@ -376,15 +377,26 @@ def asof_locs(self, where: Index, mask: np.ndarray) -> np.ndarray:
         return super().asof_locs(where, mask)
 
     @doc(Index.astype)
-    def astype(self, dtype, copy: bool = True, how="start"):
+    def astype(self, dtype, copy: bool = True, how=lib.no_default):
         dtype = pandas_dtype(dtype)
 
+        if how is not lib.no_default:
+            # GH#37982
+            warnings.warn(
+                "The 'how' keyword in PeriodIndex.astype is deprecated and "
+                "will be removed in a future version. "
+                "Use index.to_timestamp(how=how) instead",
+                FutureWarning,
+                stacklevel=2,
+            )
+        else:
+            how = "start"
+
         if is_datetime64_any_dtype(dtype):
             # 'how' is index-specific, isn't part of the EA interface.
             tz = getattr(dtype, "tz", None)
             return self.to_timestamp(how=how).tz_localize(tz)
 
-        # TODO: should probably raise on `how` here, so we don't ignore it.
         return super().astype(dtype, copy=copy)
 
     @property

pandas/tests/indexes/period/test_astype.py

@@ -144,13 +144,17 @@ def test_period_astype_to_timestamp(self):
         pi = PeriodIndex(["2011-01", "2011-02", "2011-03"], freq="M")
 
         exp = DatetimeIndex(["2011-01-01", "2011-02-01", "2011-03-01"], freq="MS")
-        res = pi.astype("datetime64[ns]")
+        with tm.assert_produces_warning(FutureWarning):
+            # how keyword deprecated GH#37982
+            res = pi.astype("datetime64[ns]", how="start")
         tm.assert_index_equal(res, exp)
         assert res.freq == exp.freq
 
         exp = DatetimeIndex(["2011-01-31", "2011-02-28", "2011-03-31"])
         exp = exp + Timedelta(1, "D") - Timedelta(1, "ns")
-        res = pi.astype("datetime64[ns]", how="end")
+        with tm.assert_produces_warning(FutureWarning):
+            # how keyword deprecated GH#37982
+            res = pi.astype("datetime64[ns]", how="end")
         tm.assert_index_equal(res, exp)
         assert res.freq == exp.freq
 
@@ -161,6 +165,8 @@ def test_period_astype_to_timestamp(self):
 
         exp = DatetimeIndex(["2011-01-31", "2011-02-28", "2011-03-31"], tz="US/Eastern")
         exp = exp + Timedelta(1, "D") - Timedelta(1, "ns")
-        res = pi.astype("datetime64[ns, US/Eastern]", how="end")
+        with tm.assert_produces_warning(FutureWarning):
+            # how keyword deprecated GH#37982
+            res = pi.astype("datetime64[ns, US/Eastern]", how="end")
         tm.assert_index_equal(res, exp)
         assert res.freq == exp.freq