ENH: add fold support to Timestamp constructor

doc/source/user_guide/timeseries.rst

@@ -2220,6 +2220,22 @@ you can use the ``tz_convert`` method.
 
    rng_pytz.tz_convert('US/Eastern')
 
+.. versionadded:: 1.1.0
+
+For ambiguous times, pandas supports explicitly specifying the fold argument.
+Due to daylight saving time, one wall clock time can occur twice when shifting
+from summer to winter time; fold describes whether the datetime-like corresponds
+to the first (0) or the second time (1) the wall clock hits the ambiguous time.
+Fold is supported only for constructing from naive datetime or :class:`Timestamp`
+or for constructing from components (see below).
+
+.. ipython:: python
+
+   pd.Timestamp(datetime.datetime(2019, 10, 27, 1, 30, 0, 0),
+                tz='dateutil/Europe/London', fold=0)
+   pd.Timestamp(year=2019, month=10, day=27, hour=1, minute=30,
+                tz='dateutil/Europe/London', fold=1)
+
 .. note::
 
     When using ``pytz`` time zones, :class:`DatetimeIndex` will construct a different

doc/source/whatsnew/v1.1.0.rst

@@ -36,6 +36,26 @@ For example:
    ser["2014"]
    ser.loc["May 2015"]
 
+.. _whatsnew_110.timestamp_fold_support:
+
+Fold argument support in Timestamp constructor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:class:`Timestamp: now supports the fold argument according to PEP 495 similar to parent `pydatetime` class. It supports both accepting fold as an initialization argument and inferring fold from other constructor arguments (:issue:`25057`, :issue:`31338`).
+
+For example:
+
+.. ipython:: python
+
+    ts = pd.Timestamp("2019-10-27 01:30:00+00:00")
+    ts.fold
+
+.. ipython:: python
+
+    ts = pd.Timestamp(year=2019, month=10, day=27, hour=1, minute=30,
+                      tz="dateutil/Europe/London", fold=1)
+    ts
+
 .. _whatsnew_110.enhancements.other:
 
 Other enhancements

pandas/_libs/tslib.pyx

@@ -49,30 +49,31 @@ from pandas._libs.tslibs.tzconversion cimport (
 
 cdef inline object create_datetime_from_ts(
         int64_t value, npy_datetimestruct dts,
-        object tz, object freq):
+        object tz, object freq, bint fold):
     """ convenience routine to construct a datetime.datetime from its parts """
     return datetime(dts.year, dts.month, dts.day, dts.hour,
-                    dts.min, dts.sec, dts.us, tz)
+                    dts.min, dts.sec, dts.us, tz, fold=fold)
 
 
 cdef inline object create_date_from_ts(
         int64_t value, npy_datetimestruct dts,
-        object tz, object freq):
+        object tz, object freq, bint fold):
     """ convenience routine to construct a datetime.date from its parts """
+    # GH 25057 add fold argument to match other func_create signatures
     return date(dts.year, dts.month, dts.day)
 
 
 cdef inline object create_time_from_ts(
         int64_t value, npy_datetimestruct dts,
-        object tz, object freq):
+        object tz, object freq, bint fold):
     """ convenience routine to construct a datetime.time from its parts """
-    return time(dts.hour, dts.min, dts.sec, dts.us, tz)
+    return time(dts.hour, dts.min, dts.sec, dts.us, tz, fold=fold)
 
 
 @cython.wraparound(False)
 @cython.boundscheck(False)
 def ints_to_pydatetime(const int64_t[:] arr, object tz=None, object freq=None,
-                       str box="datetime"):
+                       bint fold=0, str box="datetime"):
     """
     Convert an i8 repr to an ndarray of datetimes, date, time or Timestamp
 
@@ -83,6 +84,11 @@ def ints_to_pydatetime(const int64_t[:] arr, object tz=None, object freq=None,
          convert to this timezone
     freq : str/Offset, default None
          freq to convert
+    fold : bint, default is 0
+        Due to daylight saving time, one wall clock time can occur twice
+        when shifting from summer to winter time; fold describes whether the
+        datetime-like corresponds  to the first (0) or the second time (1)
+        the wall clock hits the ambiguous time
     box  : {'datetime', 'timestamp', 'date', 'time'}, default 'datetime'
          If datetime, convert to datetime.datetime
          If date, convert to datetime.date
@@ -104,7 +110,7 @@ def ints_to_pydatetime(const int64_t[:] arr, object tz=None, object freq=None,
         str typ
         int64_t value, delta, local_value
         ndarray[object] result = np.empty(n, dtype=object)
-        object (*func_create)(int64_t, npy_datetimestruct, object, object)
+        object (*func_create)(int64_t, npy_datetimestruct, object, object, bint)
 
     if box == "date":
         assert (tz is None), "tz should be None when converting to date"
@@ -129,7 +135,7 @@ def ints_to_pydatetime(const int64_t[:] arr, object tz=None, object freq=None,
                 result[i] = <object>NaT
             else:
                 dt64_to_dtstruct(value, &dts)
-                result[i] = func_create(value, dts, tz, freq)
+                result[i] = func_create(value, dts, tz, freq, fold)
     elif is_tzlocal(tz):
         for i in range(n):
             value = arr[i]
@@ -141,7 +147,7 @@ def ints_to_pydatetime(const int64_t[:] arr, object tz=None, object freq=None,
                 # using the i8 representation.
                 local_value = tz_convert_utc_to_tzlocal(value, tz)
                 dt64_to_dtstruct(local_value, &dts)
-                result[i] = func_create(value, dts, tz, freq)
+                result[i] = func_create(value, dts, tz, freq, fold)
     else:
         trans, deltas, typ = get_dst_info(tz)
 
@@ -155,7 +161,7 @@ def ints_to_pydatetime(const int64_t[:] arr, object tz=None, object freq=None,
                 else:
                     # Adjust datetime64 timestamp, recompute datetimestruct
                     dt64_to_dtstruct(value + delta, &dts)
-                    result[i] = func_create(value, dts, tz, freq)
+                    result[i] = func_create(value, dts, tz, freq, fold)
 
         elif typ == 'dateutil':
             # no zone-name change for dateutil tzs - dst etc
@@ -168,7 +174,7 @@ def ints_to_pydatetime(const int64_t[:] arr, object tz=None, object freq=None,
                     # Adjust datetime64 timestamp, recompute datetimestruct
                     pos = trans.searchsorted(value, side='right') - 1
                     dt64_to_dtstruct(value + deltas[pos], &dts)
-                    result[i] = func_create(value, dts, tz, freq)
+                    result[i] = func_create(value, dts, tz, freq, fold)
         else:
             # pytz
             for i in range(n):
@@ -182,7 +188,7 @@ def ints_to_pydatetime(const int64_t[:] arr, object tz=None, object freq=None,
                     new_tz = tz._tzinfos[tz._transition_info[pos]]
 
                     dt64_to_dtstruct(value + deltas[pos], &dts)
-                    result[i] = func_create(value, dts, new_tz, freq)
+                    result[i] = func_create(value, dts, new_tz, freq, fold)
 
     return result
 

pandas/_libs/tslibs/conversion.pxd

@@ -12,6 +12,7 @@ cdef class _TSObject:
         npy_datetimestruct dts      # npy_datetimestruct
         int64_t value               # numpy dt64
         object tzinfo
+        bint fold
 
 
 cdef convert_to_tsobject(object ts, object tz, object unit,

pandas/_libs/tslibs/conversion.pyx

@@ -216,6 +216,7 @@ cdef class _TSObject:
     #    npy_datetimestruct dts      # npy_datetimestruct
     #    int64_t value               # numpy dt64
     #    object tzinfo
+    #    bint fold
 
     @property
     def value(self):
@@ -323,6 +324,7 @@ cdef _TSObject convert_datetime_to_tsobject(datetime ts, object tz,
     cdef:
         _TSObject obj = _TSObject()
 
+    obj.fold = ts.fold
     if tz is not None:
         tz = maybe_get_tz(tz)
 
@@ -355,6 +357,24 @@ cdef _TSObject convert_datetime_to_tsobject(datetime ts, object tz,
         obj.value += nanos
         obj.dts.ps = nanos * 1000
 
+    if tz is not None:
+        if is_utc(tz) or is_tzlocal(tz):
+            # TODO: think on how we can infer fold for local Timezone
+            # and adjust value for fold
+            pass
+        else:
+            trans, deltas, typ = get_dst_info(tz)
+
+            if typ in ['pytz', 'dateutil']:
+                pos = trans.searchsorted(obj.value, side='right') - 1
+                # pytz assumes fold == 1, dateutil fold == 0
+                # adjust only if necessary
+                if (typ == 'pytz' and obj.fold == 0 or
+                        typ == 'dateutil' and obj.fold == 1):
+                    pos = _adjust_tsobject_for_fold(obj, trans, deltas, pos,
+                                                    obj.fold)
+                obj.fold = _infer_tsobject_fold(obj, trans, deltas, pos)
+
     check_dts_bounds(&obj.dts)
     check_overflows(obj)
     return obj
@@ -381,6 +401,7 @@ cdef _TSObject create_tsobject_tz_using_offset(npy_datetimestruct dts,
         _TSObject obj = _TSObject()
         int64_t value  # numpy dt64
         datetime dt
+        bint fold
 
     value = dtstruct_to_dt64(&dts)
     obj.dts = dts
@@ -390,10 +411,22 @@ cdef _TSObject create_tsobject_tz_using_offset(npy_datetimestruct dts,
         check_overflows(obj)
         return obj
 
+    # Infer fold from offset-adjusted obj.value
+    if is_utc(tz) or is_tzlocal(tz):
+        # TODO: think on how we can infer fold for local Timezone
+        # and adjust value for fold
+        pass
+    else:
+        trans, deltas, typ = get_dst_info(tz)
+
+        if typ in ['pytz', 'dateutil']:
+            pos = trans.searchsorted(obj.value, side='right') - 1
+            fold = _infer_tsobject_fold(obj, trans, deltas, pos)
+
     # Keep the converter same as PyDateTime's
     dt = datetime(obj.dts.year, obj.dts.month, obj.dts.day,
                   obj.dts.hour, obj.dts.min, obj.dts.sec,
-                  obj.dts.us, obj.tzinfo)
+                  obj.dts.us, obj.tzinfo, fold=fold)
     obj = convert_datetime_to_tsobject(
         dt, tz, nanos=obj.dts.ps // 1000)
     return obj
@@ -528,7 +561,7 @@ cdef inline void localize_tso(_TSObject obj, tzinfo tz):
 
     Notes
     -----
-    Sets obj.tzinfo inplace, alters obj.dts inplace.
+    Sets obj.tzinfo inplace, alters obj.dts inplace, alters obj.value inplace.
     """
     cdef:
         ndarray[int64_t] trans
@@ -546,6 +579,8 @@ cdef inline void localize_tso(_TSObject obj, tzinfo tz):
     elif is_tzlocal(tz):
         local_val = _tz_convert_tzlocal_utc(obj.value, tz, to_utc=False)
         dt64_to_dtstruct(local_val, &obj.dts)
+        # TODO: think on how we can infer fold for local Timezone
+        # and adjust value for fold
     else:
         # Adjust datetime64 timestamp, recompute datetimestruct
         trans, deltas, typ = get_dst_info(tz)
@@ -554,15 +589,13 @@ cdef inline void localize_tso(_TSObject obj, tzinfo tz):
             # static/fixed tzinfo; in this case we know len(deltas) == 1
             # This can come back with `typ` of either "fixed" or None
             dt64_to_dtstruct(obj.value + deltas[0], &obj.dts)
-        elif typ == 'pytz':
-            # i.e. treat_tz_as_pytz(tz)
-            pos = trans.searchsorted(obj.value, side='right') - 1
-            tz = tz._tzinfos[tz._transition_info[pos]]
-            dt64_to_dtstruct(obj.value + deltas[pos], &obj.dts)
-        elif typ == 'dateutil':
-            # i.e. treat_tz_as_dateutil(tz)
+        elif typ in ['pytz', 'dateutil']:
             pos = trans.searchsorted(obj.value, side='right') - 1
+            if typ == 'pytz':
+                tz = tz._tzinfos[tz._transition_info[pos]]
             dt64_to_dtstruct(obj.value + deltas[pos], &obj.dts)
+
+            obj.fold = _infer_tsobject_fold(obj, trans, deltas, pos)
         else:
             # Note: as of 2018-07-17 all tzinfo objects that are _not_
             # either pytz or dateutil have is_fixed_offset(tz) == True,
@@ -572,6 +605,87 @@ cdef inline void localize_tso(_TSObject obj, tzinfo tz):
     obj.tzinfo = tz
 
 
+cdef inline int32_t _adjust_tsobject_for_fold(_TSObject obj, object trans,
+                                              object deltas, int32_t pos,
+                                              bint fold):
+    """
+    Adjust _TSObject value for fold is possible. Return updated last offset
+    transition position in the trans list.
+
+    Parameters
+    ----------
+    obj : _TSObject
+    trans : object
+        List of offset transition points in nanoseconds since epoch.
+    deltas : object
+        List of offsets corresponding to transition points in trans.
+    pos : int32_t
+        Position of the last transition point before taking fold into account.
+    fold : bint
+        Due to daylight saving time, one wall clock time can occur twice
+        when shifting from summer to winter time; fold describes whether the
+        datetime-like corresponds  to the first (0) or the second time (1)
+        the wall clock hits the ambiguous time
+
+    Returns
+    -------
+    int32_t
+        Position of the last transition point after taking fold into account.
+
+    Notes
+    -----
+    Alters obj.value inplace.
+    """
+    if fold == 0:
+        if pos > 0:
+            fold_delta = deltas[pos - 1] - deltas[pos]
+            if obj.value - fold_delta < trans[pos]:
+                obj.value -= fold_delta
+                pos -= 1
+    elif fold == 1:
+        if pos < len(deltas):
+            fold_delta = deltas[pos] - deltas[pos + 1]
+            if obj.value + fold_delta > trans[pos + 1]:
+                obj.value += fold_delta
+                pos += 1
+
+    return pos
+
+
+cdef inline bint _infer_tsobject_fold(_TSObject obj, object trans,
+                                      object deltas, int32_t pos):
+    """
+    Infer _TSObject fold property from value by assuming 0 and then setting
+    to 1 if necessary.
+
+    Parameters
+    ----------
+    obj : _TSObject
+    trans : object
+        List of offset transition points in nanoseconds since epoch.
+    deltas : object
+        List of offsets corresponding to transition points in trans.
+    pos : int32_t
+        Position of the last transition point before taking fold into account.
+
+    Returns
+    -------
+    bint
+        Due to daylight saving time, one wall clock time can occur twice
+        when shifting from summer to winter time; fold describes whether the
+        datetime-like corresponds  to the first (0) or the second time (1)
+        the wall clock hits the ambiguous time
+    """
+    cdef:
+        bint fold = 0
+
+    if pos > 0:
+        fold_delta = deltas[pos - 1] - deltas[pos]
+        if obj.value - fold_delta < trans[pos]:
+            fold = 1
+
+    return fold
+
 cdef inline datetime _localize_pydatetime(datetime dt, tzinfo tz):
     """
     Take a datetime/Timestamp in UTC and localizes to timezone tz.

pandas/_libs/tslibs/timestamps.pxd

@@ -5,4 +5,4 @@ from pandas._libs.tslibs.np_datetime cimport npy_datetimestruct
 
 cdef object create_timestamp_from_ts(int64_t value,
                                      npy_datetimestruct dts,
-                                     object tz, object freq)
+                                     object tz, object freq, bint fold)