DEPR: tz_convert, tz_localize, to_timestamp, to_period

doc/source/user_guide/10min.rst

@@ -614,22 +614,6 @@ financial applications. See the :ref:`Time Series section <timeseries>`.
    ts = pd.Series(np.random.randint(0, 500, len(rng)), index=rng)
    ts.resample("5Min").sum()
 
-:meth:`Series.tz_localize` localizes a time series to a time zone:
-
-.. ipython:: python
-
-   rng = pd.date_range("3/6/2012 00:00", periods=5, freq="D")
-   ts = pd.Series(np.random.randn(len(rng)), rng)
-   ts
-   ts_utc = ts.tz_localize("UTC")
-   ts_utc
-
-:meth:`Series.tz_convert` converts a timezones aware time series to another time zone:
-
-.. ipython:: python
-
-   ts_utc.tz_convert("US/Eastern")
-
 Adding a non-fixed duration (:class:`~pandas.tseries.offsets.BusinessDay`) to a time series:
 
 .. ipython:: python

doc/source/whatsnew/v2.2.0.rst

@@ -235,6 +235,7 @@ Other Deprecations
 ^^^^^^^^^^^^^^^^^^
 - Changed :meth:`Timedelta.resolution_string` to return ``h``, ``min``, ``s``, ``ms``, ``us``, and ``ns`` instead of ``H``, ``T``, ``S``, ``L``, ``U``, and ``N``, for compatibility with respective deprecations in frequency aliases (:issue:`52536`)
 - Deprecated :meth:`Index.format`, use ``index.astype(str)`` or ``index.map(formatter)`` instead (:issue:`55413`)
+- Deprecated :meth:`Series.to_period`, :meth:`DataFrame.to_period`, :meth:`Series.to_timestamp`, :meth:`DataFrame.to_timestamp`, :meth:`Series.tz_localize`, :meth:`DataFrame.tz_localize`, :meth:`Series.tz_convert`, :meth:`DataFrame.tz_convert`, use the relevant methods on ``obj.set_axis(obj.index.relevant_method(...))`` instead (:issue:`52110`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_clipboard`. (:issue:`54229`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_csv` except ``path_or_buf``. (:issue:`54229`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_dict`. (:issue:`54229`)

pandas/conftest.py

@@ -146,6 +146,11 @@ def pytest_collection_modifyitems(items, config) -> None:
         ("NDFrame.replace", "The 'method' keyword"),
         ("NDFrame.replace", "Series.replace without 'value'"),
         ("NDFrame.clip", "Downcasting behavior in Series and DataFrame methods"),
+        ("Series.to_timestamp", "Series.to_timestamp is deprecated"),
+        ("Series.to_period", "Series.to_period is deprecated"),
+        ("Series.tz_localize", "Series.tz_localize is deprecated"),
+        ("Series.tz_convert", "Series.tz_convert is deprecated"),
+        ("DataFrame.to_timestamp", "DataFrame.to_timestamp is deprecated"),
         ("Series.idxmin", "The behavior of Series.idxmin"),
         ("Series.idxmax", "The behavior of Series.idxmax"),
         ("SeriesGroupBy.idxmin", "The behavior of Series.idxmin"),

pandas/core/frame.py

@@ -12103,6 +12103,15 @@ def to_timestamp(
         >>> df2.index
         DatetimeIndex(['2023-01-31', '2024-01-31'], dtype='datetime64[ns]', freq=None)
         """
+        warnings.warn(
+            # GH#52110
+            f"{type(self).__name__}.to_timestamp is deprecated and will be "
+            "removed in a future version. Use "
+            "obj.set_axis(obj.index.to_timestamp(...)) instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
         new_obj = self.copy(deep=copy and not using_copy_on_write())
 
         axis_name = self._get_axis_name(axis)
@@ -12160,6 +12169,15 @@ def to_period(
         >>> idx.to_period("Y")
         PeriodIndex(['2001', '2002', '2003'], dtype='period[Y-DEC]')
         """
+        warnings.warn(
+            # GH#52110
+            f"{type(self).__name__}.to_period is deprecated and will be "
+            "removed in a future version. Use "
+            "obj.set_axis(obj.index.to_period(freq)) instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
         new_obj = self.copy(deep=copy and not using_copy_on_write())
 
         axis_name = self._get_axis_name(axis)

pandas/core/generic.py

@@ -11217,6 +11217,14 @@ def tz_convert(
         2018-09-14 23:30:00    1
         dtype: int64
         """
+        warnings.warn(
+            # GH#52110
+            f"{type(self).__name__}.tz_convert is deprecated and will be "
+            "removed in a future version. Use "
+            "obj.set_axis(obj.index.tz_convert(tz)) instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
         axis = self._get_axis_number(axis)
         ax = self._get_axis(axis)
 
@@ -11389,6 +11397,15 @@ def tz_localize(
         2015-03-29 03:30:00+02:00    1
         dtype: int64
         """
+        warnings.warn(
+            # GH#52110
+            f"{type(self).__name__}.tz_localize is deprecated and will be "
+            "removed in a future version. Use "
+            "obj.set_axis(obj.index.tz_localize(tz)) instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
         nonexistent_options = ("raise", "NaT", "shift_forward", "shift_backward")
         if nonexistent not in nonexistent_options and not isinstance(
             nonexistent, dt.timedelta

pandas/core/resample.py

@@ -1868,7 +1868,8 @@ def _convert_obj(self, obj: NDFrameT) -> NDFrameT:
 
         # convert to timestamp
         if self.kind == "timestamp":
-            obj = obj.to_timestamp(how=self.convention)
+            dti = obj.index.to_timestamp(how=self.convention)
+            obj = obj.set_axis(dti)
 
         return obj
 

pandas/core/series.py

@@ -5741,6 +5741,15 @@ def to_timestamp(
         2025-01-31    3
         Freq: Y-JAN, dtype: int64
         """
+        warnings.warn(
+            # GH#52110
+            f"{type(self).__name__}.to_timestamp is deprecated and will be "
+            "removed in a future version. Use "
+            "obj.set_axis(obj.index.to_timestamp(...)) instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
         if not isinstance(self.index, PeriodIndex):
             raise TypeError(f"unsupported Type {type(self.index).__name__}")
 
@@ -5781,6 +5790,15 @@ def to_period(self, freq: str | None = None, copy: bool | None = None) -> Series
         >>> s.index
         PeriodIndex(['2023', '2024', '2025'], dtype='period[Y-DEC]')
         """
+        warnings.warn(
+            # GH#52110
+            f"{type(self).__name__}.to_period is deprecated and will be "
+            "removed in a future version. Use "
+            "obj.set_axis(obj.index.to_period(freq)) instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
         if not isinstance(self.index, DatetimeIndex):
             raise TypeError(f"unsupported Type {type(self.index).__name__}")
 

pandas/plotting/_matplotlib/timeseries.py

@@ -295,7 +295,7 @@ def maybe_convert_index(ax: Axes, data):
             )
 
             if isinstance(data.index, ABCDatetimeIndex):
-                data = data.tz_localize(None).to_period(freq=freq_str)
+                data.index = data.index.tz_localize(None).to_period(freq=freq_str)
             elif isinstance(data.index, ABCPeriodIndex):
                 data.index = data.index.asfreq(freq=freq_str)
     return data

pandas/tests/apply/test_series_apply.py

@@ -513,10 +513,9 @@ def test_series_apply_no_suffix_index(by_row):
 def test_apply_series_on_date_time_index_aware_series(dti, exp, aware):
     # GH 25959
     # Calling apply on a localized time series should not cause an error
+    index = dti.index
     if aware:
-        index = dti.tz_localize("UTC").index
-    else:
-        index = dti.index
+        index = index.tz_localize("UTC")
     result = Series(index).apply(lambda x: Series([1, 2]))
     tm.assert_frame_equal(result, exp)
 
@@ -527,7 +526,8 @@ def test_apply_series_on_date_time_index_aware_series(dti, exp, aware):
 def test_apply_scalar_on_date_time_index_aware_series(by_row, expected):
     # GH 25959
     # Calling apply on a localized time series should not cause an error
-    series = tm.makeTimeSeries(nper=30).tz_localize("UTC")
+    series = tm.makeTimeSeries(nper=30)
+    series.index = series.index.tz_localize("UTC")
     result = Series(series.index).apply(lambda x: 1, by_row=by_row)
     tm.assert_equal(result, expected)
 

pandas/tests/copy_view/test_methods.py

@@ -136,6 +136,22 @@ def test_methods_copy_keyword(
         msg = "'DataFrame.swapaxes' is deprecated"
         with tm.assert_produces_warning(FutureWarning, match=msg):
             df2 = method(df, copy=copy)
+    elif "tz_convert" in request.node.callspec.id:
+        msg = "DataFrame.tz_convert is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df2 = method(df, copy=copy)
+    elif "tz_localize" in request.node.callspec.id:
+        msg = "DataFrame.tz_localize is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df2 = method(df, copy=copy)
+    elif "to_timestamp" in request.node.callspec.id:
+        msg = "DataFrame.to_timestamp is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df2 = method(df, copy=copy)
+    elif "to_period" in request.node.callspec.id:
+        msg = "DataFrame.to_period is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df2 = method(df, copy=copy)
     else:
         df2 = method(df, copy=copy)
 
@@ -213,6 +229,22 @@ def test_methods_series_copy_keyword(request, method, copy, using_copy_on_write)
         msg = "'Series.swapaxes' is deprecated"
         with tm.assert_produces_warning(FutureWarning, match=msg):
             ser2 = method(ser, copy=copy)
+    elif "tz_convert" in request.node.callspec.id:
+        msg = "Series.tz_convert is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            ser2 = method(ser, copy=copy)
+    elif "tz_localize" in request.node.callspec.id:
+        msg = "Series.tz_localize is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            ser2 = method(ser, copy=copy)
+    elif "to_timestamp" in request.node.callspec.id:
+        msg = "Series.to_timestamp is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            ser2 = method(ser, copy=copy)
+    elif "to_period" in request.node.callspec.id:
+        msg = "Series.to_period is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            ser2 = method(ser, copy=copy)
     else:
         ser2 = method(ser, copy=copy)
 
@@ -766,7 +798,9 @@ def test_to_timestamp(using_copy_on_write, obj):
     obj.index = Index([Period("2012-1-1", freq="D"), Period("2012-1-2", freq="D")])
 
     obj_orig = obj.copy()
-    obj2 = obj.to_timestamp()
+    depr_msg = f"{type(obj).__name__}.to_timestamp is deprecated"
+    with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+        obj2 = obj.to_timestamp()
 
     if using_copy_on_write:
         assert np.shares_memory(get_array(obj2, "a"), get_array(obj, "a"))
@@ -784,7 +818,9 @@ def test_to_period(using_copy_on_write, obj):
     obj.index = Index([Timestamp("2019-12-31"), Timestamp("2020-12-31")])
 
     obj_orig = obj.copy()
-    obj2 = obj.to_period(freq="Y")
+    depr_msg = f"{type(obj).__name__}.to_period is deprecated"
+    with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+        obj2 = obj.to_period(freq="Y")
 
     if using_copy_on_write:
         assert np.shares_memory(get_array(obj2, "a"), get_array(obj, "a"))
@@ -1314,7 +1350,9 @@ def test_tz_convert_localize(using_copy_on_write, func, tz):
         [1, 2], index=date_range(start="2014-08-01 09:00", freq="h", periods=2, tz=tz)
     )
     ser_orig = ser.copy()
-    ser2 = getattr(ser, func)("US/Central")
+    depr_msg = f"Series.{func} is deprecated"
+    with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+        ser2 = getattr(ser, func)("US/Central")
 
     if using_copy_on_write:
         assert np.shares_memory(ser.values, ser2.values)

pandas/tests/frame/methods/test_align.py

@@ -34,7 +34,7 @@ def test_frame_align_aware(self):
         # different timezones convert to UTC
 
         # frame with frame
-        df1_central = df1.tz_convert("US/Central")
+        df1_central = df1.set_axis(df1.index.tz_convert("US/Central"))
         new1, new2 = df1.align(df1_central)
         assert new1.index.tz is timezone.utc
         assert new2.index.tz is timezone.utc

pandas/tests/frame/methods/test_asof.py

@@ -97,7 +97,7 @@ def test_missing(self, date_range_frame):
 
         # Check that we handle PeriodIndex correctly, dont end up with
         #  period.ordinal for series name
-        df = df.to_period("D")
+        df = df.set_axis(df.index.to_period("D"))
         result = df.asof("1989-12-31")
         assert isinstance(result.name, Period)
 

pandas/tests/frame/methods/test_at_time.py

@@ -23,10 +23,11 @@ def test_localized_at_time(self, tzstr, frame_or_series):
             np.random.default_rng(2).standard_normal(len(rng)), index=rng
         )
 
-        ts_local = ts.tz_localize(tzstr)
+        ts_local = ts.set_axis(ts.index.tz_localize(tzstr))
 
         result = ts_local.at_time(time(10, 0))
-        expected = ts.at_time(time(10, 0)).tz_localize(tzstr)
+        expected = ts.at_time(time(10, 0))
+        expected = expected.set_axis(expected.index.tz_localize(tzstr))
         tm.assert_equal(result, expected)
         assert timezones.tz_compare(result.index.tz, tz)
 

pandas/tests/frame/methods/test_between_time.py

@@ -51,11 +51,12 @@ def test_localized_between_time(self, tzstr, frame_or_series):
         if frame_or_series is DataFrame:
             ts = ts.to_frame()
 
-        ts_local = ts.tz_localize(tzstr)
+        ts_local = ts.set_axis(ts.index.tz_localize(tzstr))
 
         t1, t2 = time(10, 0), time(11, 0)
         result = ts_local.between_time(t1, t2)
-        expected = ts.between_time(t1, t2).tz_localize(tzstr)
+        expected = ts.between_time(t1, t2)
+        expected = expected.set_axis(expected.index.tz_localize(tzstr))
         tm.assert_equal(result, expected)
         assert timezones.tz_compare(result.index.tz, tz)
 

pandas/tests/frame/methods/test_to_period.py

@@ -25,12 +25,15 @@ def test_to_period(self, frame_or_series):
         obj["mix"] = "a"
         obj = tm.get_obj(obj, frame_or_series)
 
-        pts = obj.to_period()
+        msg = "(Series|DataFrame).to_period is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            pts = obj.to_period()
         exp = obj.copy()
         exp.index = period_range("1/1/2000", "1/1/2001")
         tm.assert_equal(pts, exp)
 
-        pts = obj.to_period("M")
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            pts = obj.to_period("M")
         exp.index = exp.index.asfreq("M")
         tm.assert_equal(pts, exp)
 
@@ -47,25 +50,33 @@ def test_to_period_without_freq(self, frame_or_series):
         obj = tm.get_obj(obj, frame_or_series)
         expected = obj.copy()
         expected.index = exp_idx
-        tm.assert_equal(obj.to_period(), expected)
+        msg = f"{type(expected).__name__}.to_period is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            res = obj.to_period()
+        tm.assert_equal(res, expected)
 
         if frame_or_series is DataFrame:
             expected = obj.copy()
             expected.columns = exp_idx
-            tm.assert_frame_equal(obj.to_period(axis=1), expected)
+            with tm.assert_produces_warning(FutureWarning, match=msg):
+                res = obj.to_period(axis=1)
+            tm.assert_frame_equal(res, expected)
 
     def test_to_period_columns(self):
         dr = date_range("1/1/2000", "1/1/2001")
         df = DataFrame(np.random.default_rng(2).standard_normal((len(dr), 5)), index=dr)
         df["mix"] = "a"
 
         df = df.T
-        pts = df.to_period(axis=1)
+        msg = "DataFrame.to_period is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            pts = df.to_period(axis=1)
         exp = df.copy()
         exp.columns = period_range("1/1/2000", "1/1/2001")
         tm.assert_frame_equal(pts, exp)
 
-        pts = df.to_period("M", axis=1)
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            pts = df.to_period("M", axis=1)
         tm.assert_index_equal(pts.columns, exp.columns.asfreq("M"))
 
     def test_to_period_invalid_axis(self):
@@ -74,16 +85,20 @@ def test_to_period_invalid_axis(self):
         df["mix"] = "a"
 
         msg = "No axis named 2 for object type DataFrame"
+        depr_msg = "DataFrame.to_period is deprecated"
         with pytest.raises(ValueError, match=msg):
-            df.to_period(axis=2)
+            with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+                df.to_period(axis=2)
 
     def test_to_period_raises(self, index, frame_or_series):
         # https://github.com/pandas-dev/pandas/issues/33327
         obj = Series(index=index, dtype=object)
         if frame_or_series is DataFrame:
             obj = obj.to_frame()
 
+        depr_msg = rf"{type(obj).__name__}\.to_period is deprecated"
         if not isinstance(index, DatetimeIndex):
             msg = f"unsupported Type {type(index).__name__}"
             with pytest.raises(TypeError, match=msg):
-                obj.to_period()
+                with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+                    obj.to_period()

pandas/tests/frame/methods/test_to_records.py

@@ -517,7 +517,7 @@ def test_to_records_datetimeindex_with_tz(self, tz):
         df = DataFrame({"datetime": dr}, index=dr)
 
         expected = df.to_records()
-        result = df.tz_convert("UTC").to_records()
+        result = df.set_axis(df.index.tz_convert("UTC")).to_records()
 
         # both converted to UTC, so they are equal
         tm.assert_numpy_array_equal(result, expected)