From 1c66cd3d5a2c28c827d3979083fd76d6df4721dd Mon Sep 17 00:00:00 2001
From: Eoin Shaughnessy <45000144+EoinTrial@users.noreply.github.com>
Date: Thu, 23 Apr 2026 15:50:23 +0100
Subject: [PATCH] gh-148663: Document that `calendar.IllegalMonthError`
 inherits from both `ValueError` and `IndexError` (GH-148664) (cherry picked
 from commit 435be06dd25a5e4e19014340c4ba873d71051c4c)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Eoin Shaughnessy <45000144+EoinTrial@users.noreply.github.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <stan@python.org>
---
 Doc/library/calendar.rst                                   | 7 ++++++-
 Lib/test/test_calendar.py                                  | 5 +++++
 .../2026-04-17-02-28-55.gh-issue-148663.MHIbRB.rst         | 2 ++
 3 files changed, 13 insertions(+), 1 deletion(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2026-04-17-02-28-55.gh-issue-148663.MHIbRB.rst

diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst
index 1a4323134b2ee9..e308e5bfb00906 100644
--- a/Doc/library/calendar.rst
+++ b/Doc/library/calendar.rst
@@ -544,9 +544,14 @@ The :mod:`!calendar` module defines the following exceptions:
 
 .. exception:: IllegalMonthError(month)
 
-   A subclass of :exc:`ValueError`,
+   A subclass of :exc:`ValueError` and :exc:`IndexError`,
    raised when the given month number is outside of the range 1-12 (inclusive).
 
+   .. versionchanged:: 3.12
+      :exc:`IllegalMonthError` is now also a subclass of
+      :exc:`ValueError`. New code should avoid catching
+      :exc:`IndexError`.
+
    .. attribute:: month
 
       The invalid month number.
diff --git a/Lib/test/test_calendar.py b/Lib/test/test_calendar.py
index 7ade4271b7a156..ca93e99d1427dc 100644
--- a/Lib/test/test_calendar.py
+++ b/Lib/test/test_calendar.py
@@ -457,12 +457,17 @@ def test_formatmonth(self):
             calendar.TextCalendar().formatmonth(0, 2),
             result_0_02_text
         )
+
     def test_formatmonth_with_invalid_month(self):
         with self.assertRaises(calendar.IllegalMonthError):
             calendar.TextCalendar().formatmonth(2017, 13)
         with self.assertRaises(calendar.IllegalMonthError):
             calendar.TextCalendar().formatmonth(2017, -1)
 
+    def test_illegal_month_error_bases(self):
+        self.assertIsSubclass(calendar.IllegalMonthError, ValueError)
+        self.assertIsSubclass(calendar.IllegalMonthError, IndexError)
+
     def test_formatmonthname_with_year(self):
         self.assertEqual(
             calendar.HTMLCalendar().formatmonthname(2004, 1, withyear=True),
diff --git a/Misc/NEWS.d/next/Documentation/2026-04-17-02-28-55.gh-issue-148663.MHIbRB.rst b/Misc/NEWS.d/next/Documentation/2026-04-17-02-28-55.gh-issue-148663.MHIbRB.rst
new file mode 100644
index 00000000000000..0fbe5a699ef0ad
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2026-04-17-02-28-55.gh-issue-148663.MHIbRB.rst
@@ -0,0 +1,2 @@
+Document that :class:`calendar.IllegalMonthError` is a subclass of both
+:exc:`ValueError` and :exc:`IndexError` since Python 3.12.