From c88ae1233493ccff67a6dff5a649472b67a1ab67 Mon Sep 17 00:00:00 2001
From: Victor Stinner <vstinner@python.org>
Date: Mon, 12 Oct 2026 19:20:25 +0200
Subject: [PATCH] [3.15] gh-142083: Document the 'w' type code in the
 array.array docstring (#158040) (#158575)

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 ab01d184746b3ea383f69317c16fc726d885c968)
(cherry picked from commit c5cc92c5b79989e33a35bba6e50de61525e7423c)
---
 Lib/test/test_array.py                        | 22 +++++++++++++++++++
 ...-09-24-01-20-36.gh-issue-142083.WOlkvr.rst |  3 +++
 Modules/arraymodule.c                         |  1 +
 3 files changed, 26 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Documentation/2026-09-24-01-20-36.gh-issue-142083.WOlkvr.rst

diff --git a/Lib/test/test_array.py b/Lib/test/test_array.py
index 8cf669935f923e5..c96c4ce99bbbd66 100755
--- a/Lib/test/test_array.py
+++ b/Lib/test/test_array.py
@@ -12,6 +12,7 @@
 import weakref
 import pickle
 import operator
+import re
 import struct
 import sys
 import warnings
@@ -90,6 +91,27 @@ def test_empty(self):
         a += a
         self.assertEqual(len(a), 0)
 
+    @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.
 #
diff --git a/Misc/NEWS.d/next/Documentation/2026-09-24-01-20-36.gh-issue-142083.WOlkvr.rst b/Misc/NEWS.d/next/Documentation/2026-09-24-01-20-36.gh-issue-142083.WOlkvr.rst
new file mode 100644
index 000000000000000..d8f20396b4556ae
--- /dev/null
+++ b/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.
diff --git a/Modules/arraymodule.c b/Modules/arraymodule.c
index 758a06f0e2b51ca..6328b8074e27c69 100644
--- a/Modules/arraymodule.c
+++ b/Modules/arraymodule.c
@@ -2995,6 +2995,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\