diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index 9b626b9ee4f6a..d780cf0c4ffe3 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -2574,11 +2574,28 @@ cdef class MonthBegin(MonthOffset): """ DateOffset of one month at beginning. + MonthBegin goes to the next date which is a start of the month. + To get the start of the current month pass the parameter n equals 0. + + See Also + -------- + :class:`~pandas.tseries.offsets.DateOffset` : Standard kind of date increment. + Examples -------- - >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts = pd.Timestamp(2022, 11, 30) + >>> ts + pd.offsets.MonthBegin() + Timestamp('2022-12-01 00:00:00') + + >>> ts = pd.Timestamp(2022, 12, 1) >>> ts + pd.offsets.MonthBegin() - Timestamp('2022-02-01 00:00:00') + Timestamp('2023-01-01 00:00:00') + + If you want to get the start of the current month pass the parameter n equals 0: + + >>> ts = pd.Timestamp(2022, 12, 1) + >>> ts + pd.offsets.MonthBegin(0) + Timestamp('2022-12-01 00:00:00') """ _prefix = "MS" _day_opt = "start" @@ -2616,16 +2633,26 @@ cdef class BusinessMonthBegin(MonthOffset): """ DateOffset of one month at the first business day. + BusinessMonthBegin goes to the next date which is the first business day + of the month. To get the first business day of the current month pass + the parameter n equals 0. + Examples -------- - >>> from pandas.tseries.offsets import BMonthBegin - >>> ts=pd.Timestamp('2020-05-24 05:01:15') - >>> ts + BMonthBegin() - Timestamp('2020-06-01 05:01:15') - >>> ts + BMonthBegin(2) - Timestamp('2020-07-01 05:01:15') - >>> ts + BMonthBegin(-3) - Timestamp('2020-03-02 05:01:15') + >>> ts = pd.Timestamp(2022, 11, 30) + >>> ts + pd.offsets.BMonthBegin() + Timestamp('2022-12-01 00:00:00') + + >>> ts = pd.Timestamp(2022, 12, 1) + >>> ts + pd.offsets.BMonthBegin() + Timestamp('2023-01-02 00:00:00') + + If you want to get the start of the current business month pass + the parameter n equals 0: + + >>> ts = pd.Timestamp(2022, 12, 1) + >>> ts + pd.offsets.BMonthBegin(0) + Timestamp('2022-12-01 00:00:00') """ _prefix = "BMS" _day_opt = "business_start" @@ -3671,7 +3698,9 @@ cdef class Easter(SingleConstructorOffset): cdef class CustomBusinessDay(BusinessDay): """ - DateOffset subclass representing custom business days excluding holidays. + DateOffset subclass representing possibly n custom business days. + + In CustomBusinessDay we can use custom weekmask, holidays, and calendar. Parameters ---------- @@ -3685,13 +3714,50 @@ cdef class CustomBusinessDay(BusinessDay): List/array of dates to exclude from the set of valid business days, passed to ``numpy.busdaycalendar``. calendar : np.busdaycalendar + Calendar to integrate. offset : timedelta, default timedelta(0) + Time offset to apply. Examples -------- - >>> ts = pd.Timestamp(2022, 8, 5) - >>> ts + pd.offsets.CustomBusinessDay(1) - Timestamp('2022-08-08 00:00:00') + In the example below the default parameters give the next business day. + + >>> ts = pd.Timestamp(2022, 8, 5, 16) + >>> ts + pd.offsets.CustomBusinessDay() + Timestamp('2022-08-08 16:00:00') + + Business days can be specified by ``weekmask`` parameter. To convert + the returned datetime object to its string representation + the function strftime() is used in the next example. + + >>> import datetime as dt + >>> freq = pd.offsets.CustomBusinessDay(weekmask="Mon Wed Fri") + >>> pd.date_range(dt.datetime(2022, 12, 10), dt.datetime(2022, 12, 21), + ... freq=freq).strftime('%a %d %b %Y %H:%M') + Index(['Mon 12 Dec 2022 00:00', 'Wed 14 Dec 2022 00:00', + 'Fri 16 Dec 2022 00:00', 'Mon 19 Dec 2022 00:00', + 'Wed 21 Dec 2022 00:00'], + dtype='object') + + Using NumPy business day calendar you can define custom holidays. + + >>> import datetime as dt + >>> bdc = np.busdaycalendar(holidays=['2022-12-12', '2022-12-14']) + >>> freq = pd.offsets.CustomBusinessDay(calendar=bdc) + >>> pd.date_range(dt.datetime(2022, 12, 10), dt.datetime(2022, 12, 25), freq=freq) + DatetimeIndex(['2022-12-13', '2022-12-15', '2022-12-16', '2022-12-19', + '2022-12-20', '2022-12-21', '2022-12-22', '2022-12-23'], + dtype='datetime64[ns]', freq='C') + + If you want to shift the result on n day you can use the parameter ``offset``. + + >>> pd.Timestamp(2022, 8, 5, 16) + pd.offsets.CustomBusinessDay(1) + Timestamp('2022-08-08 16:00:00') + + >>> import datetime as dt + >>> ts = pd.Timestamp(2022, 8, 5, 16) + >>> ts + pd.offsets.CustomBusinessDay(1, offset=dt.timedelta(days=1)) + Timestamp('2022-08-09 16:00:00') """ _prefix = "C"