DEPR: change DTI.to_series keep_tz default to True (#29731)

Author: jbrockmendel

doc/source/whatsnew/v1.0.0.rst

@@ -275,6 +275,7 @@ or ``matplotlib.Axes.plot``. See :ref:`plotting.formatters` for more.
 - :meth:`pandas.Series.str.cat` does not accept list-likes *within* list-likes anymore (:issue:`27611`)
 - Removed the previously deprecated :meth:`ExtensionArray._formatting_values`. Use :attr:`ExtensionArray._formatter` instead. (:issue:`23601`)
 - Removed the previously deprecated ``IntervalIndex.from_intervals`` in favor of the :class:`IntervalIndex` constructor (:issue:`19263`)
+- Changed the default value for the "keep_tz" argument in :meth:`DatetimeIndex.to_series` to ``True`` (:issue:`23739`)
 - Ability to read pickles containing :class:`Categorical` instances created with pre-0.16 version of pandas has been removed (:issue:`27538`)
 - Removed the previously deprecated ``reduce`` and ``broadcast`` arguments from :meth:`DataFrame.apply` (:issue:`18577`)
 - Removed the previously deprecated ``assert_raises_regex`` function in ``pandas.util.testing`` (:issue:`29174`)

pandas/core/indexes/datetimes.py

@@ -663,14 +663,14 @@ def _get_time_micros(self):
             values = self._data._local_timestamps()
         return fields.get_time_micros(values)
 
-    def to_series(self, keep_tz=None, index=None, name=None):
+    def to_series(self, keep_tz=lib._no_default, index=None, name=None):
         """
         Create a Series with both index and values equal to the index keys
         useful with map for returning an indexer based on an index.
 
         Parameters
         ----------
-        keep_tz : optional, defaults False
+        keep_tz : optional, defaults True
             Return the data keeping the timezone.
 
             If keep_tz is True:
@@ -686,10 +686,10 @@ def to_series(self, keep_tz=None, index=None, name=None):
               Series will have a datetime64[ns] dtype. TZ aware
               objects will have the tz removed.
 
-            .. versionchanged:: 0.24
-                The default value will change to True in a future release.
-                You can set ``keep_tz=True`` to already obtain the future
-                behaviour and silence the warning.
+            .. versionchanged:: 1.0.0
+                The default value is now True.  In a future version,
+                this keyword will be removed entirely.  Stop passing the
+                argument to obtain the future behavior and silence the warning.
 
         index : Index, optional
             Index of resulting Series. If None, defaults to original index.
@@ -708,27 +708,27 @@ def to_series(self, keep_tz=None, index=None, name=None):
         if name is None:
             name = self.name
 
-        if keep_tz is None and self.tz is not None:
-            warnings.warn(
-                "The default of the 'keep_tz' keyword in "
-                "DatetimeIndex.to_series will change "
-                "to True in a future release. You can set "
-                "'keep_tz=True' to obtain the future behaviour and "
-                "silence this warning.",
-                FutureWarning,
-                stacklevel=2,
-            )
-            keep_tz = False
-        elif keep_tz is False:
-            warnings.warn(
-                "Specifying 'keep_tz=False' is deprecated and this "
-                "option will be removed in a future release. If "
-                "you want to remove the timezone information, you "
-                "can do 'idx.tz_convert(None)' before calling "
-                "'to_series'.",
-                FutureWarning,
-                stacklevel=2,
-            )
+        if keep_tz is not lib._no_default:
+            if keep_tz:
+                warnings.warn(
+                    "The 'keep_tz' keyword in DatetimeIndex.to_series "
+                    "is deprecated and will be removed in a future version.  "
+                    "You can stop passing 'keep_tz' to silence this warning.",
+                    FutureWarning,
+                    stacklevel=2,
+                )
+            else:
+                warnings.warn(
+                    "Specifying 'keep_tz=False' is deprecated and this "
+                    "option will be removed in a future release. If "
+                    "you want to remove the timezone information, you "
+                    "can do 'idx.tz_convert(None)' before calling "
+                    "'to_series'.",
+                    FutureWarning,
+                    stacklevel=2,
+                )
+        else:
+            keep_tz = True
 
         if keep_tz and self.tz is not None:
             # preserve the tz & copy

pandas/tests/frame/test_alter_axes.py

@@ -493,29 +493,29 @@ def test_convert_dti_to_series(self):
         tm.assert_series_equal(result, expected)
 
         # convert to series while keeping the timezone
-        result = idx.to_series(keep_tz=True, index=[0, 1])
+        msg = "stop passing 'keep_tz'"
+        with tm.assert_produces_warning(FutureWarning) as m:
+            result = idx.to_series(keep_tz=True, index=[0, 1])
         tm.assert_series_equal(result, expected)
+        assert msg in str(m[0].message)
 
         # convert to utc
-        with tm.assert_produces_warning(FutureWarning):
+        with tm.assert_produces_warning(FutureWarning) as m:
             df["B"] = idx.to_series(keep_tz=False, index=[0, 1])
         result = df["B"]
         comp = Series(DatetimeIndex(expected.values).tz_localize(None), name="B")
         tm.assert_series_equal(result, comp)
-
-        with tm.assert_produces_warning(FutureWarning) as m:
-            result = idx.to_series(index=[0, 1])
-        tm.assert_series_equal(result, expected.dt.tz_convert(None))
-        msg = (
-            "The default of the 'keep_tz' keyword in "
-            "DatetimeIndex.to_series will change to True in a future "
-            "release."
-        )
+        msg = "do 'idx.tz_convert(None)' before calling"
         assert msg in str(m[0].message)
 
-        with tm.assert_produces_warning(FutureWarning):
+        result = idx.to_series(index=[0, 1])
+        tm.assert_series_equal(result, expected)
+
+        with tm.assert_produces_warning(FutureWarning) as m:
             result = idx.to_series(keep_tz=False, index=[0, 1])
         tm.assert_series_equal(result, expected.dt.tz_convert(None))
+        msg = "do 'idx.tz_convert(None)' before calling"
+        assert msg in str(m[0].message)
 
         # list of datetimes with a tz
         df["B"] = idx.to_pydatetime()

pandas/tests/frame/test_constructors.py

@@ -1795,7 +1795,7 @@ def test_constructor_with_datetimes(self):
         # preserver an index with a tz on dict construction
         i = date_range("1/1/2011", periods=5, freq="10s", tz="US/Eastern")
 
-        expected = DataFrame({"a": i.to_series(keep_tz=True).reset_index(drop=True)})
+        expected = DataFrame({"a": i.to_series().reset_index(drop=True)})
         df = DataFrame()
         df["a"] = i
         tm.assert_frame_equal(df, expected)
@@ -1806,9 +1806,7 @@ def test_constructor_with_datetimes(self):
         # multiples
         i_no_tz = date_range("1/1/2011", periods=5, freq="10s")
         df = DataFrame({"a": i, "b": i_no_tz})
-        expected = DataFrame(
-            {"a": i.to_series(keep_tz=True).reset_index(drop=True), "b": i_no_tz}
-        )
+        expected = DataFrame({"a": i.to_series().reset_index(drop=True), "b": i_no_tz})
         tm.assert_frame_equal(df, expected)
 
     def test_constructor_datetimes_with_nulls(self):

pandas/tests/test_base.py

@@ -179,7 +179,7 @@ def setup_method(self, method):
         self.int_series = Series(arr, index=self.int_index, name="a")
         self.float_series = Series(arr, index=self.float_index, name="a")
         self.dt_series = Series(arr, index=self.dt_index, name="a")
-        self.dt_tz_series = self.dt_tz_index.to_series(keep_tz=True)
+        self.dt_tz_series = self.dt_tz_index.to_series()
         self.period_series = Series(arr, index=self.period_index, name="a")
         self.string_series = Series(arr, index=self.string_index, name="a")
         self.unicode_series = Series(arr, index=self.unicode_index, name="a")