From d7032109d0798880f615f8fad0039d45ff454e9e Mon Sep 17 00:00:00 2001 From: Eduard Akhmetshin Date: Fri, 9 Aug 2024 16:30:43 +0100 Subject: [PATCH 1/3] Fix docstrings for Timestamp: normalize, replace, to_numpy, to_period --- ci/code_checks.sh | 4 --- pandas/_libs/tslibs/timestamps.pyx | 49 ++++++++++++++++++++++++++++-- 2 files changed, 47 insertions(+), 6 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 692b86ec731c9..973e31815cf63 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -218,9 +218,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" \ @@ -229,8 +227,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.tz_localize SA01" \ diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 369184d9df40c..c1eb257cd2471 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -953,7 +953,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 -------- @@ -1276,6 +1282,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 @@ -1303,7 +1316,20 @@ 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 -------- @@ -2603,23 +2629,42 @@ 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: From ada20a5d2e7c59a5cb9193abc406e609a8153794 Mon Sep 17 00:00:00 2001 From: Eduard Akhmetshin Date: Fri, 9 Aug 2024 16:43:04 +0100 Subject: [PATCH 2/3] Fix lint errors --- pandas/_libs/tslibs/timestamps.pyx | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index c1eb257cd2471..7cb9c852ea1e3 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -1318,13 +1318,17 @@ cdef class _Timestamp(ABCTimestamp): """ 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. + 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. + The period frequency. Accepted strings are listed in + the :ref:`period alias section ` + in the user docs. See Also -------- @@ -2629,7 +2633,8 @@ default 'raise' """ Implements datetime.replace, handles nanoseconds. - Returns a new timestamp with the same attributes, except for those given new value. + Returns a new timestamp with the same attributes, + except for those given new value. Parameters ---------- @@ -2660,7 +2665,8 @@ default 'raise' See Also -------- - Timestamp.normalize : Normalize the Timestamp to midnight, preserving tz information. + 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. From a941c03aa8040c4e8821290e67928ac8b2a4b4fb Mon Sep 17 00:00:00 2001 From: Eduard Akhmetshin Date: Mon, 19 Aug 2024 18:06:39 +0100 Subject: [PATCH 3/3] Fix NaT docstrings --- pandas/_libs/tslibs/nattype.pyx | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 130e41e5104a2..6ae5a96c428c2 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 @@ -1456,23 +1463,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: