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

* add parameters and examples to CustomBusinessMonthBegin/End

* move _attributes to _CustomBusinessMonth

Author: natmokval

pandas/_libs/tslibs/offsets.pyx

@@ -4329,28 +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"]
     )
@@ -4426,10 +4404,124 @@ 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"
 
 
 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"