diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 328fc26e4fef6..0bd4b78d51e4e 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -396,7 +396,7 @@ class NaTType(_NaT): Parameters ---------- locale : string, default None (English locale) - locale determining the language in which to return the month name + Locale determining the language in which to return the month name. Returns ------- @@ -411,7 +411,7 @@ class NaTType(_NaT): Parameters ---------- locale : string, default None (English locale) - locale determining the language in which to return the day name + Locale determining the language in which to return the day name. Returns ------- @@ -509,11 +509,11 @@ class NaTType(_NaT): Parameters ---------- ordinal : int - date corresponding to a proleptic Gregorian ordinal + Date corresponding to a proleptic Gregorian ordinal. freq : str, DateOffset - Offset which Timestamp will have + Offset to apply to the Timestamp. tz : str, pytz.timezone, dateutil.tz.tzfile or None - Time zone for time which Timestamp will have. + Time zone for the Timestamp. """) # _nat_methods @@ -534,7 +534,7 @@ class NaTType(_NaT): Parameters ---------- tz : str or timezone object, default None - Timezone to localize to + Timezone to localize to. """) today = _make_nat_func('today', # noqa:E128 """ @@ -547,7 +547,7 @@ class NaTType(_NaT): Parameters ---------- tz : str or timezone object, default None - Timezone to localize to + Timezone to localize to. """) round = _make_nat_func('round', # noqa:E128 """ @@ -555,27 +555,30 @@ class NaTType(_NaT): Parameters ---------- - freq : a freq string indicating the rounding resolution - ambiguous : bool, 'NaT', default 'raise' - - bool contains flags to determine if time is dst or not (note - that this flag is only applicable for ambiguous fall dst dates) - - 'NaT' will return NaT for an ambiguous time - - 'raise' will raise an AmbiguousTimeError for an ambiguous time + freq : str + Frequency string indicating the rounding resolution. + ambiguous : bool or {'raise', 'NaT'}, default 'raise' + The behavior is as follows: + + * bool contains flags to determine if time is dst or not (note + that this flag is only applicable for ambiguous fall dst dates). + * 'NaT' will return NaT for an ambiguous time. + * 'raise' will raise an AmbiguousTimeError for an ambiguous time. .. versionadded:: 0.24.0 - nonexistent : 'shift_forward', 'shift_backward, 'NaT', timedelta, \ -default 'raise' + nonexistent : {'raise', 'shift_forward', 'shift_backward, 'NaT', \ +timedelta}, default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - - 'shift_forward' will shift the nonexistent time forward to the - closest existing time - - 'shift_backward' will shift the nonexistent time backward to the - closest existing time - - 'NaT' will return NaT where there are nonexistent times - - timedelta objects will shift nonexistent times by the timedelta - - 'raise' will raise an NonExistentTimeError if there are - nonexistent times + * 'shift_forward' will shift the nonexistent time forward to the + closest existing time. + * 'shift_backward' will shift the nonexistent time backward to the + closest existing time. + * 'NaT' will return NaT where there are nonexistent times. + * timedelta objects will shift nonexistent times by the timedelta. + * 'raise' will raise an NonExistentTimeError if there are + nonexistent times. .. versionadded:: 0.24.0 @@ -593,33 +596,36 @@ default 'raise' Parameters ---------- - freq : a freq string indicating the flooring resolution - ambiguous : bool, 'NaT', default 'raise' - - bool contains flags to determine if time is dst or not (note - that this flag is only applicable for ambiguous fall dst dates) - - 'NaT' will return NaT for an ambiguous time - - 'raise' will raise an AmbiguousTimeError for an ambiguous time + freq : str + Frequency string indicating the flooring resolution. + ambiguous : bool or {'raise', 'NaT'}, default 'raise' + The behavior is as follows: + + * bool contains flags to determine if time is dst or not (note + that this flag is only applicable for ambiguous fall dst dates). + * 'NaT' will return NaT for an ambiguous time. + * 'raise' will raise an AmbiguousTimeError for an ambiguous time. .. versionadded:: 0.24.0 - nonexistent : 'shift_forward', 'shift_backward, 'NaT', timedelta, \ -default 'raise' + nonexistent : {'raise', 'shift_forward', 'shift_backward, 'NaT', \ +timedelta}, default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - - 'shift_forward' will shift the nonexistent time forward to the - closest existing time - - 'shift_backward' will shift the nonexistent time backward to the - closest existing time - - 'NaT' will return NaT where there are nonexistent times - - timedelta objects will shift nonexistent times by the timedelta - - 'raise' will raise an NonExistentTimeError if there are - nonexistent times + * 'shift_forward' will shift the nonexistent time forward to the + closest existing time. + * 'shift_backward' will shift the nonexistent time backward to the + closest existing time. + * 'NaT' will return NaT where there are nonexistent times. + * timedelta objects will shift nonexistent times by the timedelta. + * 'raise' will raise an NonExistentTimeError if there are + nonexistent times. .. versionadded:: 0.24.0 Raises ------ - ValueError if the freq cannot be converted + ValueError if the freq cannot be converted. """) ceil = _make_nat_func('ceil', # noqa:E128 """ @@ -627,33 +633,36 @@ default 'raise' Parameters ---------- - freq : a freq string indicating the ceiling resolution - ambiguous : bool, 'NaT', default 'raise' - - bool contains flags to determine if time is dst or not (note - that this flag is only applicable for ambiguous fall dst dates) - - 'NaT' will return NaT for an ambiguous time - - 'raise' will raise an AmbiguousTimeError for an ambiguous time + freq : str + Frequency string indicating the ceiling resolution. + ambiguous : bool or {'raise', 'NaT'}, default 'raise' + The behavior is as follows: + + * bool contains flags to determine if time is dst or not (note + that this flag is only applicable for ambiguous fall dst dates). + * 'NaT' will return NaT for an ambiguous time. + * 'raise' will raise an AmbiguousTimeError for an ambiguous time. .. versionadded:: 0.24.0 - nonexistent : 'shift_forward', 'shift_backward, 'NaT', timedelta, \ -default 'raise' + nonexistent : {'raise', 'shift_forward', 'shift_backward, 'NaT', \ +timedelta}, default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - - 'shift_forward' will shift the nonexistent time forward to the - closest existing time - - 'shift_backward' will shift the nonexistent time backward to the - closest existing time - - 'NaT' will return NaT where there are nonexistent times - - timedelta objects will shift nonexistent times by the timedelta - - 'raise' will raise an NonExistentTimeError if there are - nonexistent times + * 'shift_forward' will shift the nonexistent time forward to the + closest existing time. + * 'shift_backward' will shift the nonexistent time backward to the + closest existing time. + * 'NaT' will return NaT where there are nonexistent times. + * timedelta objects will shift nonexistent times by the timedelta. + * 'raise' will raise an NonExistentTimeError if there are + nonexistent times. .. versionadded:: 0.24.0 Raises ------ - ValueError if the freq cannot be converted + ValueError if the freq cannot be converted. """) tz_convert = _make_nat_func('tz_convert', # noqa:E128 @@ -694,35 +703,42 @@ default 'raise' `ambiguous` parameter dictates how ambiguous times should be handled. - - bool contains flags to determine if time is dst or not (note - that this flag is only applicable for ambiguous fall dst dates) - - 'NaT' will return NaT for an ambiguous time - - 'raise' will raise an AmbiguousTimeError for an ambiguous time + The behavior is as follows: + + * bool contains flags to determine if time is dst or not (note + that this flag is only applicable for ambiguous fall dst dates). + * 'NaT' will return NaT for an ambiguous time. + * 'raise' will raise an AmbiguousTimeError for an ambiguous time. nonexistent : 'shift_forward', 'shift_backward, 'NaT', timedelta, \ default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - - 'shift_forward' will shift the nonexistent time forward to the - closest existing time - - 'shift_backward' will shift the nonexistent time backward to the - closest existing time - - 'NaT' will return NaT where there are nonexistent times - - timedelta objects will shift nonexistent times by the timedelta - - 'raise' will raise an NonExistentTimeError if there are - nonexistent times + The behavior is as follows: - .. versionadded:: 0.24.0 + * 'shift_forward' will shift the nonexistent time forward to the + closest existing time. + * 'shift_backward' will shift the nonexistent time backward to the + closest existing time. + * 'NaT' will return NaT where there are nonexistent times. + * timedelta objects will shift nonexistent times by the timedelta. + * 'raise' will raise an NonExistentTimeError if there are + nonexistent times. + .. versionadded:: 0.24.0 errors : 'raise', 'coerce', default None - - 'raise' will raise a NonExistentTimeError if a timestamp is not - valid in the specified timezone (e.g. due to a transition from - or to DST time). Use ``nonexistent='raise'`` instead. - - 'coerce' will return NaT if the timestamp can not be converted + Determine how errors should be handled. + + The behavior is as follows: + + * 'raise' will raise a NonExistentTimeError if a timestamp is not + valid in the specified timezone (e.g. due to a transition from + or to DST time). Use ``nonexistent='raise'`` instead. + * 'coerce' will return NaT if the timestamp can not be converted into the specified timezone. Use ``nonexistent='NaT'`` instead. - .. deprecated:: 0.24.0 + .. deprecated:: 0.24.0 Returns ------- diff --git a/pandas/_libs/tslibs/timedeltas.pyx b/pandas/_libs/tslibs/timedeltas.pyx index b232042c70eac..f9cb35eb79ae3 100644 --- a/pandas/_libs/tslibs/timedeltas.pyx +++ b/pandas/_libs/tslibs/timedeltas.pyx @@ -1215,14 +1215,20 @@ class Timedelta(_Timedelta): Parameters ---------- value : Timedelta, timedelta, np.timedelta64, string, or integer - unit : str, optional - Denote the unit of the input, if input is an integer. Default 'ns'. + unit : str, default 'ns' + Denote the unit of the input, if input is an integer. + Possible values: - {'Y', 'M', 'W', 'D', 'days', 'day', 'hours', hour', 'hr', 'h', - 'm', 'minute', 'min', 'minutes', 'T', 'S', 'seconds', 'sec', 'second', - 'ms', 'milliseconds', 'millisecond', 'milli', 'millis', 'L', - 'us', 'microseconds', 'microsecond', 'micro', 'micros', 'U', - 'ns', 'nanoseconds', 'nano', 'nanos', 'nanosecond', 'N'} + + * 'Y', 'M', 'W', 'D', 'T', 'S', 'L', 'U', or 'N' + * 'days' or 'day' + * 'hours', 'hour', 'hr', or 'h' + * 'minutes', 'minute', 'min', or 'm' + * 'seconds', 'second', or 'sec' + * 'milliseconds', 'millisecond', 'millis', or 'milli' + * 'microseconds', 'microsecond', 'micros', or 'micro' + * 'nanoseconds', 'nanosecond', 'nanos', 'nano', or 'ns'. + **kwargs Available kwargs: {days, seconds, microseconds, milliseconds, minutes, hours, weeks}. @@ -1323,7 +1329,8 @@ class Timedelta(_Timedelta): Parameters ---------- - freq : a freq string indicating the rounding resolution + freq : str + Frequency string indicating the rounding resolution. Returns ------- @@ -1341,7 +1348,8 @@ class Timedelta(_Timedelta): Parameters ---------- - freq : a freq string indicating the flooring resolution + freq : str + Frequency string indicating the flooring resolution. """ return self._round(freq, np.floor) @@ -1351,7 +1359,8 @@ class Timedelta(_Timedelta): Parameters ---------- - freq : a freq string indicating the ceiling resolution + freq : str + Frequency string indicating the ceiling resolution. """ return self._round(freq, np.ceil) diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 6ca39d83afd25..c1575ce4f48b3 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -251,11 +251,11 @@ class Timestamp(_Timestamp): Parameters ---------- ordinal : int - date corresponding to a proleptic Gregorian ordinal + Date corresponding to a proleptic Gregorian ordinal. freq : str, DateOffset - Offset which Timestamp will have + Offset to apply to the Timestamp. tz : str, pytz.timezone, dateutil.tz.tzfile or None - Time zone for time which Timestamp will have. + Time zone for the Timestamp. """ return cls(datetime.fromordinal(ordinal), freq=freq, tz=tz) @@ -271,7 +271,7 @@ class Timestamp(_Timestamp): Parameters ---------- tz : str or timezone object, default None - Timezone to localize to + Timezone to localize to. """ if isinstance(tz, str): tz = maybe_get_tz(tz) @@ -289,7 +289,7 @@ class Timestamp(_Timestamp): Parameters ---------- tz : str or timezone object, default None - Timezone to localize to + Timezone to localize to. """ return cls.now(tz) @@ -445,27 +445,30 @@ class Timestamp(_Timestamp): Parameters ---------- - freq : a freq string indicating the rounding resolution - ambiguous : bool, 'NaT', default 'raise' - - bool contains flags to determine if time is dst or not (note - that this flag is only applicable for ambiguous fall dst dates) - - 'NaT' will return NaT for an ambiguous time - - 'raise' will raise an AmbiguousTimeError for an ambiguous time + freq : str + Frequency string indicating the rounding resolution. + ambiguous : bool or {'raise', 'NaT'}, default 'raise' + The behavior is as follows: + + * bool contains flags to determine if time is dst or not (note + that this flag is only applicable for ambiguous fall dst dates). + * 'NaT' will return NaT for an ambiguous time. + * 'raise' will raise an AmbiguousTimeError for an ambiguous time. .. versionadded:: 0.24.0 - nonexistent : 'shift_forward', 'shift_backward, 'NaT', timedelta, \ -default 'raise' + nonexistent : {'raise', 'shift_forward', 'shift_backward, 'NaT', \ +timedelta}, default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - - 'shift_forward' will shift the nonexistent time forward to the - closest existing time - - 'shift_backward' will shift the nonexistent time backward to the - closest existing time - - 'NaT' will return NaT where there are nonexistent times - - timedelta objects will shift nonexistent times by the timedelta - - 'raise' will raise an NonExistentTimeError if there are - nonexistent times + * 'shift_forward' will shift the nonexistent time forward to the + closest existing time. + * 'shift_backward' will shift the nonexistent time backward to the + closest existing time. + * 'NaT' will return NaT where there are nonexistent times. + * timedelta objects will shift nonexistent times by the timedelta. + * 'raise' will raise an NonExistentTimeError if there are + nonexistent times. .. versionadded:: 0.24.0 @@ -487,33 +490,36 @@ default 'raise' Parameters ---------- - freq : a freq string indicating the flooring resolution - ambiguous : bool, 'NaT', default 'raise' - - bool contains flags to determine if time is dst or not (note - that this flag is only applicable for ambiguous fall dst dates) - - 'NaT' will return NaT for an ambiguous time - - 'raise' will raise an AmbiguousTimeError for an ambiguous time + freq : str + Frequency string indicating the flooring resolution. + ambiguous : bool or {'raise', 'NaT'}, default 'raise' + The behavior is as follows: + + * bool contains flags to determine if time is dst or not (note + that this flag is only applicable for ambiguous fall dst dates). + * 'NaT' will return NaT for an ambiguous time. + * 'raise' will raise an AmbiguousTimeError for an ambiguous time. .. versionadded:: 0.24.0 - nonexistent : 'shift_forward', 'shift_backward, 'NaT', timedelta, \ -default 'raise' + nonexistent : {'raise', 'shift_forward', 'shift_backward, 'NaT', \ +timedelta}, default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - - 'shift_forward' will shift the nonexistent time forward to the - closest existing time - - 'shift_backward' will shift the nonexistent time backward to the - closest existing time - - 'NaT' will return NaT where there are nonexistent times - - timedelta objects will shift nonexistent times by the timedelta - - 'raise' will raise an NonExistentTimeError if there are - nonexistent times + * 'shift_forward' will shift the nonexistent time forward to the + closest existing time. + * 'shift_backward' will shift the nonexistent time backward to the + closest existing time. + * 'NaT' will return NaT where there are nonexistent times. + * timedelta objects will shift nonexistent times by the timedelta. + * 'raise' will raise an NonExistentTimeError if there are + nonexistent times. .. versionadded:: 0.24.0 Raises ------ - ValueError if the freq cannot be converted + ValueError if the freq cannot be converted. """ return self._round(freq, RoundTo.MINUS_INFTY, ambiguous, nonexistent) @@ -523,33 +529,36 @@ default 'raise' Parameters ---------- - freq : a freq string indicating the ceiling resolution - ambiguous : bool, 'NaT', default 'raise' - - bool contains flags to determine if time is dst or not (note - that this flag is only applicable for ambiguous fall dst dates) - - 'NaT' will return NaT for an ambiguous time - - 'raise' will raise an AmbiguousTimeError for an ambiguous time + freq : str + Frequency string indicating the ceiling resolution. + ambiguous : bool or {'raise', 'NaT'}, default 'raise' + The behavior is as follows: + + * bool contains flags to determine if time is dst or not (note + that this flag is only applicable for ambiguous fall dst dates). + * 'NaT' will return NaT for an ambiguous time. + * 'raise' will raise an AmbiguousTimeError for an ambiguous time. .. versionadded:: 0.24.0 - nonexistent : 'shift_forward', 'shift_backward, 'NaT', timedelta, \ -default 'raise' + nonexistent : {'raise', 'shift_forward', 'shift_backward, 'NaT', \ +timedelta}, default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - - 'shift_forward' will shift the nonexistent time forward to the - closest existing time - - 'shift_backward' will shift the nonexistent time backward to the - closest existing time - - 'NaT' will return NaT where there are nonexistent times - - timedelta objects will shift nonexistent times by the timedelta - - 'raise' will raise an NonExistentTimeError if there are - nonexistent times + * 'shift_forward' will shift the nonexistent time forward to the + closest existing time. + * 'shift_backward' will shift the nonexistent time backward to the + closest existing time. + * 'NaT' will return NaT where there are nonexistent times. + * timedelta objects will shift nonexistent times by the timedelta. + * 'raise' will raise an NonExistentTimeError if there are + nonexistent times. .. versionadded:: 0.24.0 Raises ------ - ValueError if the freq cannot be converted + ValueError if the freq cannot be converted. """ return self._round(freq, RoundTo.PLUS_INFTY, ambiguous, nonexistent) @@ -606,7 +615,7 @@ default 'raise' Parameters ---------- locale : string, default None (English locale) - locale determining the language in which to return the day name + Locale determining the language in which to return the day name. Returns ------- @@ -623,7 +632,7 @@ default 'raise' Parameters ---------- locale : string, default None (English locale) - locale determining the language in which to return the month name + Locale determining the language in which to return the month name. Returns ------- @@ -779,35 +788,42 @@ default 'raise' `ambiguous` parameter dictates how ambiguous times should be handled. - - bool contains flags to determine if time is dst or not (note - that this flag is only applicable for ambiguous fall dst dates) - - 'NaT' will return NaT for an ambiguous time - - 'raise' will raise an AmbiguousTimeError for an ambiguous time + The behavior is as follows: + + * bool contains flags to determine if time is dst or not (note + that this flag is only applicable for ambiguous fall dst dates). + * 'NaT' will return NaT for an ambiguous time. + * 'raise' will raise an AmbiguousTimeError for an ambiguous time. nonexistent : 'shift_forward', 'shift_backward, 'NaT', timedelta, \ default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - - 'shift_forward' will shift the nonexistent time forward to the - closest existing time - - 'shift_backward' will shift the nonexistent time backward to the - closest existing time - - 'NaT' will return NaT where there are nonexistent times - - timedelta objects will shift nonexistent times by the timedelta - - 'raise' will raise an NonExistentTimeError if there are - nonexistent times + The behavior is as follows: - .. versionadded:: 0.24.0 + * 'shift_forward' will shift the nonexistent time forward to the + closest existing time. + * 'shift_backward' will shift the nonexistent time backward to the + closest existing time. + * 'NaT' will return NaT where there are nonexistent times. + * timedelta objects will shift nonexistent times by the timedelta. + * 'raise' will raise an NonExistentTimeError if there are + nonexistent times. + .. versionadded:: 0.24.0 errors : 'raise', 'coerce', default None - - 'raise' will raise a NonExistentTimeError if a timestamp is not - valid in the specified timezone (e.g. due to a transition from - or to DST time). Use ``nonexistent='raise'`` instead. - - 'coerce' will return NaT if the timestamp can not be converted + Determine how errors should be handled. + + The behavior is as follows: + + * 'raise' will raise a NonExistentTimeError if a timestamp is not + valid in the specified timezone (e.g. due to a transition from + or to DST time). Use ``nonexistent='raise'`` instead. + * 'coerce' will return NaT if the timestamp can not be converted into the specified timezone. Use ``nonexistent='NaT'`` instead. - .. deprecated:: 0.24.0 + .. deprecated:: 0.24.0 Returns -------