From 6cb9f524ca0430c50089b449a0a0cbba9d257e33 Mon Sep 17 00:00:00 2001 From: UDIT Date: Wed, 14 Aug 2024 23:01:51 +0530 Subject: [PATCH 1/9] Fix docstrings for pandas.Period.month --- ci/code_checks.sh | 1 - pandas/_libs/tslibs/period.pyx | 62 +++++++++++++++++++++++++++++----- 2 files changed, 54 insertions(+), 9 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index eb4f03cdf4083..d79b3c96769b7 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -79,7 +79,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Period.asfreq SA01" \ -i "pandas.Period.freq GL08" \ -i "pandas.Period.freqstr SA01" \ - -i "pandas.Period.month SA01" \ -i "pandas.Period.ordinal GL08" \ -i "pandas.Period.strftime PR01,SA01" \ -i "pandas.Period.to_timestamp SA01" \ diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index c6ba97fe9f1a2..ef0b0a31e441c 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2011,15 +2011,61 @@ cdef class _Period(PeriodMixin): @property def month(self) -> int: - """ - Return the month this Period falls on. + """ + Return the month this Period falls on. + + Parameters + ---------- + None + + Returns + ------- + int : The month number of the Period. + + See Also + -------- + period.week : Get the week of the year on the given Period. + Period.year : Return the year this Period falls on. + Period.day : Return the day of the month this Period falls on. + + + Examples + -------- + Create a Period object for January 2022 and get the month: + + >>> period = pd.Period('2022-01', 'M') + >>> period.month + 1 + + Create a Period object with no specified frequency, resulting in a default frequency: + + >>> period = pd.Period('2022', 'Y') + >>> period.month + 12 + + Create a Period object with a specified frequency but an incomplete date string: + + >>> period = pd.Period('2022', 'M') + >>> period.month + 1 + + Handle a case where the Period object is invalid or empty, which results in `NaN`: + + >>> period = pd.Period('nan', 'M') + >>> period.month + nan + + Handle a case where the Period object is invalid or empty, which results in `NaN`: + + >>> period = pd.Period('nan', 'M') + >>> period.month + nan + + Notes + ----- + The month is determined based on the `ordinal` and `base` attributes of the Period. + """ - Examples - -------- - >>> period = pd.Period('2022-01', 'M') - >>> period.month - 1 - """ base = self._dtype._dtype_code return pmonth(self.ordinal, base) From 392f78ac006c8558065875a78f250d9a8af13655 Mon Sep 17 00:00:00 2001 From: UDIT Date: Wed, 14 Aug 2024 23:12:44 +0530 Subject: [PATCH 2/9] Fix docstrings for pandas.Period.month indentation --- pandas/_libs/tslibs/period.pyx | 78 +++++++++++++++++----------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index ef0b0a31e441c..52a0cc5828637 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2011,60 +2011,60 @@ cdef class _Period(PeriodMixin): @property def month(self) -> int: - """ - Return the month this Period falls on. + """ + Return the month this Period falls on. - Parameters - ---------- - None + Parameters + ---------- + None - Returns - ------- - int : The month number of the Period. + Returns + ------- + int : The month number of the Period. - See Also - -------- - period.week : Get the week of the year on the given Period. - Period.year : Return the year this Period falls on. - Period.day : Return the day of the month this Period falls on. + See Also + -------- + period.week : Get the week of the year on the given Period. + Period.year : Return the year this Period falls on. + Period.day : Return the day of the month this Period falls on. - Examples - -------- - Create a Period object for January 2022 and get the month: + Examples + -------- + Create a Period object for January 2022 and get the month: - >>> period = pd.Period('2022-01', 'M') - >>> period.month - 1 + >>> period = pd.Period('2022-01', 'M') + >>> period.month + 1 - Create a Period object with no specified frequency, resulting in a default frequency: + Create a Period object with no specified frequency, resulting in a default frequency: - >>> period = pd.Period('2022', 'Y') - >>> period.month - 12 + >>> period = pd.Period('2022', 'Y') + >>> period.month + 12 - Create a Period object with a specified frequency but an incomplete date string: + Create a Period object with a specified frequency but an incomplete date string: - >>> period = pd.Period('2022', 'M') - >>> period.month - 1 + >>> period = pd.Period('2022', 'M') + >>> period.month + 1 - Handle a case where the Period object is invalid or empty, which results in `NaN`: + Handle a case where the Period object is invalid or empty, which results in `NaN`: - >>> period = pd.Period('nan', 'M') - >>> period.month - nan + >>> period = pd.Period('nan', 'M') + >>> period.month + nan - Handle a case where the Period object is invalid or empty, which results in `NaN`: + Handle a case where the Period object is invalid or empty, which results in `NaN`: - >>> period = pd.Period('nan', 'M') - >>> period.month - nan + >>> period = pd.Period('nan', 'M') + >>> period.month + nan - Notes - ----- - The month is determined based on the `ordinal` and `base` attributes of the Period. - """ + Notes + ----- + The month is determined based on the `ordinal` and `base` attributes of the Period. + """ base = self._dtype._dtype_code return pmonth(self.ordinal, base) From cd57fa5b91dfb6732b2c3f0e1d4f11f908943e57 Mon Sep 17 00:00:00 2001 From: UDIT Date: Wed, 14 Aug 2024 23:37:33 +0530 Subject: [PATCH 3/9] Fix docstrings for pandas.Period.month --- pandas/_libs/tslibs/period.pyx | 6 ------ 1 file changed, 6 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 52a0cc5828637..9e8723c0448c1 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2055,12 +2055,6 @@ cdef class _Period(PeriodMixin): >>> period.month nan - Handle a case where the Period object is invalid or empty, which results in `NaN`: - - >>> period = pd.Period('nan', 'M') - >>> period.month - nan - Notes ----- The month is determined based on the `ordinal` and `base` attributes of the Period. From 591872297ed52ea96a83e79383b473927ebe2a4d Mon Sep 17 00:00:00 2001 From: UDIT Date: Thu, 15 Aug 2024 01:32:09 +0530 Subject: [PATCH 4/9] Fix docstrings for pandas.Period.asfreq SA01 --- ci/code_checks.sh | 1 - pandas/_libs/tslibs/period.pyx | 47 ++++++++++++++++++++++++++++++---- 2 files changed, 42 insertions(+), 6 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index d79b3c96769b7..5f9458000fd29 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -76,7 +76,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.MultiIndex.to_frame RT03" \ -i "pandas.NA SA01" \ -i "pandas.NaT SA01" \ - -i "pandas.Period.asfreq SA01" \ -i "pandas.Period.freq GL08" \ -i "pandas.Period.freqstr SA01" \ -i "pandas.Period.ordinal GL08" \ diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 9e8723c0448c1..3ed6167059912 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1913,20 +1913,57 @@ cdef class _Period(PeriodMixin): Parameters ---------- freq : str, BaseOffset - The desired frequency. If passing a `str`, it needs to be a - valid :ref:`period alias `. + The target frequency to convert the Period object to. If a string is provided, + it must be a valid :ref:`period alias `. + how : {'E', 'S', 'end', 'start'}, default 'end' - Start or end of the timespan. + Specifies whether to align the converted period to the start or end of the interval: + - 'E' or 'end': Align to the end of the interval. + - 'S' or 'start': Align to the start of the interval. Returns ------- - resampled : Period + Resampled Period : A new Period object with the specified frequency, aligned according to the `how` parameter. + + See Also + -------- + Period.end_time : Return the end Timestamp. + Period.start_time : Return the start Timestamp. + Period.dayofyear : Return the day of the year. + Period.dayofweek : Return the day of the week. Examples -------- - >>> period = pd.Period('2023-1-1', freq='D') + Convert a daily period to an hourly period, aligning to the end of the day: + + >>> period = pd.Period('2023-01-01', freq='D') >>> period.asfreq('h') Period('2023-01-01 23:00', 'h') + + Convert a monthly period to a daily period, aligning to the start of the month: + + >>> period = pd.Period('2023-01', freq='M') + >>> period.asfreq('D', how='start') + Period('2023-01-01', 'D') + + Convert a yearly period to a monthly period, aligning to the last month of the year: + + >>> period = pd.Period('2023', freq='Y') + >>> period.asfreq('M', how='end') + Period('2023-12', 'M') + + Convert a monthly period to an hourly period, aligning to the start of the first day of the month: + + >>> period = pd.Period('2023-01', freq='M') + >>> period.asfreq('h', how='start') + Period('2023-01-01 00:00', 'H') + + Convert a weekly period to a daily period, aligning to the last day of the week: + + >>> period = pd.Period('2023-08-01', freq='W') + >>> period.asfreq('D', how='end') + Period('2023-08-04', 'D') + """ freq = self._maybe_convert_freq(freq) how = validate_end_alias(how) From 02e911b827fde00091f89806ed7ecf21f9690a2f Mon Sep 17 00:00:00 2001 From: UDIT Date: Thu, 15 Aug 2024 07:38:04 +0530 Subject: [PATCH 5/9] Fix docstrings for pandas.Period.asfreq --- pandas/_libs/tslibs/period.pyx | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 3ed6167059912..c67b758a3b31b 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1963,7 +1963,6 @@ cdef class _Period(PeriodMixin): >>> period = pd.Period('2023-08-01', freq='W') >>> period.asfreq('D', how='end') Period('2023-08-04', 'D') - """ freq = self._maybe_convert_freq(freq) how = validate_end_alias(how) @@ -2065,7 +2064,10 @@ cdef class _Period(PeriodMixin): Period.year : Return the year this Period falls on. Period.day : Return the day of the month this Period falls on. - + Notes + ----- + The month is determined based on the `ordinal` and `base` attributes of the Period. + Examples -------- Create a Period object for January 2022 and get the month: @@ -2091,12 +2093,7 @@ cdef class _Period(PeriodMixin): >>> period = pd.Period('nan', 'M') >>> period.month nan - - Notes - ----- - The month is determined based on the `ordinal` and `base` attributes of the Period. """ - base = self._dtype._dtype_code return pmonth(self.ordinal, base) From 9929ec6ec7e20f67906afab83fb3468a708cdf33 Mon Sep 17 00:00:00 2001 From: UDIT Date: Thu, 15 Aug 2024 08:06:25 +0530 Subject: [PATCH 6/9] Fix docstrings ci error cython-lint --- pandas/_libs/tslibs/period.pyx | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index c67b758a3b31b..3f271e08abd99 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1913,17 +1913,18 @@ cdef class _Period(PeriodMixin): Parameters ---------- freq : str, BaseOffset - The target frequency to convert the Period object to. If a string is provided, + The target frequency to convert the Period object to. + If a string is provided, it must be a valid :ref:`period alias `. how : {'E', 'S', 'end', 'start'}, default 'end' - Specifies whether to align the converted period to the start or end of the interval: + Specifies whether to align the period to the start or end of the interval: - 'E' or 'end': Align to the end of the interval. - 'S' or 'start': Align to the start of the interval. Returns ------- - Resampled Period : A new Period object with the specified frequency, aligned according to the `how` parameter. + Period : A new Period object with the specified frequency, aligned to the `how` parameter. See Also -------- @@ -1946,13 +1947,13 @@ cdef class _Period(PeriodMixin): >>> period.asfreq('D', how='start') Period('2023-01-01', 'D') - Convert a yearly period to a monthly period, aligning to the last month of the year: + Convert a yearly period to a monthly period, aligning to the last month: >>> period = pd.Period('2023', freq='Y') >>> period.asfreq('M', how='end') Period('2023-12', 'M') - Convert a monthly period to an hourly period, aligning to the start of the first day of the month: + Convert a monthly period to an hourly period, aligning to the first day of the month: >>> period = pd.Period('2023-01', freq='M') >>> period.asfreq('h', how='start') @@ -2067,7 +2068,7 @@ cdef class _Period(PeriodMixin): Notes ----- The month is determined based on the `ordinal` and `base` attributes of the Period. - + Examples -------- Create a Period object for January 2022 and get the month: @@ -2076,7 +2077,7 @@ cdef class _Period(PeriodMixin): >>> period.month 1 - Create a Period object with no specified frequency, resulting in a default frequency: + Period object with no specified frequency, resulting in a default frequency: >>> period = pd.Period('2022', 'Y') >>> period.month @@ -2088,7 +2089,7 @@ cdef class _Period(PeriodMixin): >>> period.month 1 - Handle a case where the Period object is invalid or empty, which results in `NaN`: + Handle a case where the Period object is empty, which results in `NaN`: >>> period = pd.Period('nan', 'M') >>> period.month From 73f8b97bd67bd342f64d01bf23ae029be9cff008 Mon Sep 17 00:00:00 2001 From: UDIT Date: Thu, 15 Aug 2024 08:18:07 +0530 Subject: [PATCH 7/9] Fix docstrings pre-commit.cierror --- pandas/_libs/tslibs/period.pyx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 3f271e08abd99..df86cce955934 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1913,7 +1913,7 @@ cdef class _Period(PeriodMixin): Parameters ---------- freq : str, BaseOffset - The target frequency to convert the Period object to. + The target frequency to convert the Period object to. If a string is provided, it must be a valid :ref:`period alias `. @@ -1924,7 +1924,7 @@ cdef class _Period(PeriodMixin): Returns ------- - Period : A new Period object with the specified frequency, aligned to the `how` parameter. + Period : Period object with the specified frequency, aligned to the parameter. See Also -------- @@ -1953,7 +1953,8 @@ cdef class _Period(PeriodMixin): >>> period.asfreq('M', how='end') Period('2023-12', 'M') - Convert a monthly period to an hourly period, aligning to the first day of the month: + Convert a monthly period to an hourly period, + aligning to the first day of the month: >>> period = pd.Period('2023-01', freq='M') >>> period.asfreq('h', how='start') @@ -2067,7 +2068,7 @@ cdef class _Period(PeriodMixin): Notes ----- - The month is determined based on the `ordinal` and `base` attributes of the Period. + The month is based on the `ordinal` and `base` attributes of the Period. Examples -------- From 3991a94f2f8f308869379b44278bc600d3dbc872 Mon Sep 17 00:00:00 2001 From: UDIT Date: Thu, 15 Aug 2024 09:20:59 +0530 Subject: [PATCH 8/9] Fix docstring validation error --- pandas/_libs/tslibs/period.pyx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index df86cce955934..ee5b61e2a034e 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2054,11 +2054,12 @@ cdef class _Period(PeriodMixin): Parameters ---------- - None + does not take any parameters Returns ------- - int : The month number of the Period. + int + The month number of the Period. See Also -------- From 894a373123cf1184d50ce156a2f397dcc801944b Mon Sep 17 00:00:00 2001 From: UDIT Date: Thu, 15 Aug 2024 09:46:19 +0530 Subject: [PATCH 9/9] Fix docstring validation errors --- pandas/_libs/tslibs/period.pyx | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index ee5b61e2a034e..84d9b57340ed4 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2052,14 +2052,9 @@ cdef class _Period(PeriodMixin): """ Return the month this Period falls on. - Parameters - ---------- - does not take any parameters - Returns ------- - int - The month number of the Period. + int See Also --------