From 728b8159b2234622c565ae849dfe277e8c9b9bdd Mon Sep 17 00:00:00 2001
From: Dmitry Voropaev <144015565+v0ropaev@users.noreply.github.com>
Date: Thu, 1 Oct 2026 21:36:43 +0300
Subject: [PATCH] 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.

(cherry picked from commit ab01d184746b3ea383f69317c16fc726d885c968)
---
 Lib/test/test_array.py                        | 20 +++++++++++++++++++
 ...-09-24-01-20-36.gh-issue-142083.WOlkvr.rst |  3 +++
 Modules/arraymodule.c                         |  1 +
 3 files changed, 24 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 85cecc083f752ea..da78279fb361581 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
@@ -117,6 +118,25 @@ 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):
+                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 505c44d23735b49..d8fef25f829d22e 100644
--- a/Modules/arraymodule.c
+++ b/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\