From 3cfe276d6a7dab669b6e1565501c8528b8039e6f Mon Sep 17 00:00:00 2001 From: abonte <6319051+abonte@users.noreply.github.com> Date: Thu, 12 Jan 2023 23:59:12 +0100 Subject: [PATCH 1/4] DOC: improve Index docstrings --- pandas/core/indexes/base.py | 52 +++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 19b6c9db20f11..5333a4b47bc3f 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2073,6 +2073,14 @@ def is_monotonic_increasing(self) -> bool: """ Return a boolean if the values are equal or increasing. + Returns + ------- + bool + + See Also + -------- + Index.is_monotonic_decreasing : Check if the values are equal or decreasing. + Examples -------- >>> Index([1, 2, 3]).is_monotonic_increasing @@ -2089,6 +2097,14 @@ def is_monotonic_decreasing(self) -> bool: """ Return a boolean if the values are equal or decreasing. + Returns + ------- + bool + + See Also + -------- + Index.is_monotonic_increasing : Check if the values are equal or increasing. + Examples -------- >>> Index([3, 2, 1]).is_monotonic_decreasing @@ -2140,6 +2156,34 @@ def _is_strictly_monotonic_decreasing(self) -> bool: def is_unique(self) -> bool: """ Return if the index has unique values. + + Returns + ------- + bool + + See Also + -------- + Index.has_duplicates : Inverse method that checks if it has duplicate values. + + Examples + -------- + >>> idx = pd.Index([1, 5, 7, 7]) + >>> idx.is_unique + False + + >>> idx = pd.Index([1, 5, 7]) + >>> idx.is_unique + True + + >>> idx = pd.Index(["Watermelon", "Orange", "Apple", + ... "Watermelon"]).astype("category") + >>> idx.is_unique + False + + >>> idx = pd.Index(["Orange", "Apple", + ... "Watermelon"]).astype("category") + >>> idx.is_unique + True """ return self._engine.is_unique @@ -2154,6 +2198,10 @@ def has_duplicates(self) -> bool: bool Whether or not the Index has duplicate values. + See Also + -------- + Index.is_unique : Inverse method that checks if it has unique values. + Examples -------- >>> idx = pd.Index([1, 5, 7, 7]) @@ -2535,6 +2583,10 @@ def hasnans(self) -> bool: Return True if there are any NaNs. Enables various performance speedups. + + Returns + ------- + bool """ if self._can_hold_na: return bool(self._isnan.any()) From f3a7e190346121ca4ea9feeda46766b1dd606d70 Mon Sep 17 00:00:00 2001 From: abonte <6319051+abonte@users.noreply.github.com> Date: Fri, 13 Jan 2023 00:51:35 +0100 Subject: [PATCH 2/4] fix example --- pandas/core/indexes/base.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 5333a4b47bc3f..31d09d7e1d729 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2083,11 +2083,11 @@ def is_monotonic_increasing(self) -> bool: Examples -------- - >>> Index([1, 2, 3]).is_monotonic_increasing + >>> pd.Index([1, 2, 3]).is_monotonic_increasing True - >>> Index([1, 2, 2]).is_monotonic_increasing + >>> pd.Index([1, 2, 2]).is_monotonic_increasing True - >>> Index([1, 3, 2]).is_monotonic_increasing + >>> pd.Index([1, 3, 2]).is_monotonic_increasing False """ return self._engine.is_monotonic_increasing @@ -2107,11 +2107,11 @@ def is_monotonic_decreasing(self) -> bool: Examples -------- - >>> Index([3, 2, 1]).is_monotonic_decreasing + >>> pd.Index([3, 2, 1]).is_monotonic_decreasing True - >>> Index([3, 2, 2]).is_monotonic_decreasing + >>> pd.Index([3, 2, 2]).is_monotonic_decreasing True - >>> Index([3, 1, 2]).is_monotonic_decreasing + >>> pd.Index([3, 1, 2]).is_monotonic_decreasing False """ return self._engine.is_monotonic_decreasing From 7d95259e9bae91609ec86a6dc268ba27c772d895 Mon Sep 17 00:00:00 2001 From: abonte <6319051+abonte@users.noreply.github.com> Date: Fri, 13 Jan 2023 21:13:28 +0100 Subject: [PATCH 3/4] update Series.hanans docstring --- pandas/core/base.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pandas/core/base.py b/pandas/core/base.py index 826583fd26f5d..3f32f3cff8607 100644 --- a/pandas/core/base.py +++ b/pandas/core/base.py @@ -784,6 +784,10 @@ def hasnans(self) -> bool: Return True if there are any NaNs. Enables various performance speedups. + + Returns + ------- + bool """ # error: Item "bool" of "Union[bool, ndarray[Any, dtype[bool_]], NDFrame]" # has no attribute "any" From 79753527d287df3cd5badda75e55de07cc7a6121 Mon Sep 17 00:00:00 2001 From: abonte <6319051+abonte@users.noreply.github.com> Date: Thu, 19 Jan 2023 18:17:16 +0100 Subject: [PATCH 4/4] DOC: improve docstrings --- pandas/_libs/tslibs/timestamps.pyx | 40 ++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 0da8a9e73d963..b1b699f3ba9db 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -687,6 +687,14 @@ cdef class _Timestamp(ABCTimestamp): """ Return True if date is first day of the year. + Returns + ------- + bool + + See Also + -------- + Timestamp.is_year_end : Similar property indicating the end of the year. + Examples -------- >>> ts = pd.Timestamp(2020, 3, 14) @@ -704,6 +712,14 @@ cdef class _Timestamp(ABCTimestamp): """ Return True if date is last day of the year. + Returns + ------- + bool + + See Also + -------- + Timestamp.is_year_start : Similar property indicating the start of the year. + Examples -------- >>> ts = pd.Timestamp(2020, 3, 14) @@ -785,6 +801,10 @@ cdef class _Timestamp(ABCTimestamp): """ Return True if year is a leap year. + Returns + ------- + bool + Examples -------- >>> ts = pd.Timestamp(2020, 3, 14) @@ -798,6 +818,10 @@ cdef class _Timestamp(ABCTimestamp): """ Return day of the week. + Returns + ------- + int + Examples -------- >>> ts = pd.Timestamp(2020, 3, 14) @@ -811,6 +835,10 @@ cdef class _Timestamp(ABCTimestamp): """ Return the day of the year. + Returns + ------- + int + Examples -------- >>> ts = pd.Timestamp(2020, 3, 14) @@ -824,6 +852,10 @@ cdef class _Timestamp(ABCTimestamp): """ Return the quarter of the year. + Returns + ------- + int + Examples -------- >>> ts = pd.Timestamp(2020, 3, 14) @@ -837,6 +869,10 @@ cdef class _Timestamp(ABCTimestamp): """ Return the week number of the year. + Returns + ------- + int + Examples -------- >>> ts = pd.Timestamp(2020, 3, 14) @@ -850,6 +886,10 @@ cdef class _Timestamp(ABCTimestamp): """ Return the number of days in the month. + Returns + ------- + int + Examples -------- >>> ts = pd.Timestamp(2020, 3, 14)