DEPR: deprecate default of keep_tz=False of DatetimeIndex.to_series (#23739)

Author: jorisvandenbossche

doc/source/whatsnew/v0.24.0.rst

@@ -1029,6 +1029,8 @@ Deprecations
   `use_threads` to reflect the changes in pyarrow 0.11.0. (:issue:`23053`)
 - :func:`pandas.read_excel` has deprecated accepting ``usecols`` as an integer. Please pass in a list of ints from 0 to ``usecols`` inclusive instead (:issue:`23527`)
 - Constructing a :class:`TimedeltaIndex` from data with ``datetime64``-dtyped data is deprecated, will raise ``TypeError`` in a future version (:issue:`23539`)
+- The ``keep_tz=False`` option (the default) of the ``keep_tz`` keyword of
+  :meth:`DatetimeIndex.to_series` is deprecated (:issue:`17832`).
 
 .. _whatsnew_0240.deprecations.datetimelike_int_ops:
 

pandas/core/indexes/datetimes.py

@@ -478,15 +478,15 @@ def _get_time_micros(self):
             values = self._local_timestamps()
         return fields.get_time_micros(values)
 
-    def to_series(self, keep_tz=False, index=None, name=None):
+    def to_series(self, keep_tz=None, 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
-            return the data keeping the timezone.
+            Return the data keeping the timezone.
 
             If keep_tz is True:
 
@@ -500,6 +500,12 @@ def to_series(self, keep_tz=False, 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.
+
         index : Index, optional
             index of resulting Series. If None, defaults to original index
         name : string, optional
@@ -517,6 +523,19 @@ def to_series(self, keep_tz=False, 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 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 and self.tz is not None:
             # preserve the tz & copy
             values = self.copy(deep=True)

pandas/tests/frame/test_alter_axes.py

@@ -317,12 +317,21 @@ def test_convert_dti_to_series(self):
         tm.assert_series_equal(result, expected)
 
         # convert to utc
-        df['B'] = idx.to_series(index=[0, 1])
+        with tm.assert_produces_warning(FutureWarning):
+            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):
+            result = idx.to_series(index=[0, 1])
+        tm.assert_series_equal(result, expected.dt.tz_convert(None))
+
+        with tm.assert_produces_warning(FutureWarning):
+            result = idx.to_series(keep_tz=False, index=[0, 1])
+        tm.assert_series_equal(result, expected.dt.tz_convert(None))
+
         # list of datetimes with a tz
         df['B'] = idx.to_pydatetime()
         result = df['B']