DEPR: PeriodIndex.astype(dt64) (#44398)

Author: jbrockmendel

doc/source/whatsnew/v1.4.0.rst

@@ -458,6 +458,8 @@ Other Deprecations
 - Deprecated casting behavior when setting timezone-aware value(s) into a timezone-aware :class:`Series` or :class:`DataFrame` column when the timezones do not match. Previously this cast to object dtype. In a future version, the values being inserted will be converted to the series or column's existing timezone (:issue:`37605`)
 - Deprecated casting behavior when passing an item with mismatched-timezone to :meth:`DatetimeIndex.insert`, :meth:`DatetimeIndex.putmask`, :meth:`DatetimeIndex.where` :meth:`DatetimeIndex.fillna`, :meth:`Series.mask`, :meth:`Series.where`, :meth:`Series.fillna`, :meth:`Series.shift`, :meth:`Series.replace`, :meth:`Series.reindex` (and :class:`DataFrame` column analogues). In the past this has cast to object dtype. In a future version, these will cast the passed item to the index or series's timezone (:issue:`37605`)
 - Deprecated the 'errors' keyword argument in :meth:`Series.where`, :meth:`DataFrame.where`, :meth:`Series.mask`, and meth:`DataFrame.mask`; in a future version the argument will be removed (:issue:`44294`)
+- Deprecated :meth:`PeriodIndex.astype` to ``datetime64[ns]`` or ``DatetimeTZDtype``, use ``obj.to_timestamp(how).tz_localize(dtype.tz)`` instead (:issue:`44398`)
+-
 
 .. ---------------------------------------------------------------------------
 

pandas/core/indexes/period.py

@@ -354,6 +354,14 @@ def astype(self, dtype, copy: bool = True, how=lib.no_default):
 
         if is_datetime64_any_dtype(dtype):
             # 'how' is index-specific, isn't part of the EA interface.
+            # GH#44398 deprecate astype(dt64), matching Series behavior
+            warnings.warn(
+                f"Converting {type(self).__name__} to DatetimeIndex with "
+                "'astype' is deprecated and will raise in a future version. "
+                "Use `obj.to_timestamp(how).tz_localize(dtype.tz)` instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
             tz = getattr(dtype, "tz", None)
             return self.to_timestamp(how=how).tz_localize(tz)
 

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

@@ -164,7 +164,10 @@ def test_period_astype_to_timestamp(self):
         assert res.freq == exp.freq
 
         exp = DatetimeIndex(["2011-01-01", "2011-02-01", "2011-03-01"], tz="US/Eastern")
-        res = pi.astype("datetime64[ns, US/Eastern]")
+        msg = "Use `obj.to_timestamp"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            # GH#44398
+            res = pi.astype("datetime64[ns, US/Eastern]")
         tm.assert_index_equal(res, exp)
         assert res.freq == exp.freq
 

pandas/tests/indexes/test_common.py

@@ -392,6 +392,9 @@ def test_astype_preserves_name(self, index, dtype):
         ):
             # This astype is deprecated in favor of tz_localize
             warn = FutureWarning
+        elif isinstance(index, PeriodIndex) and dtype == "datetime64[ns]":
+            # Deprecated in favor of to_timestamp GH#44398
+            warn = FutureWarning
         try:
             # Some of these conversions cannot succeed so we use a try / except
             with tm.assert_produces_warning(warn):