gh-142083: Document the 'w' type code in the array.array docstring

[v0ropaev]

The type-code table in array.array.__doc__ is missing 'w':

>>> import array
>>> set(array.typecodes) - {l.split()[0].strip("'") for l in array.array.__doc__.splitlines() if l.startswith("    '")}
{'w'}

help(array.array) therefore lists fifteen type codes where the module supports sixteen, and 'w' is the one a reader is most likely to be looking for, since it replaced the removed 'u'.

The issue also mentioned the narrow/wide-build note. That half is already done: 46b5e3e ("gh-80480: Remove deprecated 'u' array type code") deleted both the 'u' row and the note along with it. 'w' is what is left.

Change

One line in the docstring, placed after 'B' so the order matches descriptors[] and the table in Doc/library/array.rst. The C Type column says Py_UCS4, which is what the rst table's C-type column says for this row — if you would rather it read Unicode character (the rst's Python type column) or something looser like the neighbouring signed integer rows, say so and I will change it; that is the only judgment call in the diff.

The previous attempt at this, #142323, was closed after @vstinner wrote "Your PR doesn't build successfully. Your change is not correct." That diff spliced "...\n" quoted lines into the middle of the backslash-continued PyDoc_STRVAR literal, which cannot compile. This one keeps the \n\ continuation that every other row uses, and builds:

make -j8  →  exit 0
Checked 116 modules (37 built-in, 77 shared, 0 n/a, 0 disabled, 2 missing, 0 failed on import)

Test

Rather than assert the one new row, test_typecodes_documented parses the whole table out of the docstring and asserts two things: that it lists exactly array.typecodes, and that each documented minimum size is one the implementation actually meets. So the next type code added or removed cannot silently desync the docstring again, which is how 'w' came to be missing in the first place.

It is guarded with @support.cpython_only and @support.requires_docstrings, so it skips under -OO and on implementations without docstrings:

./python.exe -m test test_array        →  run=1,039  SUCCESS
./python.exe -OO -m test test_array    →  run=1,039  skipped=1  SUCCESS

Delete-the-fix check, run by removing the added line and rebuilding:

AssertionError: Items in the second set but not the first: "'w'"
run=1,039  failures=1  FAILURE

array.typecodes is built unconditionally from descriptors[] at module init, so the set comparison does not depend on the platform having long long.

News entry in Misc/NEWS.d/next/Documentation/ — the docstring is user-visible through help().

• Issue: Docstring of array.array misses 'w' type info and mentions wide/narrow builds #142083

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[v0ropaev]

Applied, thanks. The group holds the bare type code now and the blank line before the assert is there too.

One thing worth mentioning, I could not run the test against a fresh build here, the build of this checkout stopped on a missing libatomic unrelated to the patch. I did run it against the stale binary and the regex picked up all fifteen rows of the old table, including Zd and Zf, so the rewrite parses the same thing the previous one did. CI will have a real build.

[vstinner]

There is an unrelated failure on GHA Windows:

FAIL: test_tlbc_cache_refresh_after_growth (test.test_external_inspection.TestGetStackTrace.test_tlbc_cache_refresh_after_growth)
...
stderr: OSError: [WinError 299] Only part of a ReadProcessMemory or WriteProcessMemory request was completed
...

I created #158574 to track this test_external_inspection failure.

[vstinner]

LGTM.

@v0ropaev: It seems like you used a LLM to create this PR and writes its description. LLM are too verbose. Next time, try at least to write the PR description with your own words. There is no need to elaborate that much just to add "w" to a docstring.

[miss-islington-app]

Thanks @v0ropaev for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14, 3.15.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @v0ropaev and @vstinner, I could not cleanly backport this to 3.15 due to a conflict.

Please backport manually with cherry_picker, see the devguide for more information.

cherry_picker ab01d184746b3ea383f69317c16fc726d885c968 3.15

[miss-islington-app]

Sorry, @v0ropaev and @vstinner, I could not cleanly backport this to 3.14 due to a conflict.

Please backport manually with cherry_picker, see the devguide for more information.

cherry_picker ab01d184746b3ea383f69317c16fc726d885c968 3.14

[bedevere-app]

GH-158575 is a backport of this pull request to the 3.15 branch.

[webknjaz]

I'd like to join Victor as I share his sentiment in that too many tokens to consume make for a lot of cognitive burden for the reviewers of which there are too few.
Please, check out https://dontquotetheai.com and make an effort to communicate with other people efficiently without creating the overhead of them having to figure out which parts of a long snippet of text are significant or relevant.
CPython's policy spells out more details at https://devguide.python.org/getting-started/ai-tools/.

[vstinner]

Merged, thanks for your fix.

@v0ropaev: Please sign the Python contributor agreement with your other email address: see my backport to 3.15 for details, PR gh-158575.