Make alt_month_name and alt_month_abbr public in the calendar module.

Expose alternative month names/abbreviations so users can benefit
from alternative forms when they are available. Update documentation and
tests accordingly.

Author: plashchynski

Doc/library/calendar.rst

@@ -493,9 +493,10 @@ 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.  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.
+   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.
+   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)
@@ -505,13 +506,39 @@ The :mod:`calendar` module exports the following data attributes:
 .. data:: month_abbr
 
    A sequence that represents the abbreviated 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_abbr[0]`` is the empty string.
+   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.
 
        >>> import calendar
        >>> list(calendar.month_abbr)
        ['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
 
+
+.. data:: alt_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`.
+
+       >>> import calendar
+       >>> list(calendar.alt_month_name)
+       ['', 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
+
+
+.. data:: alt_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`.
+
+       >>> import calendar
+       >>> list(calendar.alt_month_abbr)
+       ['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+
+
 .. data:: JANUARY
           FEBRUARY
           MARCH

Lib/calendar.py

@@ -14,8 +14,9 @@
 __all__ = ["IllegalMonthError", "IllegalWeekdayError", "setfirstweekday",
            "firstweekday", "isleap", "leapdays", "weekday", "monthrange",
            "monthcalendar", "prmonth", "month", "prcal", "calendar",
-           "timegm", "month_name", "month_abbr", "day_name", "day_abbr",
-           "Calendar", "TextCalendar", "HTMLCalendar", "LocaleTextCalendar",
+           "timegm", "month_name", "month_abbr", "alt_month_name",
+           "alt_month_abbr", "day_name", "day_abbr", "Calendar",
+           "TextCalendar", "HTMLCalendar", "LocaleTextCalendar",
            "LocaleHTMLCalendar", "weekheader",
            "Day", "Month", "JANUARY", "FEBRUARY", "MARCH",
            "APRIL", "MAY", "JUNE", "JULY",
@@ -139,7 +140,7 @@ def __len__(self):
 month_name = _localized_month('%B')
 month_abbr = _localized_month('%b')
 
-# Check if the platform supports the %OB format code
+# Check if the platform supports %OB and %Ob specifiers
 def _is_alt_mon_available():
     try:
         datetime.date(2001, 1, 1).strftime('%OB')
@@ -148,8 +149,9 @@ def _is_alt_mon_available():
         return False
     return True
 
-# In Greek and in many Slavic and Baltic languages, "%OB" will produce
-# the month in nominative case.
+# On platforms that support the %OB and %Ob specifiers, it is used to get the
+# standalone form of the month name. This is required for some languages
+# such as Greek, Slavic, and Baltic languages.
 if _is_alt_mon_available():
     alt_month_name = _localized_month('%OB')
     alt_month_abbr = _localized_month('%Ob')

Lib/test/test_calendar.py

@@ -546,7 +546,8 @@ def test_days(self):
             self.assertEqual(value[::-1], list(reversed(value)))
 
     def test_months(self):
-        for attr in "month_name", "month_abbr":
+        for attr in ["month_name", "month_abbr", "alt_month_name",
+                     "alt_month_abbr"]:
             value = getattr(calendar, attr)
             self.assertEqual(len(value), 13)
             self.assertEqual(len(value[:]), 13)
@@ -556,6 +557,13 @@ 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
+        # to the regular month names and abbreviations for the "C" locale.
+        with calendar.different_locale("C"):
+            self.assertEqual(list(calendar.month_name), list(calendar.alt_month_name))
+            self.assertEqual(list(calendar.month_abbr), list(calendar.alt_month_abbr))
+
     def test_locale_text_calendar(self):
         try:
             cal = calendar.LocaleTextCalendar(locale='')
@@ -1126,8 +1134,7 @@ def test__all__(self):
         not_exported = {
             'mdays', 'January', 'February', 'EPOCH',
             'different_locale', 'c', 'prweek', 'week', 'format',
-            'formatstring', 'main', 'monthlen', 'prevmonth', 'nextmonth',
-            'alt_month_name', 'alt_month_abbr', ""}
+            'formatstring', 'main', 'monthlen', 'prevmonth', 'nextmonth', ""}
         support.check__all__(self, calendar, not_exported=not_exported)