Address review

doc/source/timeseries.rst

@@ -2353,7 +2353,7 @@ constructor as well as ``tz_localize``.
 .. _timeseries.timezone_nonexsistent:
 
 Nonexistent Times when Localizing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A DST transition may also shift the local time ahead by 1 hour creating nonexistent
 local times. The behavior of localizing a timeseries with nonexistent times

doc/source/whatsnew/v0.24.0.txt

@@ -191,7 +191,7 @@ Other Enhancements
 - :meth:`Series.resample` and :meth:`DataFrame.resample` have gained the :meth:`Resampler.quantile` (:issue:`15023`).
 - :meth:`Index.to_frame` now supports overriding column name(s) (:issue:`22580`).
 - New attribute :attr:`__git_version__` will return git commit sha of current build (:issue:`21295`).
-- :meth:`Timestamp.tz_localize`, :meth:`DatetimeIndex.tz_localize`, and :meth:`Series.tz_localize` have gained the ``nonexistent`` argument for alternative handling of nonexistent times (:issue:`8917`)
+- :meth:`Timestamp.tz_localize`, :meth:`DatetimeIndex.tz_localize`, and :meth:`Series.tz_localize` have gained the ``nonexistent`` argument for alternative handling of nonexistent times. See :ref:`timeseries.timezone_nonexsistent` (:issue:`8917`)
 
 .. _whatsnew_0240.api_breaking:
 

pandas/_libs/tslibs/conversion.pyx

@@ -1,6 +1,4 @@
 # -*- coding: utf-8 -*-
-import warnings
-
 import cython
 from cython import Py_ssize_t
 
@@ -841,8 +839,13 @@ def tz_localize_to_utc(ndarray[int64_t] vals, object tz, object ambiguous=None,
         If arraylike, must have the same length as vals
     nonexistent : str, bool, or arraylike
         If arraylike, must have the same length as vals
+
+        .. versionadded:: 0.24.0
+
     errors : {"raise", "coerce"}, default "raise"
 
+         .. depreciated:: 0.24.0
+
     Returns
     -------
     localized : ndarray[int64_t]
@@ -863,11 +866,6 @@ def tz_localize_to_utc(ndarray[int64_t] vals, object tz, object ambiguous=None,
     # Vectorized version of DstTzInfo.localize
     assert is_coerce or is_raise
 
-    if is_coerce:
-        warnings.warn("the errors argument is deprecated, will be removed "
-                      "in a future release. Use the ambiguous or nonexistent "
-                      "argument instead.", DeprecationWarning)
-
     if tz == UTC or tz is None:
         return vals
 

pandas/_libs/tslibs/timestamps.pyx

@@ -944,6 +944,12 @@ class Timestamp(_Timestamp):
         if ambiguous == 'infer':
             raise ValueError('Cannot infer offset with only one time.')
 
+        if errors != 'raise':
+            warnings.warn("The errors argument is deprecated and will be "
+                          "removed in a future release. Use the ambiguous or "
+                          "nonexistent argument instead.", FutureWarning,
+                          stacklevel=2)
+
         if self.tzinfo is None:
             # tz naive, localize
             tz = maybe_get_tz(tz)

pandas/core/arrays/datetimes.py

@@ -703,6 +703,11 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',
                        '2018-03-03 09:00:00'],
                       dtype='datetime64[ns]', freq='D')
         """
+        if errors != 'raise':
+            warnings.warn("The errors argument is deprecated and will be "
+                          "removed in a future release. Use the ambiguous or "
+                          "nonexistent argument instead.", FutureWarning,
+                          stacklevel=2)
         if self.tz is not None:
             if tz is None:
                 new_dates = conversion.tz_convert(self.asi8, 'UTC', self.tz)

pandas/tests/indexes/datetimes/test_timezones.py

@@ -592,6 +592,14 @@ def test_dti_tz_localize_nonexistent(self, tz, method, exp):
             expected = DatetimeIndex([exp] * n, tz=tz)
             tm.assert_index_equal(result, expected)
 
+    @pytest.mark.filterwarnings('ignore::FutureWarning')
+    def test_dti_tz_localize_errors_deprecation(self):
+        # GH 22644
+        n = 60
+        dti = date_range(start='2015-03-29 02:00:00', periods=n, freq='min')
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            dti.tz_localize('UTC', errors='coerce')
+
     # -------------------------------------------------------------
     # DatetimeIndex.normalize
 

pandas/tests/scalar/timestamp/test_timezones.py

@@ -79,14 +79,16 @@ def test_tz_localize_ambiguous(self):
         ('2015-03-08 02:30', 'US/Pacific'),
         ('2015-03-29 02:00', 'Europe/Paris'),
         ('2015-03-29 02:30', 'Europe/Belgrade')])
+    @pytest.mark.filterwarnings('ignore::FutureWarning')
     def test_tz_localize_nonexistent(self, stamp, tz):
         # GH#13057
         ts = Timestamp(stamp)
         with pytest.raises(NonExistentTimeError):
             ts.tz_localize(tz)
         with pytest.raises(NonExistentTimeError):
             ts.tz_localize(tz, errors='raise')
-        with tm.assert_produces_warning(DeprecationWarning):
+        # GH 22644
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
             assert ts.tz_localize(tz, errors='coerce') is NaT
 
     def test_tz_localize_errors_ambiguous(self):

pandas/tests/series/test_timezones.py

@@ -33,6 +33,14 @@ def test_series_tz_localize(self):
         tm.assert_raises_regex(TypeError, 'Already tz-aware',
                                ts.tz_localize, 'US/Eastern')
 
+    @pytest.mark.filterwarnings('ignore::FutureWarning')
+    def test_tz_localize_errors_deprecation(self):
+        rng = date_range('1/1/2011', periods=100, freq='H')
+        ts = Series(rng)
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            # GH 22644
+            ts.dt.tz_localize('UTC', errors='coerce')
+
     def test_series_tz_localize_ambiguous_bool(self):
         # make sure that we are correctly accepting bool values as ambiguous