gh-142083: Document the 'w' type code in the array.array docstring (#158040)

Add a test asserting that the table lists exactly the supported type
codes and that the minimum size it gives for each of them is one the
implementation really meets.

Co-authored-by: Dmitry Voropaev <dy.voropaev@gmail.com>

(cherry picked from commit ab01d18)

Author: vstinner

Lib/test/test_array.py

@@ -12,6 +12,7 @@
 import weakref
 import pickle
 import operator
+import re
 import struct
 import sys
 import warnings
@@ -117,6 +118,27 @@ def test_typecodes(self):
             self.assertIsInstance(typecode, str)
             self.assertGreaterEqual(len(typecode), 1)
 
+    @support.cpython_only
+    @support.requires_docstrings
+    def test_typecodes_documented(self):
+        # The type code table in the array.array docstring must list every
+        # supported type code, and nothing else, and the minimum size it
+        # gives for each of them must be one the implementation meets.
+        row = re.compile(r"^ {4}'(\w+)' +\S.*? +(\d+)(?: \(see note\))?$")
+        documented = {}
+        for line in array.array.__doc__.splitlines():
+            match = row.match(line)
+            if match is not None:
+                documented[match.group(1)] = int(match.group(2))
+
+        self.assertEqual(sorted(documented), sorted(array.typecodes))
+        for typecode, minimum_size in documented.items():
+            with self.subTest(typecode=typecode):
+                with warnings.catch_warnings():
+                    warnings.simplefilter('ignore', DeprecationWarning)
+                    self.assertGreaterEqual(array.array(typecode).itemsize,
+                                            minimum_size)
+
 
 # Machine format codes.
 #

Misc/NEWS.d/next/Documentation/2026-09-24-01-20-36.gh-issue-142083.WOlkvr.rst

@@ -0,0 +1,3 @@
+Document the ``'w'`` type code in the :class:`array.array` docstring, so
+that it lists the same type codes as :data:`array.typecodes` and the
+:mod:`array` module documentation.

Modules/arraymodule.c

@@ -3200,6 +3200,7 @@ The following type codes are defined:\n\
     'b'         signed integer     1\n\
     'B'         unsigned integer   1\n\
     'u'         Unicode character  2 (see note)\n\
+    'w'         Py_UCS4            4\n\
     'h'         signed integer     2\n\
     'H'         unsigned integer   2\n\
     'i'         signed integer     2\n\