From 9f1faf6121333de5e4788c827f16d16705eace45 Mon Sep 17 00:00:00 2001 From: Tuhin Sharma Date: Sun, 4 Aug 2024 10:02:59 +0530 Subject: [PATCH 1/2] DOC: fix GL08 for pandas.tseries.offsets.YearEnd.rule_code --- ci/code_checks.sh | 1 - pandas/_libs/tslibs/offsets.pyx | 62 +++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index ebcc99100be70..ab562caf28b70 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -726,7 +726,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.tseries.offsets.YearEnd.n GL08" \ -i "pandas.tseries.offsets.YearEnd.nanos GL08" \ -i "pandas.tseries.offsets.YearEnd.normalize GL08" \ - -i "pandas.tseries.offsets.YearEnd.rule_code GL08" \ -i "pandas.util.hash_pandas_object PR07,SA01" # There should be no backslash in the final line, please keep this comment in the last ignored function RET=$(($RET + $?)) ; echo $MSG "DONE" diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index fd1bb3fe3e173..389d5c6d0a303 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -2466,6 +2466,68 @@ cdef class YearOffset(SingleConstructorOffset): @property def rule_code(self) -> str: + """ + Return the rule code for the YearEnd offset. + + The `rule_code` is a shorthand identifier used within pandas to denote + the end-of-year frequency. This code is useful when working with time + series data, particularly when you need to perform operations that require + a specific frequency. For example, it can be used in functions like + `pd.date_range`, `resample`, or `asfreq` to indicate that operations + should be aligned to the end of the year. The YearEnd offset represents the + end of a year, typically on December 31st. The `rule_code` for this offset + helps to abstract away the complexity of manually calculating end-of-year + dates, especially when handling irregular date ranges or resampling data. + + Returns + ------- + str + The rule code associated with the YearEnd offset. + + See Also + -------- + date_range : Generate a range of dates with a specific frequency. + Series.resample : Resample time-series data. + tseries.offsets.Week : Represents a weekly offset. + DateOffset : Base class for all other offset classes. + tseries.offsets.Day : Represents a single day offset. + tseries.offsets.MonthEnd : Represents a monthly offset that + snaps to the end of the month. + + Examples + -------- + Create a date range with random dates + >>> date_range = pd.to_datetime([ + ... '2020-01-01', '2020-07-15', '2021-02-28', '2021-08-20', '2022-03-10' + ... ]) + Create a DataFrame with the date_range as index and some random data + >>> data = np.random.rand(len(date_range)) + >>> df = pd.DataFrame(data, index=date_range, columns=['Value']) + Print the original DataFrame + >>> df + Value + 2020-01-01 0.460402 + 2020-07-15 0.339131 + 2021-02-28 0.697027 + 2021-08-20 0.839201 + 2022-03-10 0.079523 + + Use the YearEnd.offsets with its rule_code + >>> year_end = pd.tseries.offsets.YearEnd() + >>> rule_code = year_end.rule_code + >>> rule_code + YE-DEC + + Resample the data using the YearEnd rule code + >>> df_resampled = df.resample(rule_code).sum() + + Print the resampled DataFrame + >>df_resampled + Value + 2020-12-31 0.799533 + 2021-12-31 1.536228 + 2022-12-31 0.079523 + """ month = MONTH_ALIASES[self.month] return f"{self._prefix}-{month}" From 1a2d74849d557815d37cab8d2d80d451d3d085cc Mon Sep 17 00:00:00 2001 From: Tuhin Sharma Date: Sun, 4 Aug 2024 10:45:03 +0530 Subject: [PATCH 2/2] DOC: remove rule_code for Year objects --- ci/code_checks.sh | 3 --- 1 file changed, 3 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index ab562caf28b70..c5c564aa5b364 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -458,7 +458,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.tseries.offsets.BYearBegin.n GL08" \ -i "pandas.tseries.offsets.BYearBegin.nanos GL08" \ -i "pandas.tseries.offsets.BYearBegin.normalize GL08" \ - -i "pandas.tseries.offsets.BYearBegin.rule_code GL08" \ -i "pandas.tseries.offsets.BYearEnd PR02" \ -i "pandas.tseries.offsets.BYearEnd.freqstr SA01" \ -i "pandas.tseries.offsets.BYearEnd.is_on_offset GL08" \ @@ -466,7 +465,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.tseries.offsets.BYearEnd.n GL08" \ -i "pandas.tseries.offsets.BYearEnd.nanos GL08" \ -i "pandas.tseries.offsets.BYearEnd.normalize GL08" \ - -i "pandas.tseries.offsets.BYearEnd.rule_code GL08" \ -i "pandas.tseries.offsets.BusinessDay PR02,SA01" \ -i "pandas.tseries.offsets.BusinessDay.calendar GL08" \ -i "pandas.tseries.offsets.BusinessDay.freqstr SA01" \ @@ -719,7 +717,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.tseries.offsets.YearBegin.n GL08" \ -i "pandas.tseries.offsets.YearBegin.nanos GL08" \ -i "pandas.tseries.offsets.YearBegin.normalize GL08" \ - -i "pandas.tseries.offsets.YearBegin.rule_code GL08" \ -i "pandas.tseries.offsets.YearEnd.freqstr SA01" \ -i "pandas.tseries.offsets.YearEnd.is_on_offset GL08" \ -i "pandas.tseries.offsets.YearEnd.month GL08" \