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

[skirpichev]

In the struct docs, section "Format Characters" was renamed to "Type Codes".

• Issue: Meta issue: improve documentation for implementation of the PEP 3118 in Python #149402

[skirpichev]

RTFD failure seems to be not related to the PR.

[vstinner]

"docs/readthedocs.org:cpython-previews" failed with:

Error while cloning the repository: There was a problem cloning your repository. Please check the command output for more information.

Too bad, I like to use it to read rendered documentation :-)

[skirpichev]

Maybe you can restart it?

[vstinner]

In the struct docs, section "Format Characters" was renamed to "Type Codes".

Hum. I wanted to proposing renaming them to "Format Strings", but a "Format String" has already a different meaning in struct, it's the whole string starting with an optional endian character (@, <, >, =, !), followed by format characters with size and alignment. Format Strings: https://docs.python.org/dev/library/struct.html#format-strings.

The term "type code" is already used by the array module: the "type codes" table has a "type column", and there is the array.typecodes tuple. It's good to reuse the term. Doc: https://docs.python.org/dev/library/array.html

memoryview.cast() first parameter is called "format", and it's a format string (format character with an optional "@" prefix). Doc: https://docs.python.org/dev/library/stdtypes.html#memoryview.cast. cast() error message says "native format".

I think that I'm fine with replacing "Format Characters" with "Type Codes" :-)

Can you replace "format characters" with "type codes" in Objects/memoryview.c in comments and in the error:

        PyErr_SetString(PyExc_ValueError,
            "memoryview: destination format must be a native single "
            "character format prefixed with an optional '@'");

[vstinner]

Maybe you can restart it?

I don't see how I can restart a failed RTD job. But it's fine, it will be retried at the next commit anyway.

[skirpichev]

Can you replace "format characters" with "type codes" in Objects/memoryview.c in comments and in the error:

the error message looks different for me:

            "memoryview: destination format must be a native "
            "format prefixed with an optional '@'");

I think it's fine.

I did replacement for comments, though.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32635400 | 📁 Comparing b4d4499 against main (612140e)

  🔍 Preview build  

59 files changed · + 1 added · ± 58 modified

+ Added

• whatsnew/3.16.html

± Modified

• index.html
• c-api/dict.html
• c-api/exceptions.html
• c-api/gcsupport.html
• c-api/interp-lifecycle.html
• c-api/module.html
• c-api/sentinel.html
• c-api/slots.html
• c-api/stable.html
• c-api/threads.html
• and 48 more...

[skirpichev]

CC @vstinner

Documentation now rendered.

[vstinner]

I would prefer to keep "format" in struct. For example, struck.pack() first parameter is called "format" and its documentation calls it "format string": https://docs.python.org/dev/library/struct.html#struct.pack. So I suggest replacing "Format Characters" with "Format Strings".