Skip to content

DOC: add parameters and examples to CustomBusinessMonthBegin/End #55328

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 2, 2023
Merged

DOC: add parameters and examples to CustomBusinessMonthBegin/End #55328

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d5ab128
add parameters and examples to CustomBusinessMonthBegin/End
natmokval Sep 29, 2023
182ebbe
move _attributes to _CustomBusinessMonth
natmokval Oct 1, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 120 additions & 26 deletions pandas/_libs/tslibs/offsets.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4329,32 +4329,6 @@ cdef class CustomBusinessHour(BusinessHour):


cdef class _CustomBusinessMonth(BusinessMixin):
"""
DateOffset subclass representing custom business month(s).

Increments between beginning/end of month dates.

Parameters
----------
n : int, default 1
The number of months represented.
normalize : bool, default False
Normalize start/end dates to midnight before generating date range.
weekmask : str, Default 'Mon Tue Wed Thu Fri'
Weekmask of valid business days, passed to ``numpy.busdaycalendar``.
holidays : list
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.
"""

_attributes = tuple(
["n", "normalize", "weekmask", "holidays", "calendar", "offset"]
)

def __init__(
self,
n=1,
Expand Down Expand Up @@ -4426,11 +4400,131 @@ cdef class _CustomBusinessMonth(BusinessMixin):


cdef class CustomBusinessMonthEnd(_CustomBusinessMonth):
"""
DateOffset subclass representing custom business month(s).

Increments between end of month dates.

Parameters
----------
n : int, default 1
The number of months represented.
normalize : bool, default False
Normalize end dates to midnight before generating date range.
weekmask : str, Default 'Mon Tue Wed Thu Fri'
Weekmask of valid business days, passed to ``numpy.busdaycalendar``.
holidays : list
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.

See Also
--------
:class:`~pandas.tseries.offsets.DateOffset` : Standard kind of date increment.

Examples
--------
In the example below we use the default parameters.

>>> ts = pd.Timestamp(2022, 8, 5)
>>> ts + pd.offsets.CustomBusinessMonthEnd()
Timestamp('2022-08-31 00:00:00')

Custom business month end 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.CustomBusinessMonthEnd(weekmask="Wed Thu")
>>> pd.date_range(dt.datetime(2022, 7, 10), dt.datetime(2022, 12, 18),
... freq=freq).strftime('%a %d %b %Y %H:%M')
Index(['Thu 28 Jul 2022 00:00', 'Wed 31 Aug 2022 00:00',
'Thu 29 Sep 2022 00:00', 'Thu 27 Oct 2022 00:00',
'Wed 30 Nov 2022 00:00'],
dtype='object')

Using NumPy business day calendar you can define custom holidays.

>>> import datetime as dt
>>> bdc = np.busdaycalendar(holidays=['2022-08-01', '2022-09-30',
... '2022-10-31', '2022-11-01'])
>>> freq = pd.offsets.CustomBusinessMonthEnd(calendar=bdc)
>>> pd.date_range(dt.datetime(2022, 7, 10), dt.datetime(2022, 11, 10), freq=freq)
DatetimeIndex(['2022-07-29', '2022-08-31', '2022-09-29', '2022-10-28'],
dtype='datetime64[ns]', freq='CBM')
"""

_prefix = "CBM"
_attributes = tuple(
["n", "normalize", "weekmask", "holidays", "calendar", "offset"]
)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok with moving the docstring, but I think _attributes could have stayed in the parent class? could we move that back please to remove duplication?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for reviewing this PR. I moved _attributes to _CustomBusinessMonth



cdef class CustomBusinessMonthBegin(_CustomBusinessMonth):
"""
DateOffset subclass representing custom business month(s).

Increments between beginning of month dates.

Parameters
----------
n : int, default 1
The number of months represented.
normalize : bool, default False
Normalize start dates to midnight before generating date range.
weekmask : str, Default 'Mon Tue Wed Thu Fri'
Weekmask of valid business days, passed to ``numpy.busdaycalendar``.
holidays : list
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.

See Also
--------
:class:`~pandas.tseries.offsets.DateOffset` : Standard kind of date increment.

Examples
--------
In the example below we use the default parameters.

>>> ts = pd.Timestamp(2022, 8, 5)
>>> ts + pd.offsets.CustomBusinessMonthBegin()
Timestamp('2022-09-01 00:00:00')

Custom business month start 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.CustomBusinessMonthBegin(weekmask="Wed Thu")
>>> pd.date_range(dt.datetime(2022, 7, 10), dt.datetime(2022, 12, 18),
... freq=freq).strftime('%a %d %b %Y %H:%M')
Index(['Wed 03 Aug 2022 00:00', 'Thu 01 Sep 2022 00:00',
'Wed 05 Oct 2022 00:00', 'Wed 02 Nov 2022 00:00',
'Thu 01 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-08-01', '2022-09-30',
... '2022-10-31', '2022-11-01'])
>>> freq = pd.offsets.CustomBusinessMonthBegin(calendar=bdc)
>>> pd.date_range(dt.datetime(2022, 7, 10), dt.datetime(2022, 11, 10), freq=freq)
DatetimeIndex(['2022-08-02', '2022-09-01', '2022-10-03', '2022-11-02'],
dtype='datetime64[ns]', freq='CBMS')
"""

_prefix = "CBMS"
_attributes = tuple(
["n", "normalize", "weekmask", "holidays", "calendar", "offset"]
)


BDay = BusinessDay
Expand Down