BUG: pandas.date_range() raises NonExistentTimeError despite nonexistent="shift_forward" when crossing DST boundaries

This fixes GH#62602 where `date_range` failed for nonexistent times during
DST transitions due to `Timestamp.normalize` not handling `ambiguous` and
`nonexistent` parameters.

Changes:
- Updated `Timestamp.normalize` (in `_libs/tslibs/timestamps.pyx`):
  * Added `ambiguous` and `nonexistent` keyword arguments (defaulting to "raise").
  * Passed these parameters to `tz_localize` to properly handle DST-related
    ambiguous and nonexistent timestamps.
- Updated type stubs in `timestamps.pyi` to reflect the new method signature.
- Extended `_maybe_normalize_endpoints` (in `core/arrays/datetimes.py`):
  * Added support for `ambiguous` and `nonexistent` parameters.
  * Updated internal normalization calls to propagate these parameters.
- Updated `DatetimeArray._generate_range` logic to ensure consistent propagation
  of `ambiguous` and `nonexistent` through `_maybe_normalize_endpoints` both
  before and after timezone handling.

With these changes, `date_range` now correctly handles cases where normalization
intersects DST transitions, preserving expected behavior and avoiding
`NonExistentTimeError` or `AmbiguousTimeError` exceptions.

Co-authored-by: Mohamed Sobhy <[email protected]>

Author: msobhyy10

pandas/_libs/tslibs/timestamps.pyi

@@ -191,7 +191,11 @@ class Timestamp(datetime):
         ambiguous: bool | Literal["raise", "NaT"] = ...,
         nonexistent: TimestampNonexistent = ...,
     ) -> Self: ...
-    def normalize(self) -> Self: ...
+    def normalize(
+        self,
+        ambiguous: bool | Literal["raise", "NaT"] = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> Self: ...
     # TODO: round/floor/ceil could return NaT?
     def round(
         self,

pandas/_libs/tslibs/timestamps.pyx

@@ -1308,7 +1308,7 @@ cdef class _Timestamp(ABCTimestamp):
     # -----------------------------------------------------------------
     # Transformation Methods
 
-    def normalize(self) -> "Timestamp":
+    def normalize(self, ambiguous="raise", nonexistent="raise") -> "Timestamp":
         """
         Normalize Timestamp to midnight, preserving tz information.
 
@@ -1346,7 +1346,7 @@ cdef class _Timestamp(ABCTimestamp):
                 "Cannot normalize Timestamp without integer overflow"
             ) from err
         ts = type(self)._from_value_and_reso(normalized, reso=self._creso, tz=None)
-        return ts.tz_localize(self.tzinfo)
+        return ts.tz_localize(self.tzinfo, ambiguous=ambiguous, nonexistent=nonexistent)
 
     # -----------------------------------------------------------------
     # Pickle Methods

pandas/core/arrays/datetimes.py

@@ -447,7 +447,9 @@ def _generate_range(
             end = end.as_unit(unit, round_ok=False)
 
         left_inclusive, right_inclusive = validate_inclusive(inclusive)
-        start, end = _maybe_normalize_endpoints(start, end, normalize)
+        start, end = _maybe_normalize_endpoints(
+            start, end, normalize, ambiguous, nonexistent
+        )
         tz = _infer_tz_from_endpoints(start, end, tz)
 
         if tz is not None:
@@ -466,6 +468,10 @@ def _generate_range(
                 if end is not None and end.tz is not None:
                     end = end.tz_localize(None)
 
+                start, end = _maybe_normalize_endpoints(
+                    start, end, normalize, ambiguous, nonexistent
+                )
+
             if isinstance(freq, (Tick, Day)):
                 i8values = generate_regular_range(start, end, periods, freq, unit=unit)
             else:
@@ -2878,14 +2884,18 @@ def _infer_tz_from_endpoints(
 
 
 def _maybe_normalize_endpoints(
-    start: _TimestampNoneT1, end: _TimestampNoneT2, normalize: bool
+    start: _TimestampNoneT1,
+    end: _TimestampNoneT2,
+    normalize: bool,
+    ambiguous: TimeAmbiguous = "raise",
+    nonexistent: TimeNonexistent = "raise",
 ) -> tuple[_TimestampNoneT1, _TimestampNoneT2]:
     if normalize:
         if start is not None:
-            start = start.normalize()
+            start = start.normalize(ambiguous, nonexistent)
 
         if end is not None:
-            end = end.normalize()
+            end = end.normalize(ambiguous, nonexistent)
 
     return start, end