From 899ec563532f14a8ed3b4949d9968b321d0703d2 Mon Sep 17 00:00:00 2001 From: Shreyas Date: Tue, 13 Aug 2024 18:04:00 +0530 Subject: [PATCH 1/2] unit, utcoffset, utctimetuple --- ci/code_checks.sh | 3 -- pandas/_libs/tslibs/nattype.pyx | 33 +++++++++++++++++++- pandas/_libs/tslibs/timestamps.pyx | 49 +++++++++++++++++++++++++++++- 3 files changed, 80 insertions(+), 5 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index b95774812f15e..8b14f911e873d 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -221,9 +221,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Timestamp.today SA01" \ -i "pandas.Timestamp.toordinal SA01" \ -i "pandas.Timestamp.tzinfo GL08" \ - -i "pandas.Timestamp.unit SA01" \ - -i "pandas.Timestamp.utcoffset SA01" \ - -i "pandas.Timestamp.utctimetuple SA01" \ -i "pandas.Timestamp.value GL08" \ -i "pandas.Timestamp.year GL08" \ -i "pandas.api.extensions.ExtensionArray._pad_or_backfill PR01,RT03,SA01" \ diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 60d1f21587218..fe3e0973a5b84 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -595,7 +595,23 @@ class NaTType(_NaT): utctimetuple = _make_error_func( "utctimetuple", """ - Return UTC time tuple, compatible with time.localtime(). + Return UTC time tuple, compatible with `time.localtime()`. + + This method converts the Timestamp to UTC and returns a time tuple + containing 9 components: year, month, day, hour, minute, second, + weekday, day of year, and DST flag. This is particularly useful for + converting a Timestamp to a format compatible with time module functions. + + Returns + ------- + time.struct_time + A time.struct_time object representing the UTC time. + + See Also + -------- + datetime.datetime.utctimetuple : Return UTC time tuple, compatible with time.localtime(). + Timestamp.timetuple : Return time tuple of local time. + time.struct_time : Time tuple structure used by time functions. Examples -------- @@ -612,6 +628,21 @@ class NaTType(_NaT): """ Return utc offset. + This method returns the difference between UTC and the local time + as a `timedelta` object. It is useful for understanding the time + difference between the current timezone and UTC. + + Returns + -------- + timedelta + The difference between UTC and the local time as a `timedelta` object. + + See Also + -------- + datetime.datetime.utcoffset : Standard library method to get the UTC offset of a datetime object. + Timestamp.tzname : Return the name of the timezone. + Timestamp.dst : Return the daylight saving time (DST) adjustment. + Examples -------- >>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels') diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 41fc5fc53daea..b1cad0ae1006d 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -254,6 +254,22 @@ cdef class _Timestamp(ABCTimestamp): """ The abbreviation associated with self._creso. + This property returns a string representing the time unit of the Timestamp's + resolution. It corresponds to the smallest time unit that can be represented + by this Timestamp object. The possible values are 's' (second), 'ms' (millisecond), + 'us' (microsecond), and 'ns' (nanosecond). + + Returns + ------- + str + A string abbreviation of the Timestamp's resolution unit: + 's' for second, 'ms' for millisecond, 'us' for microsecond, or 'ns' for nanosecond. + + See Also + -------- + Timestamp.resolution : Return resolution of the Timestamp. + Timedelta : A duration expressing the difference between two dates or times. + Examples -------- >>> pd.Timestamp("2020-01-01 12:34:56").unit @@ -1771,6 +1787,21 @@ class Timestamp(_Timestamp): """ Return utc offset. + This method returns the difference between UTC and the local time + as a `timedelta` object. It is useful for understanding the time + difference between the current timezone and UTC. + + Returns + -------- + timedelta + The difference between UTC and the local time as a `timedelta` object. + + See Also + -------- + datetime.datetime.utcoffset : Standard library method to get the UTC offset of a datetime object. + Timestamp.tzname : Return the name of the timezone. + Timestamp.dst : Return the daylight saving time (DST) adjustment. + Examples -------- >>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels') @@ -1783,7 +1814,23 @@ class Timestamp(_Timestamp): def utctimetuple(self): """ - Return UTC time tuple, compatible with time.localtime(). + Return UTC time tuple, compatible with `time.localtime()`. + + This method converts the Timestamp to UTC and returns a time tuple + containing 9 components: year, month, day, hour, minute, second, + weekday, day of year, and DST flag. This is particularly useful for + converting a Timestamp to a format compatible with time module functions. + + Returns + ------- + time.struct_time + A time.struct_time object representing the UTC time. + + See Also + -------- + datetime.datetime.utctimetuple : Return UTC time tuple, compatible with time.localtime(). + Timestamp.timetuple : Return time tuple of local time. + time.struct_time : Time tuple structure used by time functions. Examples -------- From 63fc472e2380262d23df06647780e4e96ee2923d Mon Sep 17 00:00:00 2001 From: Shreyas Date: Tue, 13 Aug 2024 20:46:01 +0530 Subject: [PATCH 2/2] Fix E501 line too long cython-lint --- pandas/_libs/tslibs/nattype.pyx | 6 ++++-- pandas/_libs/tslibs/timestamps.pyx | 18 +++++++++++++----- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index fe3e0973a5b84..547f95badab53 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -609,7 +609,8 @@ class NaTType(_NaT): See Also -------- - datetime.datetime.utctimetuple : Return UTC time tuple, compatible with time.localtime(). + datetime.datetime.utctimetuple : + Return UTC time tuple, compatible with time.localtime(). Timestamp.timetuple : Return time tuple of local time. time.struct_time : Time tuple structure used by time functions. @@ -639,7 +640,8 @@ class NaTType(_NaT): See Also -------- - datetime.datetime.utcoffset : Standard library method to get the UTC offset of a datetime object. + datetime.datetime.utcoffset : + Standard library method to get the UTC offset of a datetime object. Timestamp.tzname : Return the name of the timezone. Timestamp.dst : Return the daylight saving time (DST) adjustment. diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index b1cad0ae1006d..47e5af14460a8 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -256,14 +256,20 @@ cdef class _Timestamp(ABCTimestamp): This property returns a string representing the time unit of the Timestamp's resolution. It corresponds to the smallest time unit that can be represented - by this Timestamp object. The possible values are 's' (second), 'ms' (millisecond), - 'us' (microsecond), and 'ns' (nanosecond). + by this Timestamp object. The possible values are: + - 's' (second) + - 'ms' (millisecond) + - 'us' (microsecond) + - 'ns' (nanosecond) Returns ------- str A string abbreviation of the Timestamp's resolution unit: - 's' for second, 'ms' for millisecond, 'us' for microsecond, or 'ns' for nanosecond. + - 's' for second + - 'ms' for millisecond + - 'us' for microsecond + - 'ns' for nanosecond See Also -------- @@ -1798,7 +1804,8 @@ class Timestamp(_Timestamp): See Also -------- - datetime.datetime.utcoffset : Standard library method to get the UTC offset of a datetime object. + datetime.datetime.utcoffset : + Standard library method to get the UTC offset of a datetime object. Timestamp.tzname : Return the name of the timezone. Timestamp.dst : Return the daylight saving time (DST) adjustment. @@ -1828,7 +1835,8 @@ class Timestamp(_Timestamp): See Also -------- - datetime.datetime.utctimetuple : Return UTC time tuple, compatible with time.localtime(). + datetime.datetime.utctimetuple : + Return UTC time tuple, compatible with time.localtime(). Timestamp.timetuple : Return time tuple of local time. time.struct_time : Time tuple structure used by time functions.