From a13886673817218b7d45a7e2e3b2977e2aa81556 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Tue, 2 Aug 2022 13:06:58 -0700 Subject: [PATCH 1/5] Add examples to offsets --- ci/code_checks.sh | 4 +- doc/source/reference/offset_frequency.rst | 177 ---------------------- pandas/_libs/tslibs/offsets.pyx | 160 +++++++++++++++++++ 3 files changed, 162 insertions(+), 179 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 113186c746157..733202165b33a 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -78,8 +78,8 @@ fi ### DOCSTRINGS ### if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then - MSG='Validate docstrings (EX04, GL01, GL02, GL03, GL04, GL05, GL06, GL07, GL09, GL10, PR03, PR04, PR05, PR06, PR08, PR09, PR10, RT01, RT04, RT05, SA02, SA03, SA04, SS01, SS02, SS03, SS04, SS05, SS06)' ; echo $MSG - $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX04,GL01,GL02,GL03,GL04,GL05,GL06,GL07,GL09,GL10,PR03,PR04,PR05,PR06,PR08,PR09,PR10,RT01,RT04,RT05,SA02,SA03,SA04,SS01,SS02,SS03,SS04,SS05,SS06 + MSG='Validate docstrings (EX01, EX04, GL01, GL02, GL03, GL04, GL05, GL06, GL07, GL09, GL10, PR03, PR04, PR05, PR06, PR08, PR09, PR10, RT01, RT04, RT05, SA02, SA03, SA04, SS01, SS02, SS03, SS04, SS05, SS06)' ; echo $MSG + $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX01,EX04,GL01,GL02,GL03,GL04,GL05,GL06,GL07,GL09,GL10,PR03,PR04,PR05,PR06,PR08,PR09,PR10,RT01,RT04,RT05,SA02,SA03,SA04,SS01,SS02,SS03,SS04,SS05,SS06 RET=$(($RET + $?)) ; echo $MSG "DONE" fi diff --git a/doc/source/reference/offset_frequency.rst b/doc/source/reference/offset_frequency.rst index f0e531cd81f84..4391eda62ac1d 100644 --- a/doc/source/reference/offset_frequency.rst +++ b/doc/source/reference/offset_frequency.rst @@ -26,22 +26,15 @@ Properties DateOffset.normalize DateOffset.rule_code DateOffset.n - DateOffset.is_month_start - DateOffset.is_month_end Methods ~~~~~~~ .. autosummary:: :toctree: api/ - DateOffset.apply - DateOffset.apply_index DateOffset.copy - DateOffset.isAnchored - DateOffset.onOffset DateOffset.is_anchored DateOffset.is_on_offset - DateOffset.__call__ DateOffset.is_month_start DateOffset.is_month_end DateOffset.is_quarter_start @@ -86,14 +79,9 @@ Methods .. autosummary:: :toctree: api/ - BusinessDay.apply - BusinessDay.apply_index BusinessDay.copy - BusinessDay.isAnchored - BusinessDay.onOffset BusinessDay.is_anchored BusinessDay.is_on_offset - BusinessDay.__call__ BusinessDay.is_month_start BusinessDay.is_month_end BusinessDay.is_quarter_start @@ -131,14 +119,9 @@ Methods .. autosummary:: :toctree: api/ - BusinessHour.apply - BusinessHour.apply_index BusinessHour.copy - BusinessHour.isAnchored - BusinessHour.onOffset BusinessHour.is_anchored BusinessHour.is_on_offset - BusinessHour.__call__ BusinessHour.is_month_start BusinessHour.is_month_end BusinessHour.is_quarter_start @@ -183,14 +166,9 @@ Methods .. autosummary:: :toctree: api/ - CustomBusinessDay.apply_index - CustomBusinessDay.apply CustomBusinessDay.copy - CustomBusinessDay.isAnchored - CustomBusinessDay.onOffset CustomBusinessDay.is_anchored CustomBusinessDay.is_on_offset - CustomBusinessDay.__call__ CustomBusinessDay.is_month_start CustomBusinessDay.is_month_end CustomBusinessDay.is_quarter_start @@ -228,14 +206,9 @@ Methods .. autosummary:: :toctree: api/ - CustomBusinessHour.apply - CustomBusinessHour.apply_index CustomBusinessHour.copy - CustomBusinessHour.isAnchored - CustomBusinessHour.onOffset CustomBusinessHour.is_anchored CustomBusinessHour.is_on_offset - CustomBusinessHour.__call__ CustomBusinessHour.is_month_start CustomBusinessHour.is_month_end CustomBusinessHour.is_quarter_start @@ -268,14 +241,9 @@ Methods .. autosummary:: :toctree: api/ - MonthEnd.apply - MonthEnd.apply_index MonthEnd.copy - MonthEnd.isAnchored - MonthEnd.onOffset MonthEnd.is_anchored MonthEnd.is_on_offset - MonthEnd.__call__ MonthEnd.is_month_start MonthEnd.is_month_end MonthEnd.is_quarter_start @@ -308,14 +276,9 @@ Methods .. autosummary:: :toctree: api/ - MonthBegin.apply - MonthBegin.apply_index MonthBegin.copy - MonthBegin.isAnchored - MonthBegin.onOffset MonthBegin.is_anchored MonthBegin.is_on_offset - MonthBegin.__call__ MonthBegin.is_month_start MonthBegin.is_month_end MonthBegin.is_quarter_start @@ -357,14 +320,9 @@ Methods .. autosummary:: :toctree: api/ - BusinessMonthEnd.apply - BusinessMonthEnd.apply_index BusinessMonthEnd.copy - BusinessMonthEnd.isAnchored - BusinessMonthEnd.onOffset BusinessMonthEnd.is_anchored BusinessMonthEnd.is_on_offset - BusinessMonthEnd.__call__ BusinessMonthEnd.is_month_start BusinessMonthEnd.is_month_end BusinessMonthEnd.is_quarter_start @@ -406,14 +364,9 @@ Methods .. autosummary:: :toctree: api/ - BusinessMonthBegin.apply - BusinessMonthBegin.apply_index BusinessMonthBegin.copy - BusinessMonthBegin.isAnchored - BusinessMonthBegin.onOffset BusinessMonthBegin.is_anchored BusinessMonthBegin.is_on_offset - BusinessMonthBegin.__call__ BusinessMonthBegin.is_month_start BusinessMonthBegin.is_month_end BusinessMonthBegin.is_quarter_start @@ -459,14 +412,9 @@ Methods .. autosummary:: :toctree: api/ - CustomBusinessMonthEnd.apply - CustomBusinessMonthEnd.apply_index CustomBusinessMonthEnd.copy - CustomBusinessMonthEnd.isAnchored - CustomBusinessMonthEnd.onOffset CustomBusinessMonthEnd.is_anchored CustomBusinessMonthEnd.is_on_offset - CustomBusinessMonthEnd.__call__ CustomBusinessMonthEnd.is_month_start CustomBusinessMonthEnd.is_month_end CustomBusinessMonthEnd.is_quarter_start @@ -512,14 +460,9 @@ Methods .. autosummary:: :toctree: api/ - CustomBusinessMonthBegin.apply - CustomBusinessMonthBegin.apply_index CustomBusinessMonthBegin.copy - CustomBusinessMonthBegin.isAnchored - CustomBusinessMonthBegin.onOffset CustomBusinessMonthBegin.is_anchored CustomBusinessMonthBegin.is_on_offset - CustomBusinessMonthBegin.__call__ CustomBusinessMonthBegin.is_month_start CustomBusinessMonthBegin.is_month_end CustomBusinessMonthBegin.is_quarter_start @@ -553,14 +496,9 @@ Methods .. autosummary:: :toctree: api/ - SemiMonthEnd.apply - SemiMonthEnd.apply_index SemiMonthEnd.copy - SemiMonthEnd.isAnchored - SemiMonthEnd.onOffset SemiMonthEnd.is_anchored SemiMonthEnd.is_on_offset - SemiMonthEnd.__call__ SemiMonthEnd.is_month_start SemiMonthEnd.is_month_end SemiMonthEnd.is_quarter_start @@ -594,14 +532,9 @@ Methods .. autosummary:: :toctree: api/ - SemiMonthBegin.apply - SemiMonthBegin.apply_index SemiMonthBegin.copy - SemiMonthBegin.isAnchored - SemiMonthBegin.onOffset SemiMonthBegin.is_anchored SemiMonthBegin.is_on_offset - SemiMonthBegin.__call__ SemiMonthBegin.is_month_start SemiMonthBegin.is_month_end SemiMonthBegin.is_quarter_start @@ -635,14 +568,9 @@ Methods .. autosummary:: :toctree: api/ - Week.apply - Week.apply_index Week.copy - Week.isAnchored - Week.onOffset Week.is_anchored Week.is_on_offset - Week.__call__ Week.is_month_start Week.is_month_end Week.is_quarter_start @@ -676,14 +604,9 @@ Methods .. autosummary:: :toctree: api/ - WeekOfMonth.apply - WeekOfMonth.apply_index WeekOfMonth.copy - WeekOfMonth.isAnchored - WeekOfMonth.onOffset WeekOfMonth.is_anchored WeekOfMonth.is_on_offset - WeekOfMonth.__call__ WeekOfMonth.weekday WeekOfMonth.is_month_start WeekOfMonth.is_month_end @@ -719,14 +642,9 @@ Methods .. autosummary:: :toctree: api/ - LastWeekOfMonth.apply - LastWeekOfMonth.apply_index LastWeekOfMonth.copy - LastWeekOfMonth.isAnchored - LastWeekOfMonth.onOffset LastWeekOfMonth.is_anchored LastWeekOfMonth.is_on_offset - LastWeekOfMonth.__call__ LastWeekOfMonth.is_month_start LastWeekOfMonth.is_month_end LastWeekOfMonth.is_quarter_start @@ -760,14 +678,9 @@ Methods .. autosummary:: :toctree: api/ - BQuarterEnd.apply - BQuarterEnd.apply_index BQuarterEnd.copy - BQuarterEnd.isAnchored - BQuarterEnd.onOffset BQuarterEnd.is_anchored BQuarterEnd.is_on_offset - BQuarterEnd.__call__ BQuarterEnd.is_month_start BQuarterEnd.is_month_end BQuarterEnd.is_quarter_start @@ -801,14 +714,9 @@ Methods .. autosummary:: :toctree: api/ - BQuarterBegin.apply - BQuarterBegin.apply_index BQuarterBegin.copy - BQuarterBegin.isAnchored - BQuarterBegin.onOffset BQuarterBegin.is_anchored BQuarterBegin.is_on_offset - BQuarterBegin.__call__ BQuarterBegin.is_month_start BQuarterBegin.is_month_end BQuarterBegin.is_quarter_start @@ -842,14 +750,9 @@ Methods .. autosummary:: :toctree: api/ - QuarterEnd.apply - QuarterEnd.apply_index QuarterEnd.copy - QuarterEnd.isAnchored - QuarterEnd.onOffset QuarterEnd.is_anchored QuarterEnd.is_on_offset - QuarterEnd.__call__ QuarterEnd.is_month_start QuarterEnd.is_month_end QuarterEnd.is_quarter_start @@ -883,14 +786,9 @@ Methods .. autosummary:: :toctree: api/ - QuarterBegin.apply - QuarterBegin.apply_index QuarterBegin.copy - QuarterBegin.isAnchored - QuarterBegin.onOffset QuarterBegin.is_anchored QuarterBegin.is_on_offset - QuarterBegin.__call__ QuarterBegin.is_month_start QuarterBegin.is_month_end QuarterBegin.is_quarter_start @@ -924,14 +822,9 @@ Methods .. autosummary:: :toctree: api/ - BYearEnd.apply - BYearEnd.apply_index BYearEnd.copy - BYearEnd.isAnchored - BYearEnd.onOffset BYearEnd.is_anchored BYearEnd.is_on_offset - BYearEnd.__call__ BYearEnd.is_month_start BYearEnd.is_month_end BYearEnd.is_quarter_start @@ -965,14 +858,9 @@ Methods .. autosummary:: :toctree: api/ - BYearBegin.apply - BYearBegin.apply_index BYearBegin.copy - BYearBegin.isAnchored - BYearBegin.onOffset BYearBegin.is_anchored BYearBegin.is_on_offset - BYearBegin.__call__ BYearBegin.is_month_start BYearBegin.is_month_end BYearBegin.is_quarter_start @@ -1006,14 +894,9 @@ Methods .. autosummary:: :toctree: api/ - YearEnd.apply - YearEnd.apply_index YearEnd.copy - YearEnd.isAnchored - YearEnd.onOffset YearEnd.is_anchored YearEnd.is_on_offset - YearEnd.__call__ YearEnd.is_month_start YearEnd.is_month_end YearEnd.is_quarter_start @@ -1047,14 +930,9 @@ Methods .. autosummary:: :toctree: api/ - YearBegin.apply - YearBegin.apply_index YearBegin.copy - YearBegin.isAnchored - YearBegin.onOffset YearBegin.is_anchored YearBegin.is_on_offset - YearBegin.__call__ YearBegin.is_month_start YearBegin.is_month_end YearBegin.is_quarter_start @@ -1090,16 +968,11 @@ Methods .. autosummary:: :toctree: api/ - FY5253.apply - FY5253.apply_index FY5253.copy FY5253.get_rule_code_suffix FY5253.get_year_end - FY5253.isAnchored - FY5253.onOffset FY5253.is_anchored FY5253.is_on_offset - FY5253.__call__ FY5253.is_month_start FY5253.is_month_end FY5253.is_quarter_start @@ -1136,17 +1009,12 @@ Methods .. autosummary:: :toctree: api/ - FY5253Quarter.apply - FY5253Quarter.apply_index FY5253Quarter.copy FY5253Quarter.get_rule_code_suffix FY5253Quarter.get_weeks - FY5253Quarter.isAnchored - FY5253Quarter.onOffset FY5253Quarter.is_anchored FY5253Quarter.is_on_offset FY5253Quarter.year_has_extra_week - FY5253Quarter.__call__ FY5253Quarter.is_month_start FY5253Quarter.is_month_end FY5253Quarter.is_quarter_start @@ -1179,14 +1047,9 @@ Methods .. autosummary:: :toctree: api/ - Easter.apply - Easter.apply_index Easter.copy - Easter.isAnchored - Easter.onOffset Easter.is_anchored Easter.is_on_offset - Easter.__call__ Easter.is_month_start Easter.is_month_end Easter.is_quarter_start @@ -1221,13 +1084,8 @@ Methods :toctree: api/ Tick.copy - Tick.isAnchored - Tick.onOffset Tick.is_anchored Tick.is_on_offset - Tick.__call__ - Tick.apply - Tick.apply_index Tick.is_month_start Tick.is_month_end Tick.is_quarter_start @@ -1262,13 +1120,8 @@ Methods :toctree: api/ Day.copy - Day.isAnchored - Day.onOffset Day.is_anchored Day.is_on_offset - Day.__call__ - Day.apply - Day.apply_index Day.is_month_start Day.is_month_end Day.is_quarter_start @@ -1303,13 +1156,8 @@ Methods :toctree: api/ Hour.copy - Hour.isAnchored - Hour.onOffset Hour.is_anchored Hour.is_on_offset - Hour.__call__ - Hour.apply - Hour.apply_index Hour.is_month_start Hour.is_month_end Hour.is_quarter_start @@ -1344,13 +1192,8 @@ Methods :toctree: api/ Minute.copy - Minute.isAnchored - Minute.onOffset Minute.is_anchored Minute.is_on_offset - Minute.__call__ - Minute.apply - Minute.apply_index Minute.is_month_start Minute.is_month_end Minute.is_quarter_start @@ -1385,13 +1228,8 @@ Methods :toctree: api/ Second.copy - Second.isAnchored - Second.onOffset Second.is_anchored Second.is_on_offset - Second.__call__ - Second.apply - Second.apply_index Second.is_month_start Second.is_month_end Second.is_quarter_start @@ -1426,13 +1264,8 @@ Methods :toctree: api/ Milli.copy - Milli.isAnchored - Milli.onOffset Milli.is_anchored Milli.is_on_offset - Milli.__call__ - Milli.apply - Milli.apply_index Milli.is_month_start Milli.is_month_end Milli.is_quarter_start @@ -1467,13 +1300,8 @@ Methods :toctree: api/ Micro.copy - Micro.isAnchored - Micro.onOffset Micro.is_anchored Micro.is_on_offset - Micro.__call__ - Micro.apply - Micro.apply_index Micro.is_month_start Micro.is_month_end Micro.is_quarter_start @@ -1508,13 +1336,8 @@ Methods :toctree: api/ Nano.copy - Nano.isAnchored - Nano.onOffset Nano.is_anchored Nano.is_on_offset - Nano.__call__ - Nano.apply - Nano.apply_index Nano.is_month_start Nano.is_month_end Nano.is_quarter_start diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index 48104965ec42b..6952b1497e65f 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -367,7 +367,23 @@ cdef class BaseOffset: def __init__(self, n=1, normalize=False): n = self._validate_n(n) self.n = n + """ + Number of multiples of the frequency. + + Examples + -------- + >>> pd.offsets.Hour(5).n + 5 + """ self.normalize = normalize + """ + Return boolean whether the frequency can align with midnight. + + Examples + -------- + >>> pd.offsets.Hour(5).normalize + False + """ self._cache = {} def __eq__(self, other) -> bool: @@ -417,6 +433,20 @@ cdef class BaseOffset: @property def kwds(self) -> dict: + """ + Return a dict of extra parameters for the offset. + + Examples + -------- + >>> pd.DateOffset(5).kwds + {} + + >>> pd.offsets.FY5253Quarter().kwds + {'weekday': 0, + 'startingMonth': 1, + 'qtr_with_extra_week': 1, + 'variation': 'nearest'} + """ # for backwards-compatibility kwds = {name: getattr(self, name, None) for name in self._attributes if name not in ["n", "normalize"]} @@ -506,6 +536,16 @@ cdef class BaseOffset: def copy(self): # Note: we are deferring directly to __mul__ instead of __rmul__, as # that allows us to use methods that can go in a `cdef class` + """ + Return a copy of the frequency. + + Examples + -------- + >>> freq = pd.DateOffset(1) + >>> freq_copy = freq.copy() + >>> freq is freq_copy + False + """ return self * 1 # ------------------------------------------------------------------ @@ -547,6 +587,14 @@ cdef class BaseOffset: @property def name(self) -> str: + """ + Return a string representing the base frequency. + + Examples + -------- + >>> pd.offsets.Hour(5).name + 'H' + """ return self.rule_code @property @@ -559,6 +607,20 @@ cdef class BaseOffset: @cache_readonly def freqstr(self) -> str: + """ + Return a string representing the frequency. + + Examples + -------- + >>> pd.DateOffset(5).freqstr + '<5 * DateOffsets>' + + >>> pd.offsets.BusinessHour(2).freqstr + '2BH' + + >>> pd.offsets.Nano(-3).freqstr + '-3N' + """ try: code = self.rule_code except NotImplementedError: @@ -655,6 +717,21 @@ cdef class BaseOffset: return get_day_of_month(&dts, self._day_opt) def is_on_offset(self, dt: datetime) -> bool: + """ + Return boolean whether a timestamp intersects with this frequency. + + Parameters + ---------- + dt: datetime.datetime + Timestamp to check intersections with frequency. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> freq = pd.offsets.Day(1) + >>> freq.is_on_offset(ts) + True + """ if self.normalize and not _is_normalized(dt): return False @@ -745,26 +822,96 @@ cdef class BaseOffset: def is_anchored(self) -> bool: # TODO: Does this make sense for the general case? It would help # if there were a canonical docstring for what is_anchored means. + """ + Return boolean whether the frequency is a unit frequency. + + Examples + -------- + >>> pd.DateOffset().is_anchored() + True + >>> pd.DateOffset(2).is_anchored() + False + """ return self.n == 1 # ------------------------------------------------------------------ def is_month_start(self, _Timestamp ts): + """ + Return boolean whether a timestamp occurs on the month start. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> freq = pd.offsets.Hour(5) + >>> freq.is_month_start(ts) + True + """ return ts._get_start_end_field("is_month_start", self) def is_month_end(self, _Timestamp ts): + """ + Return boolean whether a timestamp occurs on the month end. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> freq = pd.offsets.Hour(5) + >>> freq.is_month_end(ts) + False + """ return ts._get_start_end_field("is_month_end", self) def is_quarter_start(self, _Timestamp ts): + """ + Return boolean whether a timestamp occurs on the quarter start. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> freq = pd.offsets.Hour(5) + >>> freq.is_quarter_start(ts) + True + """ return ts._get_start_end_field("is_quarter_start", self) def is_quarter_end(self, _Timestamp ts): + """ + Return boolean whether a timestamp occurs on the quarter end. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> freq = pd.offsets.Hour(5) + >>> freq.is_quarter_end(ts) + False + """ return ts._get_start_end_field("is_quarter_end", self) def is_year_start(self, _Timestamp ts): + """ + Return boolean whether a timestamp occurs on the year start. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> freq = pd.offsets.Hour(5) + >>> freq.is_year_start(ts) + True + """ return ts._get_start_end_field("is_year_start", self) def is_year_end(self, _Timestamp ts): + """ + Return boolean whether a timestamp occurs on the year end. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> freq = pd.offsets.Hour(5) + >>> freq.is_year_end(ts) + False + """ return ts._get_start_end_field("is_year_end", self) @@ -837,6 +984,19 @@ cdef class Tick(SingleConstructorOffset): @property def nanos(self) -> int64_t: + """ + Return an integer of the total number of nanoseconds. + + Raises + ------ + ValueError + If the frequency is non-fixed. + + Examples + -------- + >>> pd.offsets.Hour(5).nanos + 18000000000000 + """ return self.n * self._nanos_inc def is_on_offset(self, dt: datetime) -> bool: From c42ff6b3ee612c2942285e76d3c4028fb3a8df74 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sun, 7 Aug 2022 18:31:42 -0700 Subject: [PATCH 2/5] Finish examples for offsets --- pandas/_libs/tslibs/offsets.pyx | 110 +++++++++++++++++++++++++++++++- 1 file changed, 109 insertions(+), 1 deletion(-) diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index 6952b1497e65f..2b0498288f898 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -722,7 +722,7 @@ cdef class BaseOffset: Parameters ---------- - dt: datetime.datetime + dt : datetime.datetime Timestamp to check intersections with frequency. Examples @@ -1539,6 +1539,12 @@ cdef class BusinessMixin(SingleConstructorOffset): cdef class BusinessDay(BusinessMixin): """ DateOffset subclass representing possibly n business days. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 7, 5) + >>> ts + pd.offsets.BusinessDay() + Timestamp('2022-08-08 00:00:00') """ _period_dtype_code = PeriodDtypeCode.B _prefix = "B" @@ -1659,6 +1665,12 @@ cdef class BusinessHour(BusinessMixin): Start time of your custom business hour in 24h format. end : str, default: "17:00" End time of your custom business hour in 24h format. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 8, 5, 16) + >>> ts + pd.offsets.BusinessHour() + Timestamp('2022-08-08 09:00:00') """ _prefix = "BH" @@ -2192,6 +2204,12 @@ cdef class BYearBegin(YearOffset): cdef class YearEnd(YearOffset): """ DateOffset increments between calendar year ends. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.YearEnd() + Timestamp('2022-12-31 00:00:00') """ _default_month = 12 @@ -2211,6 +2229,12 @@ cdef class YearEnd(YearOffset): cdef class YearBegin(YearOffset): """ DateOffset increments between calendar year begin dates. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.YearBegin() + Timestamp('2023-01-01 00:00:00') """ _default_month = 1 @@ -2356,6 +2380,12 @@ cdef class QuarterEnd(QuarterOffset): startingMonth = 1 corresponds to dates like 1/31/2007, 4/30/2007, ... startingMonth = 2 corresponds to dates like 2/28/2007, 5/31/2007, ... startingMonth = 3 corresponds to dates like 3/31/2007, 6/30/2007, ... + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.QuarterEnd() + Timestamp('2022-03-31 00:00:00') """ _default_starting_month = 3 _prefix = "Q" @@ -2378,6 +2408,12 @@ cdef class QuarterBegin(QuarterOffset): startingMonth = 1 corresponds to dates like 1/01/2007, 4/01/2007, ... startingMonth = 2 corresponds to dates like 2/01/2007, 5/01/2007, ... startingMonth = 3 corresponds to dates like 3/01/2007, 6/01/2007, ... + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.QuarterBegin() + Timestamp('2022-03-01 00:00:00') """ _default_starting_month = 3 _from_name_starting_month = 1 @@ -2418,6 +2454,12 @@ cdef class MonthOffset(SingleConstructorOffset): cdef class MonthEnd(MonthOffset): """ DateOffset of one month end. + + Examples + ________ + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.MonthEnd() + Timestamp('2022-01-31 00:00:00') """ _period_dtype_code = PeriodDtypeCode.M _prefix = "M" @@ -2427,6 +2469,12 @@ cdef class MonthEnd(MonthOffset): cdef class MonthBegin(MonthOffset): """ DateOffset of one month at beginning. + + Examples + ________ + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.MonthBegin() + Timestamp('2022-02-01 00:00:00') """ _prefix = "MS" _day_opt = "start" @@ -2613,6 +2661,12 @@ cdef class SemiMonthEnd(SemiMonthOffset): n : int normalize : bool, default False day_of_month : int, {1, 3,...,27}, default 15 + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.SemiMonthEnd() + Timestamp('2022-01-15 00:00:00') """ _prefix = "SM" @@ -2634,6 +2688,12 @@ cdef class SemiMonthBegin(SemiMonthOffset): n : int normalize : bool, default False day_of_month : int, {2, 3,...,27}, default 15 + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.SemiMonthBegin() + Timestamp('2022-01-15 00:00:00') """ _prefix = "SMS" @@ -2656,6 +2716,12 @@ cdef class Week(SingleConstructorOffset): ---------- weekday : int or None, default None Always generate specific day of week. 0 for Monday. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.Week() + Timestamp('2022-01-08 00:00:00') """ _inc = timedelta(weeks=1) @@ -2812,6 +2878,12 @@ cdef class WeekOfMonth(WeekOfMonthMixin): - 4 is Friday - 5 is Saturday - 6 is Sunday. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.WeekOfMonth() + Timestamp('2022-01-03 00:00:00') """ _prefix = "WOM" @@ -2877,6 +2949,12 @@ cdef class LastWeekOfMonth(WeekOfMonthMixin): - 4 is Friday - 5 is Saturday - 6 is Sunday. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.LastWeekOfMonth() + Timestamp('2022-01-31 00:00:00') """ _prefix = "LWOM" @@ -3024,6 +3102,12 @@ cdef class FY5253(FY5253Mixin): - "nearest" means year end is **weekday** closest to last day of month in year. - "last" means year end is final **weekday** of the final month in fiscal year. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.FY5253() + Timestamp('2022-01-31 00:00:00') """ _prefix = "RE" @@ -3201,6 +3285,12 @@ cdef class FY5253Quarter(FY5253Mixin): - "nearest" means year end is **weekday** closest to last day of month in year. - "last" means year end is final **weekday** of the final month in fiscal year. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.FY5253Quarter() + Timestamp('2022-01-31 00:00:00') """ _prefix = "REQ" @@ -3376,6 +3466,12 @@ cdef class Easter(SingleConstructorOffset): DateOffset for the Easter holiday using logic defined in dateutil. Right now uses the revised method which is valid in years 1583-4099. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.Easter() + Timestamp('2022-04-17 00:00:00') """ cpdef __setstate__(self, state): @@ -3437,6 +3533,12 @@ cdef class CustomBusinessDay(BusinessDay): passed to ``numpy.busdaycalendar``. calendar : np.busdaycalendar offset : timedelta, default timedelta(0) + + Examples + -------- + >>> ts = pd.Timestamp(2022, 8, 5) + >>> pd.offsets.CustomBusinessDay(1) + Timestamp('2022-08-08 00:00:00') """ _prefix = "C" @@ -3517,6 +3619,12 @@ cdef class CustomBusinessHour(BusinessHour): Start time of your custom business hour in 24h format. end : str, default: "17:00" End time of your custom business hour in 24h format. + + Examples + -------- + >>> ts = pd.Timestamp(2022, 8, 5, 16) + >>> ts + pd.offsets.CustomBusinessHour() + Timestamp('2022-08-08 09:00:00') """ _prefix = "CBH" From f2ff81c07185a6bafe35037e4539e21b691b1bcb Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sun, 7 Aug 2022 18:31:51 -0700 Subject: [PATCH 3/5] Finish examples for offsets --- ci/code_checks.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 733202165b33a..113186c746157 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -78,8 +78,8 @@ fi ### DOCSTRINGS ### if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then - MSG='Validate docstrings (EX01, EX04, GL01, GL02, GL03, GL04, GL05, GL06, GL07, GL09, GL10, PR03, PR04, PR05, PR06, PR08, PR09, PR10, RT01, RT04, RT05, SA02, SA03, SA04, SS01, SS02, SS03, SS04, SS05, SS06)' ; echo $MSG - $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX01,EX04,GL01,GL02,GL03,GL04,GL05,GL06,GL07,GL09,GL10,PR03,PR04,PR05,PR06,PR08,PR09,PR10,RT01,RT04,RT05,SA02,SA03,SA04,SS01,SS02,SS03,SS04,SS05,SS06 + MSG='Validate docstrings (EX04, GL01, GL02, GL03, GL04, GL05, GL06, GL07, GL09, GL10, PR03, PR04, PR05, PR06, PR08, PR09, PR10, RT01, RT04, RT05, SA02, SA03, SA04, SS01, SS02, SS03, SS04, SS05, SS06)' ; echo $MSG + $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX04,GL01,GL02,GL03,GL04,GL05,GL06,GL07,GL09,GL10,PR03,PR04,PR05,PR06,PR08,PR09,PR10,RT01,RT04,RT05,SA02,SA03,SA04,SS01,SS02,SS03,SS04,SS05,SS06 RET=$(($RET + $?)) ; echo $MSG "DONE" fi From a9da55be79430359ed91ddee35da1fa2b05b6aa0 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Tue, 9 Aug 2022 12:19:46 -0700 Subject: [PATCH 4/5] Undo API removals, fix failures --- doc/source/reference/offset_frequency.rst | 177 ++++++++++++++++++++++ pandas/_libs/tslibs/offsets.pyx | 8 +- 2 files changed, 181 insertions(+), 4 deletions(-) diff --git a/doc/source/reference/offset_frequency.rst b/doc/source/reference/offset_frequency.rst index 4391eda62ac1d..f0e531cd81f84 100644 --- a/doc/source/reference/offset_frequency.rst +++ b/doc/source/reference/offset_frequency.rst @@ -26,15 +26,22 @@ Properties DateOffset.normalize DateOffset.rule_code DateOffset.n + DateOffset.is_month_start + DateOffset.is_month_end Methods ~~~~~~~ .. autosummary:: :toctree: api/ + DateOffset.apply + DateOffset.apply_index DateOffset.copy + DateOffset.isAnchored + DateOffset.onOffset DateOffset.is_anchored DateOffset.is_on_offset + DateOffset.__call__ DateOffset.is_month_start DateOffset.is_month_end DateOffset.is_quarter_start @@ -79,9 +86,14 @@ Methods .. autosummary:: :toctree: api/ + BusinessDay.apply + BusinessDay.apply_index BusinessDay.copy + BusinessDay.isAnchored + BusinessDay.onOffset BusinessDay.is_anchored BusinessDay.is_on_offset + BusinessDay.__call__ BusinessDay.is_month_start BusinessDay.is_month_end BusinessDay.is_quarter_start @@ -119,9 +131,14 @@ Methods .. autosummary:: :toctree: api/ + BusinessHour.apply + BusinessHour.apply_index BusinessHour.copy + BusinessHour.isAnchored + BusinessHour.onOffset BusinessHour.is_anchored BusinessHour.is_on_offset + BusinessHour.__call__ BusinessHour.is_month_start BusinessHour.is_month_end BusinessHour.is_quarter_start @@ -166,9 +183,14 @@ Methods .. autosummary:: :toctree: api/ + CustomBusinessDay.apply_index + CustomBusinessDay.apply CustomBusinessDay.copy + CustomBusinessDay.isAnchored + CustomBusinessDay.onOffset CustomBusinessDay.is_anchored CustomBusinessDay.is_on_offset + CustomBusinessDay.__call__ CustomBusinessDay.is_month_start CustomBusinessDay.is_month_end CustomBusinessDay.is_quarter_start @@ -206,9 +228,14 @@ Methods .. autosummary:: :toctree: api/ + CustomBusinessHour.apply + CustomBusinessHour.apply_index CustomBusinessHour.copy + CustomBusinessHour.isAnchored + CustomBusinessHour.onOffset CustomBusinessHour.is_anchored CustomBusinessHour.is_on_offset + CustomBusinessHour.__call__ CustomBusinessHour.is_month_start CustomBusinessHour.is_month_end CustomBusinessHour.is_quarter_start @@ -241,9 +268,14 @@ Methods .. autosummary:: :toctree: api/ + MonthEnd.apply + MonthEnd.apply_index MonthEnd.copy + MonthEnd.isAnchored + MonthEnd.onOffset MonthEnd.is_anchored MonthEnd.is_on_offset + MonthEnd.__call__ MonthEnd.is_month_start MonthEnd.is_month_end MonthEnd.is_quarter_start @@ -276,9 +308,14 @@ Methods .. autosummary:: :toctree: api/ + MonthBegin.apply + MonthBegin.apply_index MonthBegin.copy + MonthBegin.isAnchored + MonthBegin.onOffset MonthBegin.is_anchored MonthBegin.is_on_offset + MonthBegin.__call__ MonthBegin.is_month_start MonthBegin.is_month_end MonthBegin.is_quarter_start @@ -320,9 +357,14 @@ Methods .. autosummary:: :toctree: api/ + BusinessMonthEnd.apply + BusinessMonthEnd.apply_index BusinessMonthEnd.copy + BusinessMonthEnd.isAnchored + BusinessMonthEnd.onOffset BusinessMonthEnd.is_anchored BusinessMonthEnd.is_on_offset + BusinessMonthEnd.__call__ BusinessMonthEnd.is_month_start BusinessMonthEnd.is_month_end BusinessMonthEnd.is_quarter_start @@ -364,9 +406,14 @@ Methods .. autosummary:: :toctree: api/ + BusinessMonthBegin.apply + BusinessMonthBegin.apply_index BusinessMonthBegin.copy + BusinessMonthBegin.isAnchored + BusinessMonthBegin.onOffset BusinessMonthBegin.is_anchored BusinessMonthBegin.is_on_offset + BusinessMonthBegin.__call__ BusinessMonthBegin.is_month_start BusinessMonthBegin.is_month_end BusinessMonthBegin.is_quarter_start @@ -412,9 +459,14 @@ Methods .. autosummary:: :toctree: api/ + CustomBusinessMonthEnd.apply + CustomBusinessMonthEnd.apply_index CustomBusinessMonthEnd.copy + CustomBusinessMonthEnd.isAnchored + CustomBusinessMonthEnd.onOffset CustomBusinessMonthEnd.is_anchored CustomBusinessMonthEnd.is_on_offset + CustomBusinessMonthEnd.__call__ CustomBusinessMonthEnd.is_month_start CustomBusinessMonthEnd.is_month_end CustomBusinessMonthEnd.is_quarter_start @@ -460,9 +512,14 @@ Methods .. autosummary:: :toctree: api/ + CustomBusinessMonthBegin.apply + CustomBusinessMonthBegin.apply_index CustomBusinessMonthBegin.copy + CustomBusinessMonthBegin.isAnchored + CustomBusinessMonthBegin.onOffset CustomBusinessMonthBegin.is_anchored CustomBusinessMonthBegin.is_on_offset + CustomBusinessMonthBegin.__call__ CustomBusinessMonthBegin.is_month_start CustomBusinessMonthBegin.is_month_end CustomBusinessMonthBegin.is_quarter_start @@ -496,9 +553,14 @@ Methods .. autosummary:: :toctree: api/ + SemiMonthEnd.apply + SemiMonthEnd.apply_index SemiMonthEnd.copy + SemiMonthEnd.isAnchored + SemiMonthEnd.onOffset SemiMonthEnd.is_anchored SemiMonthEnd.is_on_offset + SemiMonthEnd.__call__ SemiMonthEnd.is_month_start SemiMonthEnd.is_month_end SemiMonthEnd.is_quarter_start @@ -532,9 +594,14 @@ Methods .. autosummary:: :toctree: api/ + SemiMonthBegin.apply + SemiMonthBegin.apply_index SemiMonthBegin.copy + SemiMonthBegin.isAnchored + SemiMonthBegin.onOffset SemiMonthBegin.is_anchored SemiMonthBegin.is_on_offset + SemiMonthBegin.__call__ SemiMonthBegin.is_month_start SemiMonthBegin.is_month_end SemiMonthBegin.is_quarter_start @@ -568,9 +635,14 @@ Methods .. autosummary:: :toctree: api/ + Week.apply + Week.apply_index Week.copy + Week.isAnchored + Week.onOffset Week.is_anchored Week.is_on_offset + Week.__call__ Week.is_month_start Week.is_month_end Week.is_quarter_start @@ -604,9 +676,14 @@ Methods .. autosummary:: :toctree: api/ + WeekOfMonth.apply + WeekOfMonth.apply_index WeekOfMonth.copy + WeekOfMonth.isAnchored + WeekOfMonth.onOffset WeekOfMonth.is_anchored WeekOfMonth.is_on_offset + WeekOfMonth.__call__ WeekOfMonth.weekday WeekOfMonth.is_month_start WeekOfMonth.is_month_end @@ -642,9 +719,14 @@ Methods .. autosummary:: :toctree: api/ + LastWeekOfMonth.apply + LastWeekOfMonth.apply_index LastWeekOfMonth.copy + LastWeekOfMonth.isAnchored + LastWeekOfMonth.onOffset LastWeekOfMonth.is_anchored LastWeekOfMonth.is_on_offset + LastWeekOfMonth.__call__ LastWeekOfMonth.is_month_start LastWeekOfMonth.is_month_end LastWeekOfMonth.is_quarter_start @@ -678,9 +760,14 @@ Methods .. autosummary:: :toctree: api/ + BQuarterEnd.apply + BQuarterEnd.apply_index BQuarterEnd.copy + BQuarterEnd.isAnchored + BQuarterEnd.onOffset BQuarterEnd.is_anchored BQuarterEnd.is_on_offset + BQuarterEnd.__call__ BQuarterEnd.is_month_start BQuarterEnd.is_month_end BQuarterEnd.is_quarter_start @@ -714,9 +801,14 @@ Methods .. autosummary:: :toctree: api/ + BQuarterBegin.apply + BQuarterBegin.apply_index BQuarterBegin.copy + BQuarterBegin.isAnchored + BQuarterBegin.onOffset BQuarterBegin.is_anchored BQuarterBegin.is_on_offset + BQuarterBegin.__call__ BQuarterBegin.is_month_start BQuarterBegin.is_month_end BQuarterBegin.is_quarter_start @@ -750,9 +842,14 @@ Methods .. autosummary:: :toctree: api/ + QuarterEnd.apply + QuarterEnd.apply_index QuarterEnd.copy + QuarterEnd.isAnchored + QuarterEnd.onOffset QuarterEnd.is_anchored QuarterEnd.is_on_offset + QuarterEnd.__call__ QuarterEnd.is_month_start QuarterEnd.is_month_end QuarterEnd.is_quarter_start @@ -786,9 +883,14 @@ Methods .. autosummary:: :toctree: api/ + QuarterBegin.apply + QuarterBegin.apply_index QuarterBegin.copy + QuarterBegin.isAnchored + QuarterBegin.onOffset QuarterBegin.is_anchored QuarterBegin.is_on_offset + QuarterBegin.__call__ QuarterBegin.is_month_start QuarterBegin.is_month_end QuarterBegin.is_quarter_start @@ -822,9 +924,14 @@ Methods .. autosummary:: :toctree: api/ + BYearEnd.apply + BYearEnd.apply_index BYearEnd.copy + BYearEnd.isAnchored + BYearEnd.onOffset BYearEnd.is_anchored BYearEnd.is_on_offset + BYearEnd.__call__ BYearEnd.is_month_start BYearEnd.is_month_end BYearEnd.is_quarter_start @@ -858,9 +965,14 @@ Methods .. autosummary:: :toctree: api/ + BYearBegin.apply + BYearBegin.apply_index BYearBegin.copy + BYearBegin.isAnchored + BYearBegin.onOffset BYearBegin.is_anchored BYearBegin.is_on_offset + BYearBegin.__call__ BYearBegin.is_month_start BYearBegin.is_month_end BYearBegin.is_quarter_start @@ -894,9 +1006,14 @@ Methods .. autosummary:: :toctree: api/ + YearEnd.apply + YearEnd.apply_index YearEnd.copy + YearEnd.isAnchored + YearEnd.onOffset YearEnd.is_anchored YearEnd.is_on_offset + YearEnd.__call__ YearEnd.is_month_start YearEnd.is_month_end YearEnd.is_quarter_start @@ -930,9 +1047,14 @@ Methods .. autosummary:: :toctree: api/ + YearBegin.apply + YearBegin.apply_index YearBegin.copy + YearBegin.isAnchored + YearBegin.onOffset YearBegin.is_anchored YearBegin.is_on_offset + YearBegin.__call__ YearBegin.is_month_start YearBegin.is_month_end YearBegin.is_quarter_start @@ -968,11 +1090,16 @@ Methods .. autosummary:: :toctree: api/ + FY5253.apply + FY5253.apply_index FY5253.copy FY5253.get_rule_code_suffix FY5253.get_year_end + FY5253.isAnchored + FY5253.onOffset FY5253.is_anchored FY5253.is_on_offset + FY5253.__call__ FY5253.is_month_start FY5253.is_month_end FY5253.is_quarter_start @@ -1009,12 +1136,17 @@ Methods .. autosummary:: :toctree: api/ + FY5253Quarter.apply + FY5253Quarter.apply_index FY5253Quarter.copy FY5253Quarter.get_rule_code_suffix FY5253Quarter.get_weeks + FY5253Quarter.isAnchored + FY5253Quarter.onOffset FY5253Quarter.is_anchored FY5253Quarter.is_on_offset FY5253Quarter.year_has_extra_week + FY5253Quarter.__call__ FY5253Quarter.is_month_start FY5253Quarter.is_month_end FY5253Quarter.is_quarter_start @@ -1047,9 +1179,14 @@ Methods .. autosummary:: :toctree: api/ + Easter.apply + Easter.apply_index Easter.copy + Easter.isAnchored + Easter.onOffset Easter.is_anchored Easter.is_on_offset + Easter.__call__ Easter.is_month_start Easter.is_month_end Easter.is_quarter_start @@ -1084,8 +1221,13 @@ Methods :toctree: api/ Tick.copy + Tick.isAnchored + Tick.onOffset Tick.is_anchored Tick.is_on_offset + Tick.__call__ + Tick.apply + Tick.apply_index Tick.is_month_start Tick.is_month_end Tick.is_quarter_start @@ -1120,8 +1262,13 @@ Methods :toctree: api/ Day.copy + Day.isAnchored + Day.onOffset Day.is_anchored Day.is_on_offset + Day.__call__ + Day.apply + Day.apply_index Day.is_month_start Day.is_month_end Day.is_quarter_start @@ -1156,8 +1303,13 @@ Methods :toctree: api/ Hour.copy + Hour.isAnchored + Hour.onOffset Hour.is_anchored Hour.is_on_offset + Hour.__call__ + Hour.apply + Hour.apply_index Hour.is_month_start Hour.is_month_end Hour.is_quarter_start @@ -1192,8 +1344,13 @@ Methods :toctree: api/ Minute.copy + Minute.isAnchored + Minute.onOffset Minute.is_anchored Minute.is_on_offset + Minute.__call__ + Minute.apply + Minute.apply_index Minute.is_month_start Minute.is_month_end Minute.is_quarter_start @@ -1228,8 +1385,13 @@ Methods :toctree: api/ Second.copy + Second.isAnchored + Second.onOffset Second.is_anchored Second.is_on_offset + Second.__call__ + Second.apply + Second.apply_index Second.is_month_start Second.is_month_end Second.is_quarter_start @@ -1264,8 +1426,13 @@ Methods :toctree: api/ Milli.copy + Milli.isAnchored + Milli.onOffset Milli.is_anchored Milli.is_on_offset + Milli.__call__ + Milli.apply + Milli.apply_index Milli.is_month_start Milli.is_month_end Milli.is_quarter_start @@ -1300,8 +1467,13 @@ Methods :toctree: api/ Micro.copy + Micro.isAnchored + Micro.onOffset Micro.is_anchored Micro.is_on_offset + Micro.__call__ + Micro.apply + Micro.apply_index Micro.is_month_start Micro.is_month_end Micro.is_quarter_start @@ -1336,8 +1508,13 @@ Methods :toctree: api/ Nano.copy + Nano.isAnchored + Nano.onOffset Nano.is_anchored Nano.is_on_offset + Nano.__call__ + Nano.apply + Nano.apply_index Nano.is_month_start Nano.is_month_end Nano.is_quarter_start diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index 2b0498288f898..53edaa315eaca 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -1542,7 +1542,7 @@ cdef class BusinessDay(BusinessMixin): Examples -------- - >>> ts = pd.Timestamp(2022, 7, 5) + >>> ts = pd.Timestamp(2022, 8, 5) >>> ts + pd.offsets.BusinessDay() Timestamp('2022-08-08 00:00:00') """ @@ -2456,7 +2456,7 @@ cdef class MonthEnd(MonthOffset): DateOffset of one month end. Examples - ________ + -------- >>> ts = pd.Timestamp(2022, 1, 1) >>> ts + pd.offsets.MonthEnd() Timestamp('2022-01-31 00:00:00') @@ -2471,7 +2471,7 @@ cdef class MonthBegin(MonthOffset): DateOffset of one month at beginning. Examples - ________ + -------- >>> ts = pd.Timestamp(2022, 1, 1) >>> ts + pd.offsets.MonthBegin() Timestamp('2022-02-01 00:00:00') @@ -3537,7 +3537,7 @@ cdef class CustomBusinessDay(BusinessDay): Examples -------- >>> ts = pd.Timestamp(2022, 8, 5) - >>> pd.offsets.CustomBusinessDay(1) + >>> ts + pd.offsets.CustomBusinessDay(1) Timestamp('2022-08-08 00:00:00') """ From c0b336a3c0b9458d98f89e9abfb12ea6afdc43db Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Wed, 10 Aug 2022 11:19:54 -0700 Subject: [PATCH 5/5] Address review --- pandas/_libs/tslibs/offsets.pyx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index 6f90d2ea7ec27..d553c0d77bc56 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -592,6 +592,9 @@ cdef class BaseOffset: Examples -------- + >>> pd.offsets.Hour().name + 'H' + >>> pd.offsets.Hour(5).name 'H' """ @@ -618,6 +621,9 @@ cdef class BaseOffset: >>> pd.offsets.BusinessHour(2).freqstr '2BH' + >>> pd.offsets.Nano().freqstr + 'N' + >>> pd.offsets.Nano(-3).freqstr '-3N' """ @@ -731,6 +737,13 @@ cdef class BaseOffset: >>> freq = pd.offsets.Day(1) >>> freq.is_on_offset(ts) True + + >>> ts = pd.Timestamp(2022, 8, 6) + >>> ts.day_name() + 'Saturday' + >>> freq = pd.offsets.BusinessDay(1) + >>> freq.is_on_offset(ts) + False """ if self.normalize and not _is_normalized(dt): return False @@ -823,7 +836,7 @@ cdef class BaseOffset: # TODO: Does this make sense for the general case? It would help # if there were a canonical docstring for what is_anchored means. """ - Return boolean whether the frequency is a unit frequency. + Return boolean whether the frequency is a unit frequency (n=1). Examples --------