From 0d7e77cfe8672b92ff9ade27106f2bcbc648b520 Mon Sep 17 00:00:00 2001
From: John Hendricks <jwh8zc@virginia.edu>
Date: Fri, 14 Mar 2025 07:47:58 -0400
Subject: [PATCH 1/2] Added docstrings to min/max/reso for Timedelta
---
ci/code_checks.sh | 3 --
pandas/_libs/tslibs/timedeltas.pyx | 83 +++++++++++++++++++++++++++---
2 files changed, 77 insertions(+), 9 deletions(-)
diff --git a/ci/code_checks.sh b/ci/code_checks.sh
index 6ce43725fecc9..6700a235c25be 100755
--- a/ci/code_checks.sh
+++ b/ci/code_checks.sh
@@ -72,9 +72,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
-i "pandas.Series.dt PR01" `# Accessors are implemented as classes, but we do not document the Parameters section` \
-i "pandas.Period.freq GL08" \
-i "pandas.Period.ordinal GL08" \
- -i "pandas.Timedelta.max PR02" \
- -i "pandas.Timedelta.min PR02" \
- -i "pandas.Timedelta.resolution PR02" \
-i "pandas.Timestamp.max PR02" \
-i "pandas.Timestamp.min PR02" \
-i "pandas.Timestamp.resolution PR02" \
diff --git a/pandas/_libs/tslibs/timedeltas.pyx b/pandas/_libs/tslibs/timedeltas.pyx
index 36fe29b2146b7..9505ceacba5ee 100644
--- a/pandas/_libs/tslibs/timedeltas.pyx
+++ b/pandas/_libs/tslibs/timedeltas.pyx
@@ -998,8 +998,9 @@ class MinMaxReso:
and Timedelta class. On an instance, these depend on the object's _reso.
On the class, we default to the values we would get with nanosecond _reso.
"""
- def __init__(self, name):
+ def __init__(self, name, docstring):
self._name = name
+ self.__doc__ = docstring
def __get__(self, obj, type=None):
if self._name == "min":
@@ -1012,9 +1013,13 @@ class MinMaxReso:
if obj is None:
# i.e. this is on the class, default to nanos
- return Timedelta(val)
+ result = Timedelta(val)
else:
- return Timedelta._from_value_and_reso(val, obj._creso)
+ result = Timedelta._from_value_and_reso(val, obj._creso)
+
+ result.__doc__ = self.__doc__
+
+ return result
def __set__(self, obj, value):
raise AttributeError(f"{self._name} is not settable.")
@@ -1033,9 +1038,75 @@ cdef class _Timedelta(timedelta):
# higher than np.ndarray and np.matrix
__array_priority__ = 100
- min = MinMaxReso("min")
- max = MinMaxReso("max")
- resolution = MinMaxReso("resolution")
+
+ docstring_min = """
+ Returns the minimum bound possible for Timedelta.
+
+ This property provides access to the smallest possible value that
+ can be represented by a Timedelta object.
+
+ Returns
+ -------
+ Timedelta
+
+ See Also
+ --------
+ Timedelta.max: Returns the maximum bound possible for Timedelta.
+ Timedelta.resolution: Returns the smallest possible difference between
+ non-equal Timedelta objects.
+
+ Examples
+ --------
+ >>> pd.Timedelta.min
+ -106752 days +00:12:43.145224193
+ """
+
+ docstring_max = """
+ Returns the maximum bound possible for Timedelta.
+
+ This property provides access to the largest possible value that
+ can be represented by a Timedelta object.
+
+ Returns
+ -------
+ Timedelta
+
+ See Also
+ --------
+ Timedelta.min: Returns the minimum bound possible for Timedelta.
+ Timedelta.resolution: Returns the smallest possible difference between
+ non-equal Timedelta objects.
+
+ Examples
+ --------
+ >>> pd.Timedelta.max
+ 106751 days 23:47:16.854775807
+ """
+
+ docstring_reso = """
+ Returns the smallest possible difference between non-equal Timedelta objects.
+
+ The resolution value is determined by the underlying representation of time
+ units and is equivalent to Timedelta(nanoseconds=1).
+
+ Returns
+ -------
+ Timedelta
+
+ See Also
+ --------
+ Timedelta.max: Returns the maximum bound possible for Timedelta.
+ Timedelta.min: Returns the minimum bound possible for Timedelta.
+
+ Examples
+ --------
+ >>> pd.Timedelta.resolution
+ 0 days 00:00:00.000000001
+ """
+
+ min = MinMaxReso("min", docstring_min)
+ max = MinMaxReso("max", docstring_max)
+ resolution = MinMaxReso("resolution", docstring_reso)
@property
def value(self):
From dc4b5ae8c4b5672e373bcc4a3a1c53bc3bfcd228 Mon Sep 17 00:00:00 2001
From: John Hendricks <jwh8zc@virginia.edu>
Date: Fri, 14 Mar 2025 18:16:09 -0400
Subject: [PATCH 2/2] Converted new Timedelta attributes to private
---
pandas/_libs/tslibs/timedeltas.pyx | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/pandas/_libs/tslibs/timedeltas.pyx b/pandas/_libs/tslibs/timedeltas.pyx
index 9505ceacba5ee..222a6070016e0 100644
--- a/pandas/_libs/tslibs/timedeltas.pyx
+++ b/pandas/_libs/tslibs/timedeltas.pyx
@@ -1039,7 +1039,7 @@ cdef class _Timedelta(timedelta):
# higher than np.ndarray and np.matrix
__array_priority__ = 100
- docstring_min = """
+ _docstring_min = """
Returns the minimum bound possible for Timedelta.
This property provides access to the smallest possible value that
@@ -1061,7 +1061,7 @@ cdef class _Timedelta(timedelta):
-106752 days +00:12:43.145224193
"""
- docstring_max = """
+ _docstring_max = """
Returns the maximum bound possible for Timedelta.
This property provides access to the largest possible value that
@@ -1083,7 +1083,7 @@ cdef class _Timedelta(timedelta):
106751 days 23:47:16.854775807
"""
- docstring_reso = """
+ _docstring_reso = """
Returns the smallest possible difference between non-equal Timedelta objects.
The resolution value is determined by the underlying representation of time
@@ -1104,9 +1104,9 @@ cdef class _Timedelta(timedelta):
0 days 00:00:00.000000001
"""
- min = MinMaxReso("min", docstring_min)
- max = MinMaxReso("max", docstring_max)
- resolution = MinMaxReso("resolution", docstring_reso)
+ min = MinMaxReso("min", _docstring_min)
+ max = MinMaxReso("max", _docstring_max)
+ resolution = MinMaxReso("resolution", _docstring_reso)
@property
def value(self):