gh-125854: Improve error messages for invalid category in the warnings module

Include the type name if category is a type, but not a Warning
subtype, instead of just 'type'.

Author: serhiy-storchaka

Lib/_py_warnings.py

@@ -251,6 +251,15 @@ def _formatwarnmsg(msg):
     return _wm._formatwarnmsg_impl(msg)
 
 
+def _validate_category(category):
+    if not isinstance(category, type):
+        raise TypeError(f"category must be a Warning subclass, not "
+                        f"'{type(category).__name__}'")
+    if not issubclass(category, Warning):
+        raise TypeError(f"category must be a Warning subclass, not "
+                        f"class '{category.__name__}'")
+
+
 def filterwarnings(action, message="", category=Warning, module="", lineno=0,
                    append=False):
     """Insert an entry into the list of warnings filters (at the front).
@@ -267,8 +276,7 @@ def filterwarnings(action, message="", category=Warning, module="", lineno=0,
         raise ValueError(f"invalid action: {action!r}")
     if not isinstance(message, str):
         raise TypeError("message must be a string")
-    if not isinstance(category, type) or not issubclass(category, Warning):
-        raise TypeError("category must be a Warning subclass")
+    _validate_category(category)
     if not isinstance(module, str):
         raise TypeError("module must be a string")
     if not isinstance(lineno, int):
@@ -449,9 +457,8 @@ def warn(message, category=None, stacklevel=1, source=None,
     # Check category argument
     if category is None:
         category = UserWarning
-    if not (isinstance(category, type) and issubclass(category, Warning)):
-        raise TypeError("category must be a Warning subclass, "
-                        "not '{:s}'".format(type(category).__name__))
+    else:
+        _validate_category(category)
     if not isinstance(skip_file_prefixes, tuple):
         # The C version demands a tuple for implementation performance.
         raise TypeError('skip_file_prefixes must be a tuple of strs.')

Lib/test/test_warnings/__init__.py

@@ -596,25 +596,31 @@ def test_warning_classes(self):
         class MyWarningClass(Warning):
             pass
 
-        class NonWarningSubclass:
-            pass
-
         # passing a non-subclass of Warning should raise a TypeError
-        with self.assertRaises(TypeError) as cm:
+        expected = "category must be a Warning subclass, not 'str'"
+        with self.assertRaisesRegex(TypeError, expected):
             self.module.warn('bad warning category', '')
-        self.assertIn('category must be a Warning subclass, not ',
-                      str(cm.exception))
-
-        with self.assertRaises(TypeError) as cm:
-            self.module.warn('bad warning category', NonWarningSubclass)
-        self.assertIn('category must be a Warning subclass, not ',
-                      str(cm.exception))
+        with self.assertRaisesRegex(TypeError, expected):
+            self.module.simplefilter('always', '')
+        with self.assertRaisesRegex(TypeError, expected):
+            self.module.filterwarnings('always', '', '')
+
+        expected = "category must be a Warning subclass, not class 'int'"
+        with self.assertRaisesRegex(TypeError, expected):
+            self.module.warn('bad warning category', int)
+        with self.assertRaisesRegex(TypeError, expected):
+            self.module.simplefilter('always', int)
+        with self.assertRaisesRegex(TypeError, expected):
+            self.module.filterwarnings('always', '', int)
 
         # check that warning instances also raise a TypeError
-        with self.assertRaises(TypeError) as cm:
+        expected = "category must be a Warning subclass, not '.*MyWarningClass'"
+        with self.assertRaisesRegex(TypeError, expected):
             self.module.warn('bad warning category', MyWarningClass())
-        self.assertIn('category must be a Warning subclass, not ',
-                      str(cm.exception))
+        with self.assertRaisesRegex(TypeError, expected):
+            self.module.simplefilter('always', MyWarningClass())
+        with self.assertRaisesRegex(TypeError, expected):
+            self.module.filterwarnings('always', '', MyWarningClass())
 
         with self.module.catch_warnings():
             self.module.resetwarnings()

Misc/NEWS.d/next/Library/2025-08-14-10-27-07.gh-issue-125854.vDzFcZ.rst

@@ -0,0 +1 @@
+Improve error messages for invalid category in the :mod:`warnings` module.

Python/_warnings.c

@@ -823,11 +823,7 @@ warn_explicit(PyThreadState *tstate, PyObject *category, PyObject *message,
 
     /* Normalize message. */
     Py_INCREF(message);  /* DECREF'ed in cleanup. */
-    rc = PyObject_IsInstance(message, PyExc_Warning);
-    if (rc == -1) {
-        goto cleanup;
-    }
-    if (rc == 1) {
+    if (PyObject_TypeCheck(message, (PyTypeObject *)PyExc_Warning)) {
         text = PyObject_Str(message);
         if (text == NULL)
             goto cleanup;
@@ -1124,26 +1120,25 @@ setup_context(Py_ssize_t stack_level,
 static PyObject *
 get_category(PyObject *message, PyObject *category)
 {
-    int rc;
-
-    /* Get category. */
-    rc = PyObject_IsInstance(message, PyExc_Warning);
-    if (rc == -1)
-        return NULL;
-
-    if (rc == 1)
-        category = (PyObject*)Py_TYPE(message);
-    else if (category == NULL || category == Py_None)
-        category = PyExc_UserWarning;
+    if (PyObject_TypeCheck(message, (PyTypeObject *)PyExc_Warning)) {
+        /* Ignore the category argument. */
+        return (PyObject*)Py_TYPE(message);
+    }
+    if (category == NULL || category == Py_None) {
+        return PyExc_UserWarning;
+    }
 
     /* Validate category. */
-    rc = PyObject_IsSubclass(category, PyExc_Warning);
-    /* category is not a subclass of PyExc_Warning or
-       PyObject_IsSubclass raised an error */
-    if (rc == -1 || rc == 0) {
+    if (!PyType_Check(category)) {
+        PyErr_Format(PyExc_TypeError,
+                     "category must be a Warning subclass, not '%T'",
+                     category);
+        return NULL;
+    }
+    if (!PyType_IsSubtype((PyTypeObject *)category, (PyTypeObject *)PyExc_Warning)) {
         PyErr_Format(PyExc_TypeError,
-                     "category must be a Warning subclass, not '%s'",
-                     Py_TYPE(category)->tp_name);
+                     "category must be a Warning subclass, not class '%N'",
+                     (PyTypeObject *)category);
         return NULL;
     }