diff --git a/ci/code_checks.sh b/ci/code_checks.sh index dbfe0230d835c..a9a4daa2e2059 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -195,9 +195,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Timestamp.month GL08" \ -i "pandas.Timestamp.month_name SA01" \ -i "pandas.Timestamp.nanosecond GL08" \ - -i "pandas.Timestamp.normalize SA01" \ -i "pandas.Timestamp.quarter SA01" \ - -i "pandas.Timestamp.replace PR07,SA01" \ -i "pandas.Timestamp.resolution PR02" \ -i "pandas.Timestamp.second GL08" \ -i "pandas.Timestamp.strptime PR01,SA01" \ @@ -206,8 +204,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Timestamp.timetz SA01" \ -i "pandas.Timestamp.to_datetime64 SA01" \ -i "pandas.Timestamp.to_julian_date SA01" \ - -i "pandas.Timestamp.to_numpy PR01" \ - -i "pandas.Timestamp.to_period PR01,SA01" \ -i "pandas.Timestamp.today SA01" \ -i "pandas.Timestamp.toordinal SA01" \ -i "pandas.Timestamp.tzinfo GL08" \ diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 547f95badab53..3cb4dda1cd273 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -251,6 +251,13 @@ cdef class _NaT(datetime): The copy parameter is available here only for compatibility. Its value will not affect the return value. + Parameters + ---------- + dtype : numpy.dtype, default None + Must be None. Otherwise, a ValueError is raised. + copy : bool, default False + Must be False. Otherwise, a ValueError is raised. + Returns ------- numpy.datetime64 or numpy.timedelta64 @@ -1518,23 +1525,44 @@ default 'raise' """ Implements datetime.replace, handles nanoseconds. + Returns a new timestamp with the same attributes, + except for those given new value. + Parameters ---------- year : int, optional + New year value. month : int, optional + New month value. day : int, optional + New day value. hour : int, optional + New hour value. minute : int, optional + New minute value. second : int, optional + New second value. microsecond : int, optional + New microsecond value. nanosecond : int, optional + New nanosecond value. tzinfo : tz-convertible, optional + New tzinfo value. fold : int, optional + New fold value. Returns ------- Timestamp with fields replaced + See Also + -------- + Timestamp.normalize : Normalize the Timestamp to midnight, + preserving tz information. + Timestamp.tz_convert : Convert timezone-aware Timestamp to another time zone. + Timestamp.tz_localize : Localize the Timestamp to a timezone. + datetime.datetime.replace : Return a new datetime with replaced attributes. + Examples -------- Create a timestamp object: diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 47e5af14460a8..1cbb24084a62b 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -975,7 +975,13 @@ cdef class _Timestamp(ABCTimestamp): def normalize(self) -> "Timestamp": """ - Normalize Timestamp to midnight, preserving tz information. + Normalize Timestamp to previous midnight, preserving tz information. + + This is equivalent to replacing the time part of the timestamp with `00:00:00`. + + See Also + -------- + Timestamp.replace : Return a new timestamp with replaced attributes. Examples -------- @@ -1298,6 +1304,13 @@ cdef class _Timestamp(ABCTimestamp): copy parameters are available here only for compatibility. Their values will not affect the return value. + Parameters + ---------- + dtype : numpy.dtype, default None + Must be None. Otherwise, a ValueError is raised. + copy : bool, default False + Must be False. Otherwise, a ValueError is raised. + Returns ------- numpy.datetime64 @@ -1325,7 +1338,24 @@ cdef class _Timestamp(ABCTimestamp): def to_period(self, freq=None): """ - Return an period of which this timestamp is an observation. + Return a period of which this timestamp is an observation. + + This method constructs a `Period` object from the `Timestamp` + and provided period. + Please note that timezone information will be dropped, + since `Period` doesn't support timezones. + + Parameters + ---------- + freq : str, default None + The period frequency. Accepted strings are listed in + the :ref:`period alias section ` + in the user docs. + + See Also + -------- + Period : Represents a period of time. + Period.to_timestamp : Return the Timestamp representation of the Period. Examples -------- @@ -2687,23 +2717,44 @@ default 'raise' """ Implements datetime.replace, handles nanoseconds. + Returns a new timestamp with the same attributes, + except for those given new value. + Parameters ---------- year : int, optional + New year value. month : int, optional + New month value. day : int, optional + New day value. hour : int, optional + New hour value. minute : int, optional + New minute value. second : int, optional + New second value. microsecond : int, optional + New microsecond value. nanosecond : int, optional + New nanosecond value. tzinfo : tz-convertible, optional + New tzinfo value. fold : int, optional + New fold value. Returns ------- Timestamp with fields replaced + See Also + -------- + Timestamp.normalize : Normalize the Timestamp to midnight, + preserving tz information. + Timestamp.tz_convert : Convert timezone-aware Timestamp to another time zone. + Timestamp.tz_localize : Localize the Timestamp to a timezone. + datetime.datetime.replace : Return a new datetime with replaced attributes. + Examples -------- Create a timestamp object: