API/ENH: tz_localize handling of nonexistent times: rename keyword + add shift option

pandas/_libs/tslibs/nattype.pyx

@@ -565,6 +565,8 @@ class NaTType(_NaT):
             - 'raise' will raise an AmbiguousTimeError for an ambiguous time
 
         nonexistent : 'shift', 'NaT', default 'raise'
+            A nonexistent time doesn't not exist in a particular timezone
+            where clocks moved forward due to DST.
             - 'shift' will shift the nonexistent time forward to the closest
               existing time
             - 'NaT' will return NaT where there are nonexistent times

pandas/_libs/tslibs/timestamps.pyx

@@ -980,6 +980,8 @@ class Timestamp(_Timestamp):
             - 'raise' will raise an AmbiguousTimeError for an ambiguous time
 
         nonexistent : 'shift', 'NaT', default 'raise'
+            A nonexistent time doesn't not exist in a particular timezone
+            where clocks moved forward due to DST.
             - 'shift' will shift the nonexistent time forward to the closest
               existing time
             - 'NaT' will return NaT where there are nonexistent times
@@ -1013,8 +1015,7 @@ class Timestamp(_Timestamp):
             warnings.warn("The errors argument is deprecated and will be "
                           "removed in a future release. Use "
                           "nonexistent='NaT' or nonexistent='raise' "
-                          "instead.", FutureWarning,
-                          stacklevel=2)
+                          "instead.", FutureWarning)
             if errors == 'coerce':
                 nonexistent = 'NaT'
             elif errors == 'raise':

pandas/core/arrays/datetimes.py

@@ -649,6 +649,8 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',
               times
 
         nonexistent : 'shift', 'NaT' default 'raise'
+            A nonexistent time doesn't not exist in a particular timezone
+            where clocks moved forward due to DST.
             - 'shift' will shift the nonexistent times forward to the closest
               existing time
             - 'NaT' will return NaT where there are nonexistent times
@@ -711,8 +713,7 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',
             warnings.warn("The errors argument is deprecated and will be "
                           "removed in a future release. Use "
                           "nonexistent='NaT' or nonexistent='raise' "
-                          "instead.", FutureWarning,
-                          stacklevel=2)
+                          "instead.", FutureWarning)
             if errors == 'coerce':
                 nonexistent = 'NaT'
             elif errors == 'raise':

pandas/core/generic.py

@@ -8656,6 +8656,8 @@ def tz_localize(self, tz, axis=0, level=None, copy=True,
             - 'raise' will raise an AmbiguousTimeError if there are ambiguous
               times
         nonexistent : 'shift', 'NaT', default 'raise'
+            A nonexistent time doesn't not exist in a particular timezone
+            where clocks moved forward due to DST.
             - 'shift' will shift the nonexistent times forward to the closest
               existing time
             - 'NaT' will return NaT where there are nonexistent times

pandas/tests/indexes/datetimes/test_timezones.py

@@ -312,12 +312,12 @@ def test_dti_tz_localize_nonexistent_raise_coerce(self):
             index.tz_localize(tz=tz)
 
         with pytest.raises(pytz.NonExistentTimeError):
-            with tm.assert_produces_warning(FutureWarning,
-                                            check_stacklevel=False):
+            with tm.assert_produces_warning(FutureWarning):
                 index.tz_localize(tz=tz, errors='raise')
 
-        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False,
-                                        clear=FutureWarning):
+        with tm.assert_produces_warning(FutureWarning,
+                                        clear=FutureWarning,
+                                        check_stacklevel=False):
             result = index.tz_localize(tz=tz, errors='coerce')
         test_times = ['2015-03-08 01:00-05:00', 'NaT',
                       '2015-03-08 03:00-04:00']

pandas/tests/scalar/timestamp/test_timezones.py

@@ -87,18 +87,16 @@ def test_tz_localize_nonexistent(self, stamp, tz):
             ts.tz_localize(tz)
         # GH 22644
         with pytest.raises(NonExistentTimeError):
-            with tm.assert_produces_warning(FutureWarning,
-                                            check_stacklevel=False):
+            with tm.assert_produces_warning(FutureWarning):
                 ts.tz_localize(tz, errors='raise')
-        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+        with tm.assert_produces_warning(FutureWarning):
             assert ts.tz_localize(tz, errors='coerce') is NaT
 
     def test_tz_localize_errors_ambiguous(self):
         # GH#13057
         ts = Timestamp('2015-11-1 01:00')
         with pytest.raises(AmbiguousTimeError):
-            with tm.assert_produces_warning(FutureWarning,
-                                            check_stacklevel=False):
+            with tm.assert_produces_warning(FutureWarning):
                 ts.tz_localize('US/Pacific', errors='coerce')
 
     @pytest.mark.filterwarnings('ignore::FutureWarning')
@@ -107,16 +105,15 @@ def test_tz_localize_errors_invalid_arg(self):
         tz = 'Europe/Warsaw'
         ts = Timestamp('2015-03-29 02:00:00')
         with pytest.raises(ValueError):
-            with tm.assert_produces_warning(FutureWarning,
-                                            check_stacklevel=False):
+            with tm.assert_produces_warning(FutureWarning):
                 ts.tz_localize(tz, errors='foo')
 
     def test_tz_localize_errors_coerce(self):
         # GH 22644
         # make sure errors='coerce' gets mapped correctly to nonexistent
         tz = 'Europe/Warsaw'
         ts = Timestamp('2015-03-29 02:00:00')
-        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+        with tm.assert_produces_warning(FutureWarning):
             result = ts.tz_localize(tz, errors='coerce')
         expected = ts.tz_localize(tz, nonexistent='NaT')
         assert result is expected