Rename calendar.alt_month_name to calendar.standalone_month_name, and calendar.alt_month_abbr to calendar.standalone_month_abbr.

Author: plashchynski

Doc/library/calendar.rst

@@ -493,51 +493,63 @@ The :mod:`calendar` module exports the following data attributes:
 
 .. data:: month_name
 
-   A sequence that represents the months of the year in the current locale
-   in the grammatical form used when the month is part of a complete date.
+   A sequence that represents the months of the year in the current locale.
    This follows normal convention of January being month number 1, so it has
    a length of 13 and ``month_name[0]`` is the empty string.
 
        >>> import calendar
        >>> list(calendar.month_name)
        ['', 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
 
+   .. caution::
+
+      In locales with alternative forms of month names, the :data:`month_name` sequence
+      may not be suitable when a month name stands by itself and not as part of a date.
+      For instance, in Greek and in many Slavic and Baltic languages, :data:`month_name`
+      will produce the month in genitive case. Use :data:`standalone_month_name` for a form
+      suitable for standalone use.
+
 
 .. data:: month_abbr
 
    A sequence that represents the abbreviated months of the year in the current
-   locale in the grammatical form used when the month is part of a complete date.
-   This follows normal convention of January being month number 1, so it has
-   a length of 13 and  ``month_abbr[0]`` is the empty string.
+   locale. This follows normal convention of January being month number 1, so
+   it has a length of 13 and  ``month_abbr[0]`` is the empty string.
 
        >>> import calendar
        >>> list(calendar.month_abbr)
        ['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
 
+   .. caution::
+
+      In locales with alternative forms of month names, the :data:`month_abbr` sequence
+      may not be suitable when a month name stands by itself and not as part of a date.
+      Use :data:`standalone_month_abbr` for a form suitable for standalone use.
+
 
-.. data:: alt_month_name
+.. data:: standalone_month_name
 
    A sequence that represents the months of the year in the current locale
-   in the grammatical form used when the month is named by itself if the locale
-   provides one. If the locale does not supply an alternative form, it falls back
-   to the behavior of :data:`month_name`.
+   in the grammatical form used when a month name stands by itself if the locale
+   provides one. If the locale does not supply an alternative form, it is equal to
+   :data:`month_name`.
 
        >>> import calendar
-       >>> list(calendar.alt_month_name)
+       >>> list(calendar.standalone_month_name)
        ['', 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
 
    .. versionadded:: next
 
 
-.. data:: alt_month_abbr
+.. data:: standalone_month_abbr
 
    A sequence that represents the abbreviated months of the year in the current
-   locale in the grammatical form used when the month is named by itself if the
-   locale provides one. If the locale does not supply an alternative form, it falls
-   back to the behavior of :data:`month_abbr`.
+   locale in the grammatical form used when a month name stands by itself if the
+   locale provides one. If the locale does not supply an alternative form, it is equal to
+   :data:`month_abbr`.
 
        >>> import calendar
-       >>> list(calendar.alt_month_abbr)
+       >>> list(calendar.standalone_month_abbr)
        ['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
 
    .. versionadded:: next

Lib/calendar.py

@@ -14,8 +14,8 @@
 __all__ = ["IllegalMonthError", "IllegalWeekdayError", "setfirstweekday",
            "firstweekday", "isleap", "leapdays", "weekday", "monthrange",
            "monthcalendar", "prmonth", "month", "prcal", "calendar",
-           "timegm", "month_name", "month_abbr", "alt_month_name",
-           "alt_month_abbr", "day_name", "day_abbr", "Calendar",
+           "timegm", "month_name", "month_abbr", "standalone_month_name",
+           "standalone_month_abbr", "day_name", "day_abbr", "Calendar",
            "TextCalendar", "HTMLCalendar", "LocaleTextCalendar",
            "LocaleHTMLCalendar", "weekheader",
            "Day", "Month", "JANUARY", "FEBRUARY", "MARCH",
@@ -144,12 +144,12 @@ def __len__(self):
 # standalone form of the month name. This is required for some languages
 # such as Greek, Slavic, and Baltic languages.
 try:
-    alt_month_name = _localized_month('%OB')
-    alt_month_abbr = _localized_month('%Ob')
+    standalone_month_name = _localized_month('%OB')
+    standalone_month_abbr = _localized_month('%Ob')
 except ValueError:
     # The platform does not support the %OB and %Ob specifiers.
-    alt_month_name = month_name
-    alt_month_abbr = month_abbr
+    standalone_month_name = month_name
+    standalone_month_abbr = month_abbr
 
 
 def isleap(year):
@@ -389,7 +389,7 @@ def formatmonthname(self, theyear, themonth, width, withyear=True):
         """
         _validate_month(themonth)
 
-        s = alt_month_name[themonth]
+        s = standalone_month_name[themonth]
         if withyear:
             s = "%s %r" % (s, theyear)
         return s.center(width)
@@ -522,9 +522,9 @@ def formatmonthname(self, theyear, themonth, withyear=True):
         """
         _validate_month(themonth)
         if withyear:
-            s = '%s %s' % (alt_month_name[themonth], theyear)
+            s = '%s %s' % (standalone_month_name[themonth], theyear)
         else:
-            s = alt_month_name[themonth]
+            s = standalone_month_name[themonth]
         return '<tr><th colspan="7" class="%s">%s</th></tr>' % (
             self.cssclass_month_head, s)
 

Lib/test/test_calendar.py

@@ -546,8 +546,8 @@ def test_days(self):
             self.assertEqual(value[::-1], list(reversed(value)))
 
     def test_months(self):
-        for attr in ("month_name", "month_abbr", "alt_month_name",
-                     "alt_month_abbr"):
+        for attr in ("month_name", "month_abbr", "standalone_month_name",
+                     "standalone_month_abbr"):
             value = getattr(calendar, attr)
             self.assertEqual(len(value), 13)
             self.assertEqual(len(value[:]), 13)
@@ -557,12 +557,12 @@ def test_months(self):
             # verify it "acts like a sequence" in two forms of iteration
             self.assertEqual(value[::-1], list(reversed(value)))
 
-    def test_alt_month_name_and_abbr(self):
-        # Ensure that the alternate month names and abbreviations are equal
+    def test_standalone_month_name_and_abbr(self):
+        # Ensure that the standalone month names and abbreviations are equal
         # to the regular month names and abbreviations for the "C" locale.
         with calendar.different_locale("C"):
-            self.assertListEqual(list(calendar.month_name), list(calendar.alt_month_name))
-            self.assertListEqual(list(calendar.month_abbr), list(calendar.alt_month_abbr))
+            self.assertListEqual(list(calendar.month_name), list(calendar.standalone_month_name))
+            self.assertListEqual(list(calendar.month_abbr), list(calendar.standalone_month_abbr))
 
     def test_locale_text_calendar(self):
         try:

Misc/NEWS.d/next/Library/2025-03-17-21-15-04.gh-issue-131146.P9Cdx0.rst

@@ -1,4 +1,4 @@
-Add :func:`calendar.alt_month_name` and :func:`calendar.alt_month_abbr` to
+Add :func:`calendar.standalone_month_name` and :func:`calendar.standalone_month_abbr` to
 provide alternative month names and abbreviations for the current locale
 when available. These are used when the month is named by itself, such as in
 a standalone date.