BUG: Breaking change to offsets.pyx - quarter offset classes

doc/source/reference/offset_frequency.rst

@@ -655,6 +655,7 @@ Properties
     BQuarterEnd.normalize
     BQuarterEnd.rule_code
     BQuarterEnd.n
+    BQuarterEnd.month
     BQuarterEnd.startingMonth
 
 Methods
@@ -690,6 +691,7 @@ Properties
     BQuarterBegin.normalize
     BQuarterBegin.rule_code
     BQuarterBegin.n
+    BQuarterBegin.month
     BQuarterBegin.startingMonth
 
 Methods
@@ -725,6 +727,7 @@ Properties
     QuarterEnd.normalize
     QuarterEnd.rule_code
     QuarterEnd.n
+    QuarterEnd.month
     QuarterEnd.startingMonth
 
 Methods
@@ -760,6 +763,7 @@ Properties
     QuarterBegin.normalize
     QuarterBegin.rule_code
     QuarterBegin.n
+    QuarterBegin.month
     QuarterBegin.startingMonth
 
 Methods

doc/source/whatsnew/v1.3.0.rst

@@ -458,6 +458,7 @@ Deprecations
 - Deprecated allowing partial failure in :meth:`Series.transform` and :meth:`DataFrame.transform` when ``func`` is list-like or dict-like and raises anything but ``TypeError``; ``func`` raising anything but a ``TypeError`` will raise in a future version (:issue:`40211`)
 - Deprecated support for ``np.ma.mrecords.MaskedRecords`` in the :class:`DataFrame` constructor, pass ``{name: data[name] for name in data.dtype.names}`` instead (:issue:`40363`)
 - Deprecated the use of ``**kwargs`` in :class:`.ExcelWriter`; use the keyword argument ``engine_kwargs`` instead (:issue:`40430`)
+- Deprecated the use of keyword argument ``startingMonth`` in quarter-based offsets :class:`QuarterBegin`, :class:`QuarterEnd`, :class:`BQuarterBegin`, :class:`BQuarterEnd`; use ``month`` instead (:issue:`5307`)
 
 .. ---------------------------------------------------------------------------
 
@@ -511,6 +512,7 @@ Datetimelike
 - Bug in :meth:`Timedelta.round`, :meth:`Timedelta.floor`, :meth:`Timedelta.ceil` for values near the implementation bounds of :class:`Timedelta` (:issue:`38964`)
 - Bug in :func:`date_range` incorrectly creating :class:`DatetimeIndex` containing ``NaT`` instead of raising ``OutOfBoundsDatetime`` in corner cases (:issue:`24124`)
 - Bug in :func:`infer_freq` incorrectly fails to infer 'H' frequency of :class:`DatetimeIndex` if the latter has a timezone and crosses DST boundaries (:issue:`39556`)
+- Bug in offsets :class:`QuarterBegin` and :class:`BQuarterBegin` returning days that are not conventional quarter beginnings (:issue:`8435`)
 
 Timedelta
 ^^^^^^^^^

pandas/_libs/tslibs/offsets.pyx

@@ -1840,7 +1840,7 @@ cdef class YearOffset(SingleConstructorOffset):
     """
     _attributes = tuple(["n", "normalize", "month"])
 
-    # _default_month: int  # FIXME: python annotation here breaks things
+    # FIXME: python annotation here breaks things
 
     cdef readonly:
         int month
@@ -1986,52 +1986,90 @@ cdef class YearBegin(YearOffset):
 # Quarter-Based Offset Classes
 
 cdef class QuarterOffset(SingleConstructorOffset):
-    _attributes = tuple(["n", "normalize", "startingMonth"])
+    """
+    Base for quarter-based offset classes.
+
+    Parameters
+    ----------
+    n : int, default 1
+        Number of quarters to offset.
+    normalize : bool, default False
+        If true, the time component of the resulting date-time is converted
+        to 00:00:00, i.e. midnight (the start, not the end of date-time).
+    month : int
+        The calendar month number (1 for January) of the beginning or ending
+        month in a custom-defined quarter to be used as an offset.
+
+        .. versionadded:: 1.X.X
+    startingMonth : int
+        The calendar month number (1 for January) of the beginning or ending
+        month in a custom-defined quarter to be used as an offset.
+
+        .. deprecated:: 1.X.X
+    """
+
+    _attributes = tuple(["n", "normalize", "month"])
     # TODO: Consider combining QuarterOffset and YearOffset __init__ at some
-    #       point.  Also apply_index, is_on_offset, rule_code if
-    #       startingMonth vs month attr names are resolved
+    #       point. Also apply_index, is_on_offset, rule_code.
 
-    # FIXME: python annotations here breaks things
-    # _default_starting_month: int
-    # _from_name_starting_month: int
+    # FIXME: python annotation here breaks things
 
     cdef readonly:
-        int startingMonth
+        int month
+        int startingMonth  # Backwards compatibility
 
-    def __init__(self, n=1, normalize=False, startingMonth=None):
+    def __init__(self, n=1, normalize=False, month=None,
+                 *, startingMonth=None):  # Backwards compatibility
         BaseOffset.__init__(self, n, normalize)
 
-        if startingMonth is None:
-            startingMonth = self._default_starting_month
-        self.startingMonth = startingMonth
+        # Backwards compatibility
+        if month and startingMonth and month != startingMonth:
+            raise TypeError("Offset received both month and startingMonth")
+        elif month is None and startingMonth is not None:
+            warnings.warn(
+                "startingMonth is deprecated, use month instead.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+            month = startingMonth
+
+        month = month if month is not None else self._default_month
+        self.month = month
+
+        if month < 1 or month > 12:
+            raise ValueError("Month must go from 1 to 12.")
 
     cpdef __setstate__(self, state):
-        self.startingMonth = state.pop("startingMonth")
+        try:
+            self.month = state.pop("month")
+        except:
+            self.month = state.pop("startingMonth")  # For legacy pickles
         self.n = state.pop("n")
         self.normalize = state.pop("normalize")
+        self._cache = {}
 
     @classmethod
     def _from_name(cls, suffix=None):
         kwargs = {}
         if suffix:
-            kwargs["startingMonth"] = MONTH_TO_CAL_NUM[suffix]
+            kwargs["month"] = MONTH_TO_CAL_NUM[suffix]
         else:
-            if cls._from_name_starting_month is not None:
-                kwargs["startingMonth"] = cls._from_name_starting_month
+            if cls._from_name_month is not None:
+                kwargs["month"] = cls._from_name_month
         return cls(**kwargs)
 
     @property
     def rule_code(self) -> str:
-        month = MONTH_ALIASES[self.startingMonth]
+        month = MONTH_ALIASES[self.month]
         return f"{self._prefix}-{month}"
 
     def is_anchored(self) -> bool:
-        return self.n == 1 and self.startingMonth is not None
+        return self.n == 1 and self.month is not None
 
     def is_on_offset(self, dt: datetime) -> bool:
         if self.normalize and not _is_normalized(dt):
             return False
-        mod_month = (dt.month - self.startingMonth) % 3
+        mod_month = (dt.month - self.month) % 3
         return mod_month == 0 and dt.day == self._get_offset_day(dt)
 
     @apply_wraps
@@ -2041,9 +2079,9 @@ cdef class QuarterOffset(SingleConstructorOffset):
         # Then find the month in that quarter containing an is_on_offset date for
         # self.  `months_since` is the number of months to shift other.month
         # to get to this on-offset month.
-        months_since = other.month % 3 - self.startingMonth % 3
+        months_since = other.month % 3 - self.month % 3
         qtrs = roll_qtrday(
-            other, self.n, self.startingMonth, day_opt=self._day_opt, modby=3
+            other, self.n, self.month, day_opt=self._day_opt, modby=3
         )
         months = qtrs * 3 - months_since
         return shift_month(other, months, self._day_opt)
@@ -2055,35 +2093,53 @@ cdef class QuarterOffset(SingleConstructorOffset):
     @apply_array_wraps
     def _apply_array(self, dtarr):
         shifted = shift_quarters(
-            dtarr.view("i8"), self.n, self.startingMonth, self._day_opt
+            dtarr.view("i8"), self.n, self.month, self._day_opt
         )
         return shifted
 
 
 cdef class BQuarterEnd(QuarterOffset):
     """
-    DateOffset increments between the last business day of each Quarter.
+    DateOffset increments between the last business day of each quarter.
 
-    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/30/2007, 6/29/2007, ...
+    month = 1 corresponds to dates like 1/31/2007, 4/30/2007, ...
+    month = 2 corresponds to dates like 2/28/2007, 5/31/2007, ...
+    month = 3 corresponds to dates like 3/30/2007, 6/29/2007, ...
+
+    Parameters
+    ----------
+    n : int, default 1
+        Number of business quarters to offset.
+    normalize : bool, default False
+        If true, the time component of the resulting date-time is converted
+        to 00:00:00, i.e. midnight (the start, not the end of date-time).
+    month : int, default 3
+        The calendar month number (3 for March) of the last month
+        in a custom-defined business quarter to be used as an offset.
+
+        .. versionadded:: 1.X.X
+    startingMonth : int, default 3
+        The calendar month number (3 for March) of the last month
+        in a custom-defined business quarter to be used as an offset.
+
+        .. deprecated:: 1.X.X
 
     Examples
     --------
-    >>> from pandas.tseries.offset import BQuarterEnd
+    >>> from pandas.tseries.offsets import BQuarterEnd
     >>> ts = pd.Timestamp('2020-05-24 05:01:15')
     >>> ts + BQuarterEnd()
     Timestamp('2020-06-30 05:01:15')
     >>> ts + BQuarterEnd(2)
     Timestamp('2020-09-30 05:01:15')
-    >>> ts + BQuarterEnd(1, startingMonth=2)
+    >>> ts + BQuarterEnd(1, month=2)
     Timestamp('2020-05-29 05:01:15')
-    >>> ts + BQuarterEnd(startingMonth=2)
+    >>> ts + BQuarterEnd(month=2)
     Timestamp('2020-05-29 05:01:15')
     """
     _output_name = "BusinessQuarterEnd"
-    _default_starting_month = 3
-    _from_name_starting_month = 12
+    _default_month = 3
+    _from_name_month = 3
     _prefix = "BQ"
     _day_opt = "business_end"
 
@@ -2092,26 +2148,44 @@ cdef class BQuarterBegin(QuarterOffset):
     """
     DateOffset increments between the first business day of each Quarter.
 
-    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, ...
+    month = 1 corresponds to dates like 1/01/2007, 4/01/2007, ...
+    month = 2 corresponds to dates like 2/01/2007, 5/01/2007, ...
+    month = 3 corresponds to dates like 3/01/2007, 6/01/2007, ...
+
+    Parameters
+    ----------
+    n : int, default 1
+        Number of business quarters to offset.
+    normalize : bool, default False
+        If true, the time component of the resulting date-time is converted
+        to 00:00:00, i.e. midnight (the start, not the end of date-time).
+    month : int, default 1
+        The calendar month number (1 for January) of the first month
+        in a custom-defined business quarter to be used as an offset.
+
+        .. versionadded:: 1.X.X
+    startingMonth : int, default 1
+        The calendar month number (1 for January) of the first month
+        in a custom-defined business quarter to be used as an offset.
+
+        .. deprecated:: 1.X.X
 
     Examples
     --------
-    >>> from pandas.tseries.offset import BQuarterBegin
+    >>> from pandas.tseries.offsets import BQuarterBegin
     >>> ts = pd.Timestamp('2020-05-24 05:01:15')
     >>> ts + BQuarterBegin()
     Timestamp('2020-06-01 05:01:15')
     >>> ts + BQuarterBegin(2)
     Timestamp('2020-09-01 05:01:15')
-    >>> ts + BQuarterBegin(startingMonth=2)
+    >>> ts + BQuarterBegin(month=2)
     Timestamp('2020-08-03 05:01:15')
     >>> ts + BQuarterBegin(-1)
     Timestamp('2020-03-02 05:01:15')
     """
     _output_name = "BusinessQuarterBegin"
-    _default_starting_month = 3
-    _from_name_starting_month = 1
+    _default_month = 1
+    _from_name_month = 1
     _prefix = "BQS"
     _day_opt = "business_start"
 
@@ -2120,34 +2194,73 @@ cdef class QuarterEnd(QuarterOffset):
     """
     DateOffset increments between Quarter end dates.
 
-    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, ...
+    month = 1 corresponds to dates like 1/31/2007, 4/30/2007, ...
+    month = 2 corresponds to dates like 2/28/2007, 5/31/2007, ...
+    month = 3 corresponds to dates like 3/31/2007, 6/30/2007, ...
+
+    Parameters
+    ----------
+    n : int, default 1
+        Number of quarters to offset.
+    normalize : bool, default False
+        If true, the time component of the resulting date-time is converted
+        to 00:00:00, i.e. midnight (the start, not the end of date-time).
+    month : int, default 3
+        The calendar month number (3 for March) of the last month
+        in a custom-defined quarter to be used as an offset.
+
+        .. versionadded:: 1.X.X
+    startingMonth : int, default 3
+        The calendar month number (3 for March) of the last month
+        in a custom-defined quarter to be used as an offset.
+
+        .. deprecated:: 1.X.X
     """
-    _default_starting_month = 3
+    _default_month = 3
+    _from_name_month = 3
     _prefix = "Q"
     _day_opt = "end"
 
     cdef readonly:
         int _period_dtype_code
 
-    def __init__(self, n=1, normalize=False, startingMonth=None):
+    def __init__(self, n=1, normalize=False, month=None,
+                 *, startingMonth=None):  # Backwards compatibility
         # Because QuarterEnd can be the freq for a Period, define its
         #  _period_dtype_code at construction for performance
-        QuarterOffset.__init__(self, n, normalize, startingMonth)
-        self._period_dtype_code = PeriodDtypeCode.Q_DEC + self.startingMonth % 12
+        QuarterOffset.__init__(self, n, normalize, month,
+                               startingMonth=startingMonth)
+        self._period_dtype_code = PeriodDtypeCode.Q_DEC + self.month % 12
 
 
 cdef class QuarterBegin(QuarterOffset):
     """
     DateOffset increments between Quarter start dates.
 
-    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, ...
+    month = 1 corresponds to dates like 1/01/2007, 4/01/2007, ...
+    month = 2 corresponds to dates like 2/01/2007, 5/01/2007, ...
+    month = 3 corresponds to dates like 3/01/2007, 6/01/2007, ...
+
+    Parameters
+    ----------
+    n : int, default 1
+        Number of quarters to offset.
+    normalize : bool, default False
+        If true, the time component of the resulting date-time is converted
+        to 00:00:00, i.e. midnight (the start, not the end of date-time).
+    month : int, default 1
+        The calendar month number (1 for January) of the first month
+        in a custom-defined quarter to be used as an offset.
+
+        .. versionadded:: 1.X.X
+    startingMonth : int, default 1
+        The calendar month number (1 for January) of the first month
+        in a custom-defined quarter to be used as an offset.
+
+        .. deprecated:: 1.X.X
     """
-    _default_starting_month = 3
-    _from_name_starting_month = 1
+    _default_month = 1
+    _from_name_month = 1
     _prefix = "QS"
     _day_opt = "start"
 

pandas/conftest.py

@@ -172,7 +172,7 @@ def pytest_collection_modifyitems(items):
             cls,
             n=st.integers(-24, 24),
             normalize=st.booleans(),
-            startingMonth=st.integers(min_value=1, max_value=12),
+            month=st.integers(min_value=1, max_value=12),
         ),
     )