Meta issue: improve documentation for implementation of the PEP 3118 in Python

[skirpichev]

Documentation

Recent d.p.o discussion thread and SC decision reveal some problems with current docs. Affected parts are the memoryview and struct/array/ctypes modules. I'll list issues in a random order with a hope that people will extend/correct this list:

• The struct module docs has Format Characters section. Though, some type codes now have more than one character. We should rename this section and use some different term. Format Codes? // gh-149402: don't assume single-character type codes (struct/array/ctypes) #149483
• array docs says: The type is specified at object creation time by using a type code, which is a single character. // gh-149402: don't assume single-character type codes (struct/array/ctypes) #149483
• memoryview docs are too vague in their references to the struct module:
  • "format" described as being "in struct module style"
  • it might be not clear that means "single element native format" (C type with native byte size, native endianness, and native alignment)
• ctypes has no documentation for the buffer protocol support at all; though, it's probably most advanced across of the stdlib, see Lib/test/test_ctypes/test_pep3118.py.
• ctypes._SimpleCData._type_ docs says "Class attribute that contains an internal type code, as a single-character string. See Fundamental data types for a summary." // gh-149402: don't assume single-character type codes (struct/array/ctypes) #149483

Linked PRs

• gh-149402: don't assume single-character type codes (struct/array/ctypes) #149483

[skirpichev]

CC @vstinner @encukou

[encukou]

The docs are correct: these modules all “use similar – but slightly different – type codes”.

IMO, this should be the background section for a PEP rather than an issue.

[skirpichev]

The docs are correct: these modules all “use similar – but slightly different – type codes”.

I don't see such item in the above list (an I appreciate if new PEP can address this). This issue is for cases, that could be fixed right now.