DEPR: tz kwarg in Period.to_timestamp (#34522)

Author: jbrockmendel

doc/source/whatsnew/v1.1.0.rst

@@ -741,6 +741,7 @@ Deprecations
   raise an ``IndexError`` in the future. You can manually convert to an integer key
   instead (:issue:`34191`).
 - The ``squeeze`` keyword in the ``groupby`` function is deprecated and will be removed in a future version (:issue:`32380`)
+- The ``tz`` keyword in :meth:`Period.to_timestamp` is deprecated and will be removed in a future version; use `per.to_timestamp(...).tz_localize(tz)`` instead (:issue:`34522`)
 
 .. ---------------------------------------------------------------------------
 

pandas/_libs/tslibs/period.pyx

@@ -1,3 +1,5 @@
+import warnings
+
 from cpython.object cimport PyObject_RichCompareBool, Py_EQ, Py_NE
 
 from numpy cimport int64_t, import_array, ndarray
@@ -1727,6 +1729,16 @@ cdef class _Period:
         -------
         Timestamp
         """
+        if tz is not None:
+            # GH#34522
+            warnings.warn(
+                "Period.to_timestamp `tz` argument is deprecated and will "
+                "be removed in a future version.  Use "
+                "`per.to_timestamp(...).tz_localize(tz)` instead.",
+                FutureWarning,
+                stacklevel=1,
+            )
+
         how = validate_end_alias(how)
 
         end = how == 'E'

pandas/plotting/_matplotlib/timeseries.py

@@ -221,7 +221,7 @@ def _use_dynamic_x(ax, data):
         x = data.index
         if base <= FreqGroup.FR_DAY:
             return x[:1].is_normalized
-        return Period(x[0], freq).to_timestamp(tz=x.tz) == x[0]
+        return Period(x[0], freq).to_timestamp().tz_localize(x.tz) == x[0]
     return True
 
 

pandas/tests/scalar/period/test_period.py

@@ -506,31 +506,36 @@ def test_hash(self):
 
     @pytest.mark.parametrize("tzstr", ["Europe/Brussels", "Asia/Tokyo", "US/Pacific"])
     def test_to_timestamp_tz_arg(self, tzstr):
-        p = Period("1/1/2005", freq="M").to_timestamp(tz=tzstr)
+        # GH#34522 tz kwarg deprecated
+        with tm.assert_produces_warning(FutureWarning):
+            p = Period("1/1/2005", freq="M").to_timestamp(tz=tzstr)
         exp = Timestamp("1/1/2005", tz="UTC").tz_convert(tzstr)
         exp_zone = pytz.timezone(tzstr).normalize(p)
 
         assert p == exp
         assert p.tz == exp_zone.tzinfo
         assert p.tz == exp.tz
 
-        p = Period("1/1/2005", freq="3H").to_timestamp(tz=tzstr)
+        with tm.assert_produces_warning(FutureWarning):
+            p = Period("1/1/2005", freq="3H").to_timestamp(tz=tzstr)
         exp = Timestamp("1/1/2005", tz="UTC").tz_convert(tzstr)
         exp_zone = pytz.timezone(tzstr).normalize(p)
 
         assert p == exp
         assert p.tz == exp_zone.tzinfo
         assert p.tz == exp.tz
 
-        p = Period("1/1/2005", freq="A").to_timestamp(freq="A", tz=tzstr)
+        with tm.assert_produces_warning(FutureWarning):
+            p = Period("1/1/2005", freq="A").to_timestamp(freq="A", tz=tzstr)
         exp = Timestamp("31/12/2005", tz="UTC").tz_convert(tzstr)
         exp_zone = pytz.timezone(tzstr).normalize(p)
 
         assert p == exp
         assert p.tz == exp_zone.tzinfo
         assert p.tz == exp.tz
 
-        p = Period("1/1/2005", freq="A").to_timestamp(freq="3H", tz=tzstr)
+        with tm.assert_produces_warning(FutureWarning):
+            p = Period("1/1/2005", freq="A").to_timestamp(freq="3H", tz=tzstr)
         exp = Timestamp("1/1/2005", tz="UTC").tz_convert(tzstr)
         exp_zone = pytz.timezone(tzstr).normalize(p)
 
@@ -544,20 +549,23 @@ def test_to_timestamp_tz_arg(self, tzstr):
     )
     def test_to_timestamp_tz_arg_dateutil(self, tzstr):
         tz = maybe_get_tz(tzstr)
-        p = Period("1/1/2005", freq="M").to_timestamp(tz=tz)
+        with tm.assert_produces_warning(FutureWarning):
+            p = Period("1/1/2005", freq="M").to_timestamp(tz=tz)
         exp = Timestamp("1/1/2005", tz="UTC").tz_convert(tzstr)
         assert p == exp
         assert p.tz == dateutil_gettz(tzstr.split("/", 1)[1])
         assert p.tz == exp.tz
 
-        p = Period("1/1/2005", freq="M").to_timestamp(freq="3H", tz=tz)
+        with tm.assert_produces_warning(FutureWarning):
+            p = Period("1/1/2005", freq="M").to_timestamp(freq="3H", tz=tz)
         exp = Timestamp("1/1/2005", tz="UTC").tz_convert(tzstr)
         assert p == exp
         assert p.tz == dateutil_gettz(tzstr.split("/", 1)[1])
         assert p.tz == exp.tz
 
     def test_to_timestamp_tz_arg_dateutil_from_string(self):
-        p = Period("1/1/2005", freq="M").to_timestamp(tz="dateutil/Europe/Brussels")
+        with tm.assert_produces_warning(FutureWarning):
+            p = Period("1/1/2005", freq="M").to_timestamp(tz="dateutil/Europe/Brussels")
         assert p.tz == dateutil_gettz("Europe/Brussels")
 
     def test_to_timestamp_mult(self):