DEPR: 'A' for yearly frequency and YearEnd in favour of 'Y'

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,7 +1383,7 @@ 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)\-DEC", "annual frequency, anchored end of December. Same as 'Y'"
     "(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"
@@ -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:

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,13 +205,12 @@ 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",
 }
 cdef dict c_OFFSET_TO_PERIOD_FREQSTR = OFFSET_TO_PERIOD_FREQSTR
 
@@ -226,6 +225,8 @@ 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",
     "T": "min",
     "t": "min",
     "S": "s",

pandas/_libs/tslibs/offsets.pyx

@@ -2496,7 +2496,7 @@ cdef class YearEnd(YearOffset):
     """
 
     _default_month = 12
-    _prefix = "A"
+    _prefix = "Y"
     _day_opt = "end"
 
     cdef readonly:
@@ -4447,7 +4447,7 @@ prefix_mapping = {
     offset._prefix: offset
     for offset in [
         YearBegin,  # 'AS'
-        YearEnd,  # 'A'
+        YearEnd,  # 'Y'
         BYearBegin,  # 'BAS'
         BYearEnd,  # 'BA'
         BusinessDay,  # 'B'
@@ -4489,8 +4489,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),

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')

pandas/core/arrays/arrow/array.py

@@ -2467,7 +2467,7 @@ def _round_temporally(
         if offset is None:
             raise ValueError(f"Must specify a valid frequency: {freq}")
         pa_supported_unit = {
-            "A": "year",
+            "Y": "year",
             "AS": "year",
             "Q": "quarter",
             "QS": "quarter",

pandas/core/arrays/datetimes.py

@@ -2042,7 +2042,7 @@ def isocalendar(self) -> DataFrame:
         >>> idx = pd.date_range("2012-01-01", "2015-01-01", freq="Y")
         >>> idx
         DatetimeIndex(['2012-12-31', '2013-12-31', '2014-12-31'],
-                      dtype='datetime64[ns]', freq='A-DEC')
+                      dtype='datetime64[ns]', freq='Y-DEC')
         >>> idx.is_leap_year
         array([ True, False, False])
 

pandas/core/arrays/period.py

@@ -548,7 +548,7 @@ def __arrow_array__(self, type=None):
 
         >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y")
         >>> idx
-        PeriodIndex(['2023', '2024', '2025'], dtype='period[A-DEC]')
+        PeriodIndex(['2023', '2024', '2025'], dtype='period[Y-DEC]')
         >>> idx.dayofyear
         Index([365, 366, 365], dtype='int64')
         """,
@@ -712,10 +712,10 @@ def asfreq(self, freq=None, how: str = "E") -> Self:
 
         Examples
         --------
-        >>> pidx = pd.period_range('2010-01-01', '2015-01-01', freq='A')
+        >>> pidx = pd.period_range('2010-01-01', '2015-01-01', freq='Y')
         >>> pidx
         PeriodIndex(['2010', '2011', '2012', '2013', '2014', '2015'],
-        dtype='period[A-DEC]')
+        dtype='period[Y-DEC]')
 
         >>> pidx.asfreq('M')
         PeriodIndex(['2010-12', '2011-12', '2012-12', '2013-12', '2014-12',
@@ -1025,18 +1025,18 @@ def period_array(
 
     Examples
     --------
-    >>> period_array([pd.Period('2017', freq='A'),
-    ...               pd.Period('2018', freq='A')])
+    >>> period_array([pd.Period('2017', freq='Y'),
+    ...               pd.Period('2018', freq='Y')])
     <PeriodArray>
     ['2017', '2018']
-    Length: 2, dtype: period[A-DEC]
+    Length: 2, dtype: period[Y-DEC]
 
-    >>> period_array([pd.Period('2017', freq='A'),
-    ...               pd.Period('2018', freq='A'),
+    >>> period_array([pd.Period('2017', freq='Y'),
+    ...               pd.Period('2018', freq='Y'),
     ...               pd.NaT])
     <PeriodArray>
     ['2017', '2018', 'NaT']
-    Length: 3, dtype: period[A-DEC]
+    Length: 3, dtype: period[Y-DEC]
 
     Integers that look like years are handled
 

pandas/core/dtypes/common.py

@@ -402,7 +402,7 @@ def is_period_dtype(arr_or_dtype) -> bool:
     False
     >>> is_period_dtype(pd.Period("2017-01-01"))
     False
-    >>> is_period_dtype(pd.PeriodIndex([], freq="A"))
+    >>> is_period_dtype(pd.PeriodIndex([], freq="Y"))
     True
     """
     warnings.warn(

pandas/core/frame.py

@@ -12067,7 +12067,7 @@ def to_period(
         For the yearly frequency
 
         >>> idx.to_period("Y")
-        PeriodIndex(['2001', '2002', '2003'], dtype='period[A-DEC]')
+        PeriodIndex(['2001', '2002', '2003'], dtype='period[Y-DEC]')
         """
         new_obj = self.copy(deep=copy and not using_copy_on_write())
 

pandas/core/generic.py

@@ -9172,11 +9172,11 @@ def resample(
                 Use frame.T.resample(...) instead.
         closed : {{'right', 'left'}}, default None
             Which side of bin interval is closed. The default is 'left'
-            for all frequency offsets except for 'ME', 'A', 'Q', 'BM',
+            for all frequency offsets except for 'ME', 'Y', 'Q', 'BM',
             'BA', 'BQ', and 'W' which all have a default of 'right'.
         label : {{'right', 'left'}}, default None
             Which bin edge label to label bucket with. The default is 'left'
-            for all frequency offsets except for 'ME', 'A', 'Q', 'BM',
+            for all frequency offsets except for 'ME', 'Y', 'Q', 'BM',
             'BA', 'BQ', and 'W' which all have a default of 'right'.
         convention : {{'start', 'end', 's', 'e'}}, default 'start'
             For `PeriodIndex` only, controls whether to use the start or
@@ -9347,12 +9347,12 @@ def resample(
         assigned to the first quarter of the period.
 
         >>> s = pd.Series([1, 2], index=pd.period_range('2012-01-01',
-        ...                                             freq='A',
+        ...                                             freq='Y',
         ...                                             periods=2))
         >>> s
         2012    1
         2013    2
-        Freq: A-DEC, dtype: int64
+        Freq: Y-DEC, dtype: int64
         >>> s.resample('Q', convention='start').asfreq()
         2012Q1    1.0
         2012Q2    NaN

pandas/core/resample.py

@@ -2101,7 +2101,7 @@ def __init__(
         else:
             freq = to_offset(freq)
 
-        end_types = {"ME", "A", "Q", "BM", "BA", "BQ", "W"}
+        end_types = {"ME", "Y", "Q", "BM", "BA", "BQ", "W"}
         rule = freq.rule_code
         if rule in end_types or ("-" in rule and rule[: rule.find("-")] in end_types):
             if closed is None: