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

Doc/library/array.rst

@@ -12,7 +12,7 @@ This module defines an object type which can compactly represent an array of
 basic values: characters, integers, floating-point numbers, complex numbers.  Arrays are mutable :term:`sequence`
 types and behave very much like lists, except that the type of objects stored in
 them is constrained.  The type is specified at object creation time by using a
-:dfn:`type code`, which is a single character.  The following type codes are
+:dfn:`type code`.  The following type codes are
 defined:
 
 +-----------+--------------------+-------------------+-----------------------+-------+
@@ -91,7 +91,7 @@ Notes:
 .. seealso::
 
    The :ref:`ctypes <ctypes-fundamental-data-types>` and
-   :ref:`struct <format-characters>` modules,
+   :ref:`struct <type-codes>` modules,
    as well as third-party modules like `numpy <https://numpy.org/doc/stable/reference/arrays.interface.html#object.__array_interface__>`__,
    use similar -- but slightly different -- type codes.
 

Doc/library/ctypes.rst

@@ -2572,8 +2572,7 @@ Fundamental data types
 
    .. attribute:: _type_
 
-      Class attribute that contains an internal type code, as a
-      single-character string.
+      Class attribute that contains an internal type code.
       See :ref:`ctypes-fundamental-data-types` for a summary.
 
       Types marked \* in the summary may be (or always are) aliases of a
@@ -2587,7 +2586,7 @@ Fundamental data types
 
       .. seealso::
 
-         The :mod:`array` and :ref:`struct <format-characters>` modules,
+         The :mod:`array` and :ref:`struct <type-codes>` modules,
          as well as third-party modules like `numpy <https://numpy.org/doc/stable/reference/arrays.interface.html#object.__array_interface__>`__,
          use similar -- but slightly different -- type codes.
 

Doc/library/struct.rst

@@ -111,7 +111,7 @@ Format Strings
 --------------
 
 Format strings describe the data layout when
-packing and unpacking data.  They are built up from :ref:`format characters<format-characters>`,
+packing and unpacking data.  They are built up from :ref:`type codes<type-codes>`,
 which specify the type of data being packed/unpacked.  In addition,
 special characters control the :ref:`byte order, size and alignment<struct-alignment>`.
 Each format string consists of an optional prefix character which
@@ -183,8 +183,8 @@ Use :data:`sys.byteorder` to check the endianness of your system.
 Native size and alignment are determined using the C compiler's
 ``sizeof`` expression.  This is always combined with native byte order.
 
-Standard size depends only on the format character;  see the table in
-the :ref:`format-characters` section.
+Standard size depends only on the type code;  see the table in
+the :ref:`type-codes` section.
 
 Note the difference between ``'@'`` and ``'='``: both use native byte order, but
 the size and alignment of the latter is standardized.
@@ -208,12 +208,13 @@ Notes:
     count of zero.  See :ref:`struct-examples`.
 
 
+.. _type-codes:
 .. _format-characters:
 
-Format Characters
-^^^^^^^^^^^^^^^^^
+Type Codes
+^^^^^^^^^^
 
-Format characters have the following meaning; the conversion between C and
+Type codes (or format codes) have the following meaning; the conversion between C and
 Python values should be obvious given their types.  The 'Standard size' column
 refers to the size of the packed value in bytes when using standard size; that
 is, when the format string starts with one of ``'<'``, ``'>'``, ``'!'`` or
@@ -324,7 +325,7 @@ Notes:
    format used by the platform.
 
 (5)
-   The ``'P'`` format character is only available for the native byte ordering
+   The ``'P'`` type code is only available for the native byte ordering
    (selected as the default or with the ``'@'`` byte order character). The byte
    order character ``'='`` chooses to use little- or big-endian ordering based
    on the host system. The struct module does not interpret this as native
@@ -346,22 +347,22 @@ Notes:
    When packing, ``'x'`` inserts one NUL byte.
 
 (8)
-   The ``'p'`` format character encodes a "Pascal string", meaning a short
+   The ``'p'`` type code encodes a "Pascal string", meaning a short
    variable-length string stored in a *fixed number of bytes*, given by the count.
    The first byte stored is the length of the string, or 255, whichever is
    smaller.  The bytes of the string follow.  If the byte string passed in to
    :func:`pack` is too long (longer than the count minus 1), only the leading
    ``count-1`` bytes of the string are stored.  If the byte string is shorter than
    ``count-1``, it is padded with null bytes so that exactly count bytes in all
-   are used.  Note that for :func:`unpack`, the ``'p'`` format character consumes
+   are used.  Note that for :func:`unpack`, the ``'p'`` type code consumes
    ``count`` bytes, but that the :class:`!bytes` object returned can never contain more than 255
    bytes.
    When packing, arguments of types :class:`bytes` and :class:`bytearray`
    are accepted.
 
 (9)
-   For the ``'s'`` format character, the count is interpreted as the length of the
-   byte string, not a repeat count like for the other format characters; for example,
+   For the ``'s'`` type code, the count is interpreted as the length of the
+   byte string, not a repeat count like for the other type codes; for example,
    ``'10s'`` means a single 10-byte string mapping to or from a single
    Python byte string, while ``'10c'`` means 10
    separate one byte character elements (e.g., ``cccccccccc``) mapping
@@ -376,7 +377,7 @@ Notes:
    are accepted.
 
 (10)
-   For the ``'F'`` and ``'D'`` format characters, the packed representation uses
+   For the ``'F'`` and ``'D'`` type codes, the packed representation uses
    the IEEE 754 binary32 and binary64 format for components of the complex
    number, regardless of the floating-point format used by the platform.
    Note that complex types (``F``/``Zf`` and ``D``/``Zd``) are available unconditionally,
@@ -385,7 +386,7 @@ Notes:
    two-element C array containing, respectively, the real and imaginary parts.
 
 
-A format character may be preceded by an integral repeat count.  For example,
+A type code may be preceded by an integral repeat count.  For example,
 the format string ``'4h'`` means exactly the same as ``'hhhh'``.
 
 Whitespace characters between formats are ignored; a count and its format must
@@ -402,7 +403,7 @@ then :exc:`struct.error` is raised.
 
 .. index:: single: ? (question mark); in struct format strings
 
-For the ``'?'`` format character, the return value is either :const:`True` or
+For the ``'?'`` type code, the return value is either :const:`True` or
 :const:`False`. When packing, the truth value of the argument object is used.
 Either 0 or 1 in the native or standard bool representation will be packed, and
 any non-zero value will be ``True`` when unpacking.
@@ -457,7 +458,7 @@ the result in a named tuple::
     >>> Student._make(unpack('<10sHHb', record))
     Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)
 
-The ordering of format characters may have an impact on size in native
+The ordering of type codes may have an impact on size in native
 mode since padding is implicit. In standard mode, the user is
 responsible for inserting any desired padding.
 Note in
@@ -515,7 +516,7 @@ When constructing format strings which mimic native layouts, the
 compiler and machine architecture determine byte ordering and padding.
 In such cases, the ``@`` format character should be used to specify
 native byte ordering and data sizes.  Internal pad bytes are normally inserted
-automatically.  It is possible that a zero-repeat format code will be
+automatically.  It is possible that a zero-repeat type code will be
 needed at the end of a format string to round up to the correct
 byte boundary for proper alignment of consecutive chunks of data.
 
@@ -534,7 +535,7 @@ code solves that problem::
     >>> calcsize('@llh0l')
     24
 
-The ``'x'`` format code can be used to specify the repeat, but for
+The ``'x'`` type code can be used to specify the repeat, but for
 native formats it is better to use a zero-repeat format like ``'0l'``.
 
 By default, native byte ordering and alignment is used, but it is

Objects/memoryobject.c

@@ -1806,7 +1806,7 @@ pylong_as_zu(PyObject *item)
         dest = x;                          \
     } while (0)
 
-/* Unpack a single item. 'fmt' can be any native format character in struct
+/* Unpack a single item. 'fmt' can be any native format in struct
    module syntax. This function is very sensitive to small changes. With this
    layout gcc automatically generates a fast jump table. */
 static inline PyObject *
@@ -1926,7 +1926,7 @@ unpack_single(PyMemoryViewObject *self, const char *ptr, const char *fmt)
         memcpy(ptr, (char *)&x, sizeof x);   \
     } while (0)
 
-/* Pack a single item. 'fmt' can be any native format character in
+/* Pack a single item. 'fmt' can be any native format in
    struct module syntax. */
 static int
 pack_single(PyMemoryViewObject *self, char *ptr, PyObject *item, const char *fmt)