pandas-dev / pandas

Flexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more
https://pandas.pydata.org
BSD 3-Clause "New" or "Revised" License
43.82k stars 17.99k forks source link

QST: How to add docstring to min, max, and resolution defined by MinMaxReso() #59761

Closed ammar-qazi closed 2 months ago

ammar-qazi commented 2 months ago

Research

Link to question on StackOverflow

None

Question about pandas

I've been trying to resolve the doc issues mentioned in #59698, but I couldn't find a way to add docstring for the following three attributes, present in timedeltas.pyx:

    i "pandas.Timedelta.resolution PR02" \
    i "pandas.Timedelta.min PR02" \
    i "pandas.Timedelta.resolution PR02" \

Unlike other python functions, these three attributes don't have their own def func area. Instead, they're being defined as:

cdef class _Timedelta(timedelta):
    # cdef readonly:
    #    int64_t value      # nanoseconds
    #    bint _is_populated  # are my components populated
    #    int64_t _d, _h, _m, _s, _ms, _us, _ns
    #    NPY_DATETIMEUNIT _reso

    # higher than np.ndarray and np.matrix
    __array_priority__ = 100
    min = MinMaxReso("min")
    max = MinMaxReso("max")
    resolution = MinMaxReso("resolution")

Here's the MinMaxReso function (placed a few lines above this cdef class):

class MinMaxReso:
    """
    We need to define min/max/resolution on both the Timedelta _instance_
    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):
        self._name = name

    def __get__(self, obj, type=None):
        if self._name == "min":
            val = np.iinfo(np.int64).min + 1
        elif self._name == "max":
            val = np.iinfo(np.int64).max
        else:
            assert self._name == "resolution"
            val = 1

        if obj is None:
            # i.e. this is on the class, default to nanos
            return Timedelta(val)
        else:
            return Timedelta._from_value_and_reso(val, obj._creso)

    def __set__(self, obj, value):
        raise AttributeError(f"{self._name} is not settable.")

I found these same attributes in a couple other files as well, and none of those had documentation, either. So, I would to know how to document what they offer to a pandas user.

rhshadrach commented 2 months ago

@ammar-qazi - I see you have discussion on this in the linked issue. I believe that issue was accidentally closed, so I've reopened it. To keep the discussion consolidated, I'm closing this issue. Let me know if you'd prefer to keep it open.