DEPR: 'A' for yearly frequency and YearEnd in favour of 'Y' (#55252)

Author: natmokval

asv_bench/benchmarks/tslibs/period.py

@@ -72,7 +72,7 @@ def time_now(self, freq):
         self.per.now(freq)
 
     def time_asfreq(self, freq):
-        self.per.asfreq("A")
+        self.per.asfreq("Y")
 
     def time_str(self, freq):
         str(self.per)

doc/source/user_guide/io.rst

@@ -2332,7 +2332,7 @@ A few notes on the generated table schema:
 
   .. ipython:: python
 
-     s_per = pd.Series(1, index=pd.period_range("2016", freq="A-DEC", periods=4))
+     s_per = pd.Series(1, index=pd.period_range("2016", freq="Y-DEC", periods=4))
      build_table_schema(s_per)
 
 * Categoricals use the ``any`` type and an ``enum`` constraint listing

doc/source/user_guide/timeseries.rst

@@ -895,7 +895,7 @@ into ``freq`` keyword arguments. The available date offsets and associated frequ
     :class:`~pandas.tseries.offsets.BQuarterEnd`, ``'BQ``, "business quarter end"
     :class:`~pandas.tseries.offsets.BQuarterBegin`, ``'BQS'``, "business quarter begin"
     :class:`~pandas.tseries.offsets.FY5253Quarter`, ``'REQ'``, "retail (aka 52-53 week) quarter"
-    :class:`~pandas.tseries.offsets.YearEnd`, ``'A'``, "calendar year end"
+    :class:`~pandas.tseries.offsets.YearEnd`, ``'Y'``, "calendar year end"
     :class:`~pandas.tseries.offsets.YearBegin`, ``'AS'`` or ``'BYS'``,"calendar year begin"
     :class:`~pandas.tseries.offsets.BYearEnd`, ``'BA'``, "business year end"
     :class:`~pandas.tseries.offsets.BYearBegin`, ``'BAS'``, "business year begin"
@@ -1258,7 +1258,7 @@ frequencies. We will refer to these aliases as *offset aliases*.
     "BQ", "business quarter end frequency"
     "QS", "quarter start frequency"
     "BQS", "business quarter start frequency"
-    "A, Y", "year end frequency"
+    "Y", "year end frequency"
     "BA, BY", "business year end frequency"
     "AS, YS", "year start frequency"
     "BAS, BYS", "business year start frequency"
@@ -1321,7 +1321,7 @@ frequencies. We will refer to these aliases as *period aliases*.
     "W", "weekly frequency"
     "M", "monthly frequency"
     "Q", "quarterly frequency"
-    "A, Y", "yearly frequency"
+    "Y", "yearly frequency"
     "H", "hourly frequency"
     "min", "minutely frequency"
     "s", "secondly frequency"
@@ -1331,8 +1331,8 @@ frequencies. We will refer to these aliases as *period aliases*.
 
 .. deprecated:: 2.2.0
 
-   Aliases ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
-   ``min``, ``s``, ``ms``, ``us``, and ``ns``.
+   Aliases ``A``, ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
+   ``Y``, ``min``, ``s``, ``ms``, ``us``, and ``ns``.
 
 
 Combining aliases
@@ -1383,18 +1383,18 @@ For some frequencies you can specify an anchoring suffix:
     "(B)Q(S)\-SEP", "quarterly frequency, year ends in September"
     "(B)Q(S)\-OCT", "quarterly frequency, year ends in October"
     "(B)Q(S)\-NOV", "quarterly frequency, year ends in November"
-    "(B)A(S)\-DEC", "annual frequency, anchored end of December. Same as 'A'"
-    "(B)A(S)\-JAN", "annual frequency, anchored end of January"
-    "(B)A(S)\-FEB", "annual frequency, anchored end of February"
-    "(B)A(S)\-MAR", "annual frequency, anchored end of March"
-    "(B)A(S)\-APR", "annual frequency, anchored end of April"
-    "(B)A(S)\-MAY", "annual frequency, anchored end of May"
-    "(B)A(S)\-JUN", "annual frequency, anchored end of June"
-    "(B)A(S)\-JUL", "annual frequency, anchored end of July"
-    "(B)A(S)\-AUG", "annual frequency, anchored end of August"
-    "(B)A(S)\-SEP", "annual frequency, anchored end of September"
-    "(B)A(S)\-OCT", "annual frequency, anchored end of October"
-    "(B)A(S)\-NOV", "annual frequency, anchored end of November"
+    "(B)Y(S)\-DEC", "annual frequency, anchored end of December. Same as 'Y'"
+    "(B)Y(S)\-JAN", "annual frequency, anchored end of January"
+    "(B)Y(S)\-FEB", "annual frequency, anchored end of February"
+    "(B)Y(S)\-MAR", "annual frequency, anchored end of March"
+    "(B)Y(S)\-APR", "annual frequency, anchored end of April"
+    "(B)Y(S)\-MAY", "annual frequency, anchored end of May"
+    "(B)Y(S)\-JUN", "annual frequency, anchored end of June"
+    "(B)Y(S)\-JUL", "annual frequency, anchored end of July"
+    "(B)Y(S)\-AUG", "annual frequency, anchored end of August"
+    "(B)Y(S)\-SEP", "annual frequency, anchored end of September"
+    "(B)Y(S)\-OCT", "annual frequency, anchored end of October"
+    "(B)Y(S)\-NOV", "annual frequency, anchored end of November"
 
 These can be used as arguments to ``date_range``, ``bdate_range``, constructors
 for ``DatetimeIndex``, as well as various other timeseries-related functions
@@ -1690,7 +1690,7 @@ the end of the interval.
 .. warning::
 
     The default values for ``label`` and ``closed`` is '**left**' for all
-    frequency offsets except for 'ME', 'A', 'Q', 'BM', 'BA', 'BQ', and 'W'
+    frequency offsets except for 'ME', 'Y', 'Q', 'BM', 'BA', 'BQ', and 'W'
     which all have a default of 'right'.
 
     This might unintendedly lead to looking ahead, where the value for a later
@@ -1995,7 +1995,7 @@ Because ``freq`` represents a span of ``Period``, it cannot be negative like "-3
 
 .. ipython:: python
 
-   pd.Period("2012", freq="A-DEC")
+   pd.Period("2012", freq="Y-DEC")
 
    pd.Period("2012-1-1", freq="D")
 
@@ -2008,7 +2008,7 @@ frequency. Arithmetic is not allowed between ``Period`` with different ``freq``
 
 .. ipython:: python
 
-   p = pd.Period("2012", freq="A-DEC")
+   p = pd.Period("2012", freq="Y-DEC")
    p + 1
    p - 3
    p = pd.Period("2012-01", freq="2M")
@@ -2050,7 +2050,7 @@ return the number of frequency units between them:
 
 .. ipython:: python
 
-   pd.Period("2012", freq="A-DEC") - pd.Period("2002", freq="A-DEC")
+   pd.Period("2012", freq="Y-DEC") - pd.Period("2002", freq="Y-DEC")
 
 PeriodIndex and period_range
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2184,7 +2184,7 @@ method. Let's start with the fiscal year 2011, ending in December:
 
 .. ipython:: python
 
-   p = pd.Period("2011", freq="A-DEC")
+   p = pd.Period("2011", freq="Y-DEC")
    p
 
 We can convert it to a monthly frequency. Using the ``how`` parameter, we can
@@ -2211,10 +2211,10 @@ input period:
 
    p = pd.Period("2011-12", freq="M")
 
-   p.asfreq("A-NOV")
+   p.asfreq("Y-NOV")
 
 Note that since we converted to an annual frequency that ends the year in
-November, the monthly period of December 2011 is actually in the 2012 A-NOV
+November, the monthly period of December 2011 is actually in the 2012 Y-NOV
 period.
 
 .. _timeseries.quarterly:

doc/source/whatsnew/v2.2.0.rst

@@ -251,6 +251,7 @@ Other Deprecations
 - Deprecated downcasting behavior in :meth:`Series.where`, :meth:`DataFrame.where`, :meth:`Series.mask`, :meth:`DataFrame.mask`, :meth:`Series.clip`, :meth:`DataFrame.clip`; in a future version these will not infer object-dtype columns to non-object dtype, or all-round floats to integer dtype. Call ``result.infer_objects(copy=False)`` on the result for object inference, or explicitly cast floats to ints. To opt in to the future version, use ``pd.set_option("future.no_silent_downcasting", True)`` (:issue:`53656`)
 - Deprecated including the groups in computations when using :meth:`DataFrameGroupBy.apply` and :meth:`DataFrameGroupBy.resample`; pass ``include_groups=False`` to exclude the groups (:issue:`7155`)
 - Deprecated not passing a tuple to :class:`DataFrameGroupBy.get_group` or :class:`SeriesGroupBy.get_group` when grouping by a length-1 list-like (:issue:`25971`)
+- Deprecated string ``A`` denoting frequency in :class:`YearEnd` and strings ``A-DEC``, ``A-JAN``, etc. denoting annual frequencies with various fiscal year ends (:issue:`52536`)
 - Deprecated strings ``S``, ``U``, and ``N`` denoting units in :func:`to_timedelta` (:issue:`52536`)
 - Deprecated strings ``T``, ``S``, ``L``, ``U``, and ``N`` denoting frequencies in :class:`Minute`, :class:`Second`, :class:`Milli`, :class:`Micro`, :class:`Nano` (:issue:`52536`)
 - Deprecated strings ``T``, ``S``, ``L``, ``U``, and ``N`` denoting units in :class:`Timedelta` (:issue:`52536`)

pandas/_libs/tslibs/dtypes.pxd

@@ -13,6 +13,8 @@ cpdef bint is_supported_unit(NPY_DATETIMEUNIT reso)
 
 cpdef freq_to_period_freqstr(freq_n, freq_name)
 cdef dict c_OFFSET_TO_PERIOD_FREQSTR
+cdef dict c_OFFSET_DEPR_FREQSTR
+cdef dict c_REVERSE_OFFSET_DEPR_FREQSTR
 cdef dict c_DEPR_ABBREVS
 cdef dict attrname_to_abbrevs
 cdef dict npy_unit_to_attrname

pandas/_libs/tslibs/dtypes.pyi

@@ -7,6 +7,7 @@ from pandas._libs.tslibs.timedeltas import UnitChoices
 _attrname_to_abbrevs: dict[str, str]
 _period_code_map: dict[str, int]
 OFFSET_TO_PERIOD_FREQSTR: dict[str, str]
+OFFSET_DEPR_FREQSTR: dict[str, str]
 DEPR_ABBREVS: dict[str, UnitChoices]
 
 def periods_per_day(reso: int) -> int: ...

pandas/_libs/tslibs/dtypes.pyx

@@ -101,19 +101,19 @@ cdef class PeriodDtypeBase:
 
 _period_code_map = {
     # Annual freqs with various fiscal year ends.
-    # eg, 2005 for A-FEB runs Mar 1, 2004 to Feb 28, 2005
-    "A-DEC": PeriodDtypeCode.A_DEC,  # Annual - December year end
-    "A-JAN": PeriodDtypeCode.A_JAN,  # Annual - January year end
-    "A-FEB": PeriodDtypeCode.A_FEB,  # Annual - February year end
-    "A-MAR": PeriodDtypeCode.A_MAR,  # Annual - March year end
-    "A-APR": PeriodDtypeCode.A_APR,  # Annual - April year end
-    "A-MAY": PeriodDtypeCode.A_MAY,  # Annual - May year end
-    "A-JUN": PeriodDtypeCode.A_JUN,  # Annual - June year end
-    "A-JUL": PeriodDtypeCode.A_JUL,  # Annual - July year end
-    "A-AUG": PeriodDtypeCode.A_AUG,  # Annual - August year end
-    "A-SEP": PeriodDtypeCode.A_SEP,  # Annual - September year end
-    "A-OCT": PeriodDtypeCode.A_OCT,  # Annual - October year end
-    "A-NOV": PeriodDtypeCode.A_NOV,  # Annual - November year end
+    # eg, 2005 for Y-FEB runs Mar 1, 2004 to Feb 28, 2005
+    "Y-DEC": PeriodDtypeCode.A_DEC,  # Annual - December year end
+    "Y-JAN": PeriodDtypeCode.A_JAN,  # Annual - January year end
+    "Y-FEB": PeriodDtypeCode.A_FEB,  # Annual - February year end
+    "Y-MAR": PeriodDtypeCode.A_MAR,  # Annual - March year end
+    "Y-APR": PeriodDtypeCode.A_APR,  # Annual - April year end
+    "Y-MAY": PeriodDtypeCode.A_MAY,  # Annual - May year end
+    "Y-JUN": PeriodDtypeCode.A_JUN,  # Annual - June year end
+    "Y-JUL": PeriodDtypeCode.A_JUL,  # Annual - July year end
+    "Y-AUG": PeriodDtypeCode.A_AUG,  # Annual - August year end
+    "Y-SEP": PeriodDtypeCode.A_SEP,  # Annual - September year end
+    "Y-OCT": PeriodDtypeCode.A_OCT,  # Annual - October year end
+    "Y-NOV": PeriodDtypeCode.A_NOV,  # Annual - November year end
 
     # Quarterly frequencies with various fiscal year ends.
     # eg, Q42005 for Q-OCT runs Aug 1, 2005 to Oct 31, 2005
@@ -156,22 +156,22 @@ _reverse_period_code_map = {
 # Yearly aliases; careful not to put these in _reverse_period_code_map
 _period_code_map.update({"Y" + key[1:]: _period_code_map[key]
                          for key in _period_code_map
-                         if key.startswith("A-")})
+                         if key.startswith("Y-")})
 
 _period_code_map.update({
     "Q": 2000,   # Quarterly - December year end (default quarterly)
-    "A": PeriodDtypeCode.A,   # Annual
+    "Y": PeriodDtypeCode.A,   # Annual
     "W": 4000,   # Weekly
     "C": 5000,   # Custom Business Day
 })
 
 cdef set _month_names = {
-    x.split("-")[-1] for x in _period_code_map.keys() if x.startswith("A-")
+    x.split("-")[-1] for x in _period_code_map.keys() if x.startswith("Y-")
 }
 
 # Map attribute-name resolutions to resolution abbreviations
 _attrname_to_abbrevs = {
-    "year": "A",
+    "year": "Y",
     "quarter": "Q",
     "month": "M",
     "day": "D",
@@ -192,9 +192,9 @@ OFFSET_TO_PERIOD_FREQSTR: dict = {
     "BQS": "Q",
     "QS": "Q",
     "BQ": "Q",
-    "BA": "A",
-    "AS": "A",
-    "BAS": "A",
+    "BA": "Y",
+    "AS": "Y",
+    "BAS": "Y",
     "MS": "M",
     "D": "D",
     "B": "B",
@@ -205,15 +205,19 @@ OFFSET_TO_PERIOD_FREQSTR: dict = {
     "ns": "ns",
     "H": "H",
     "Q": "Q",
-    "A": "A",
+    "Y": "Y",
     "W": "W",
     "ME": "M",
-    "Y": "A",
-    "BY": "A",
-    "YS": "A",
-    "BYS": "A",
+    "BY": "Y",
+    "YS": "Y",
+    "BYS": "Y",
+}
+OFFSET_DEPR_FREQSTR: dict[str, str]= {
+    "M": "ME",
 }
 cdef dict c_OFFSET_TO_PERIOD_FREQSTR = OFFSET_TO_PERIOD_FREQSTR
+cdef dict c_OFFSET_DEPR_FREQSTR = OFFSET_DEPR_FREQSTR
+cdef dict c_REVERSE_OFFSET_DEPR_FREQSTR = {v: k for k, v in OFFSET_DEPR_FREQSTR.items()}
 
 cpdef freq_to_period_freqstr(freq_n, freq_name):
     if freq_n == 1:
@@ -226,6 +230,20 @@ cpdef freq_to_period_freqstr(freq_n, freq_name):
 
 # Map deprecated resolution abbreviations to correct resolution abbreviations
 DEPR_ABBREVS: dict[str, str]= {
+    "A": "Y",
+    "a": "Y",
+    "A-DEC": "Y-DEC",
+    "A-JAN": "Y-JAN",
+    "A-FEB": "Y-FEB",
+    "A-MAR": "Y-MAR",
+    "A-APR": "Y-APR",
+    "A-MAY": "Y-MAY",
+    "A-JUN": "Y-JUN",
+    "A-JUL": "Y-JUL",
+    "A-AUG": "Y-AUG",
+    "A-SEP": "Y-SEP",
+    "A-OCT": "Y-OCT",
+    "A-NOV": "Y-NOV",
     "T": "min",
     "t": "min",
     "S": "s",

pandas/_libs/tslibs/offsets.pyx

@@ -15,6 +15,7 @@ from cpython.datetime cimport (
     time as dt_time,
     timedelta,
 )
+
 import warnings
 
 import_datetime()
@@ -48,7 +49,6 @@ from pandas._libs.tslibs.ccalendar import (
 )
 from pandas.util._exceptions import find_stack_level
 
-
 from pandas._libs.tslibs.ccalendar cimport (
     dayofweek,
     get_days_in_month,
@@ -58,6 +58,8 @@ from pandas._libs.tslibs.ccalendar cimport (
 from pandas._libs.tslibs.conversion cimport localize_pydatetime
 from pandas._libs.tslibs.dtypes cimport (
     c_DEPR_ABBREVS,
+    c_OFFSET_DEPR_FREQSTR,
+    c_REVERSE_OFFSET_DEPR_FREQSTR,
     periods_per_day,
 )
 from pandas._libs.tslibs.nattype cimport (
@@ -2496,7 +2498,7 @@ cdef class YearEnd(YearOffset):
     """
 
     _default_month = 12
-    _prefix = "A"
+    _prefix = "Y"
     _day_opt = "end"
 
     cdef readonly:
@@ -4539,7 +4541,7 @@ prefix_mapping = {
     offset._prefix: offset
     for offset in [
         YearBegin,  # 'AS'
-        YearEnd,  # 'A'
+        YearEnd,  # 'Y'
         BYearBegin,  # 'BAS'
         BYearEnd,  # 'BA'
         BusinessDay,  # 'B'
@@ -4581,8 +4583,7 @@ _lite_rule_alias = {
     "W": "W-SUN",
     "Q": "Q-DEC",
 
-    "A": "A-DEC",      # YearEnd(month=12),
-    "Y": "A-DEC",
+    "Y": "Y-DEC",      # YearEnd(month=12),
     "AS": "AS-JAN",    # YearBegin(month=1),
     "YS": "AS-JAN",
     "BA": "BA-DEC",    # BYearEnd(month=12),
@@ -4707,21 +4708,22 @@ cpdef to_offset(freq, bint is_period=False):
 
             tups = zip(split[0::4], split[1::4], split[2::4])
             for n, (sep, stride, name) in enumerate(tups):
-                if is_period is False and name == "M":
+                if is_period is False and name in c_OFFSET_DEPR_FREQSTR:
                     warnings.warn(
-                        "\'M\' will be deprecated, please use \'ME\' "
-                        "for \'month end\'",
+                        f"\'{name}\' will be deprecated, please use "
+                        f"\'{c_OFFSET_DEPR_FREQSTR.get(name)}\' instead.",
                         UserWarning,
                         stacklevel=find_stack_level(),
                     )
-                    name = "ME"
-                if is_period is True and name == "ME":
+                    name = c_OFFSET_DEPR_FREQSTR[name]
+                if is_period is True and name in c_REVERSE_OFFSET_DEPR_FREQSTR:
                     raise ValueError(
-                        r"for Period, please use \'M\' "
-                        "instead of \'ME\'"
+                        f"for Period, please use "
+                        f"\'{c_REVERSE_OFFSET_DEPR_FREQSTR.get(name)}\' "
+                        f"instead of \'{name}\'"
                     )
-                elif is_period is True and name == "M":
-                    name = "ME"
+                elif is_period is True and name in c_OFFSET_DEPR_FREQSTR:
+                    name = c_OFFSET_DEPR_FREQSTR.get(name)
 
                 if sep != "" and not sep.isspace():
                     raise ValueError("separator must be spaces")
@@ -4740,6 +4742,7 @@ cpdef to_offset(freq, bint is_period=False):
                         stacklevel=find_stack_level(),
                     )
                     prefix = c_DEPR_ABBREVS[prefix]
+
                 if prefix in {"D", "H", "min", "s", "ms", "us", "ns"}:
                     # For these prefixes, we have something like "3H" or
                     #  "2.5T", so we can construct a Timedelta with the
@@ -4753,7 +4756,7 @@ cpdef to_offset(freq, bint is_period=False):
                         offset *= stride_sign
                 else:
                     stride = int(stride)
-                    offset = _get_offset(name)
+                    offset = _get_offset(prefix)
                     offset = offset * int(np.fabs(stride) * stride_sign)
 
                 if delta is None:

pandas/_libs/tslibs/timestamps.pyx

@@ -1249,7 +1249,7 @@ cdef class _Timestamp(ABCTimestamp):
         >>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651')
         >>> # Year end frequency
         >>> ts.to_period(freq='Y')
-        Period('2020', 'A-DEC')
+        Period('2020', 'Y-DEC')
 
         >>> # Month end frequency
         >>> ts.to_period(freq='M')