Skip to content

Commit 21bbdc1

Browse files
methaneskirpichevvstinner
authored
gh-149402: Don't assume single-character type codes (struct/array/ctypes) (GH-149483)
In the struct docs, section "Format Characters" was renamed to "Type Codes". (cherry picked from commit ef87731) Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com> Co-authored-by: Victor Stinner <vstinner@python.org>
1 parent d01fec5 commit 21bbdc1

4 files changed

Lines changed: 23 additions & 23 deletions

File tree

‎Doc/library/array.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ This module defines an object type which can compactly represent an array of
1212
basic values: characters, integers, floating-point numbers, complex numbers. Arrays are mutable :term:`sequence`
1313
types and behave very much like lists, except that the type of objects stored in
1414
them is constrained. The type is specified at object creation time by using a
15-
:dfn:`type code`, which is a single character. The following type codes are
15+
:dfn:`type code`. The following type codes are
1616
defined:
1717

1818
+-----------+--------------------+-------------------+-----------------------+-------+
@@ -91,7 +91,7 @@ Notes:
9191
.. seealso::
9292

9393
The :ref:`ctypes <ctypes-fundamental-data-types>` and
94-
:ref:`struct <format-characters>` modules,
94+
:ref:`struct <type-codes>` modules,
9595
as well as third-party modules like `numpy <https://numpy.org/doc/stable/reference/arrays.interface.html#object.__array_interface__>`__,
9696
use similar -- but slightly different -- type codes.
9797

‎Doc/library/ctypes.rst‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2623,8 +2623,7 @@ Fundamental data types
26232623

26242624
.. attribute:: _type_
26252625

2626-
Class attribute that contains an internal type code, as a
2627-
single-character string.
2626+
Class attribute that contains an internal type code, as a string.
26282627
See :ref:`ctypes-fundamental-data-types` for a summary.
26292628

26302629
Types marked \* in the summary may be (or always are) aliases of a
@@ -2638,7 +2637,7 @@ Fundamental data types
26382637

26392638
.. seealso::
26402639

2641-
The :mod:`array` and :ref:`struct <format-characters>` modules,
2640+
The :mod:`array` and :ref:`struct <type-codes>` modules,
26422641
as well as third-party modules like `numpy <https://numpy.org/doc/stable/reference/arrays.interface.html#object.__array_interface__>`__,
26432642
use similar -- but slightly different -- type codes.
26442643

‎Doc/library/struct.rst‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ Format Strings
113113
--------------
114114

115115
Format strings describe the data layout when
116-
packing and unpacking data. They are built up from :ref:`format characters<format-characters>`,
116+
packing and unpacking data. They are built up from :ref:`type codes <type-codes>`,
117117
which specify the type of data being packed/unpacked. In addition,
118118
special characters control the :ref:`byte order, size and alignment<struct-alignment>`.
119119
Each format string consists of an optional prefix character which
@@ -185,8 +185,8 @@ Use :data:`sys.byteorder` to check the endianness of your system.
185185
Native size and alignment are determined using the C compiler's
186186
``sizeof`` expression. This is always combined with native byte order.
187187

188-
Standard size depends only on the format character; see the table in
189-
the :ref:`format-characters` section.
188+
Standard size depends only on the type code; see the table in
189+
the :ref:`type-codes` section.
190190

191191
Note the difference between ``'@'`` and ``'='``: both use native byte order, but
192192
the size and alignment of the latter is standardized.
@@ -210,12 +210,13 @@ Notes:
210210
count of zero. See :ref:`struct-examples`.
211211

212212

213+
.. _type-codes:
213214
.. _format-characters:
214215

215-
Format Characters
216-
^^^^^^^^^^^^^^^^^
216+
Type Codes
217+
^^^^^^^^^^
217218

218-
Format characters have the following meaning; the conversion between C and
219+
Type codes (or format codes) have the following meaning; the conversion between C and
219220
Python values should be obvious given their types. The 'Standard size' column
220221
refers to the size of the packed value in bytes when using standard size; that
221222
is, when the format string starts with one of ``'<'``, ``'>'``, ``'!'`` or
@@ -323,7 +324,7 @@ Notes:
323324
format used by the platform.
324325

325326
(5)
326-
The ``'P'`` format character is only available for the native byte ordering
327+
The ``'P'`` type code is only available for the native byte ordering
327328
(selected as the default or with the ``'@'`` byte order character). The byte
328329
order character ``'='`` chooses to use little- or big-endian ordering based
329330
on the host system. The struct module does not interpret this as native
@@ -345,22 +346,22 @@ Notes:
345346
When packing, ``'x'`` inserts one NUL byte.
346347

347348
(8)
348-
The ``'p'`` format character encodes a "Pascal string", meaning a short
349+
The ``'p'`` type code encodes a "Pascal string", meaning a short
349350
variable-length string stored in a *fixed number of bytes*, given by the count.
350351
The first byte stored is the length of the string, or 255, whichever is
351352
smaller. The bytes of the string follow. If the byte string passed in to
352353
:func:`pack` is too long (longer than the count minus 1), only the leading
353354
``count-1`` bytes of the string are stored. If the byte string is shorter than
354355
``count-1``, it is padded with null bytes so that exactly count bytes in all
355-
are used. Note that for :func:`unpack`, the ``'p'`` format character consumes
356+
are used. Note that for :func:`unpack`, the ``'p'`` type code consumes
356357
``count`` bytes, but that the :class:`!bytes` object returned can never contain more than 255
357358
bytes.
358359
When packing, arguments of types :class:`bytes` and :class:`bytearray`
359360
are accepted.
360361

361362
(9)
362-
For the ``'s'`` format character, the count is interpreted as the length of the
363-
byte string, not a repeat count like for the other format characters; for example,
363+
For the ``'s'`` type code, the count is interpreted as the length of the
364+
byte string, not a repeat count like for the other type codes; for example,
364365
``'10s'`` means a single 10-byte string mapping to or from a single
365366
Python byte string, while ``'10c'`` means 10
366367
separate one byte character elements (e.g., ``cccccccccc``) mapping
@@ -386,7 +387,7 @@ Notes:
386387
characters are supported for compatibility.
387388

388389

389-
A format character may be preceded by an integral repeat count. For example,
390+
A type code may be preceded by an integral repeat count. For example,
390391
the format string ``'4h'`` means exactly the same as ``'hhhh'``.
391392

392393
Whitespace characters between formats are ignored; a count and its format must
@@ -403,7 +404,7 @@ then :exc:`struct.error` is raised.
403404

404405
.. index:: single: ? (question mark); in struct format strings
405406

406-
For the ``'?'`` format character, the return value is either :const:`True` or
407+
For the ``'?'`` type code, the return value is either :const:`True` or
407408
:const:`False`. When packing, the truth value of the argument object is used.
408409
Either 0 or 1 in the native or standard bool representation will be packed, and
409410
any non-zero value will be ``True`` when unpacking.
@@ -458,7 +459,7 @@ the result in a named tuple::
458459
>>> Student._make(unpack('<10sHHb', record))
459460
Student(name=b'raymond ', serialnum=4658, school=264, gradelevel=8)
460461

461-
The ordering of format characters may have an impact on size in native
462+
The ordering of type codes may have an impact on size in native
462463
mode since padding is implicit. In standard mode, the user is
463464
responsible for inserting any desired padding.
464465
Note in
@@ -516,7 +517,7 @@ When constructing format strings which mimic native layouts, the
516517
compiler and machine architecture determine byte ordering and padding.
517518
In such cases, the ``@`` format character should be used to specify
518519
native byte ordering and data sizes. Internal pad bytes are normally inserted
519-
automatically. It is possible that a zero-repeat format code will be
520+
automatically. It is possible that a zero-repeat type code will be
520521
needed at the end of a format string to round up to the correct
521522
byte boundary for proper alignment of consecutive chunks of data.
522523

@@ -535,7 +536,7 @@ code solves that problem::
535536
>>> calcsize('@llh0l')
536537
24
537538

538-
The ``'x'`` format code can be used to specify the repeat, but for
539+
The ``'x'`` type code can be used to specify the repeat, but for
539540
native formats it is better to use a zero-repeat format like ``'0l'``.
540541

541542
By default, native byte ordering and alignment is used, but it is

‎Objects/memoryobject.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1798,7 +1798,7 @@ pylong_as_zu(PyObject *item)
17981798
dest = x; \
17991799
} while (0)
18001800

1801-
/* Unpack a single item. 'fmt' can be any native format character in struct
1801+
/* Unpack a single item. 'fmt' can be any native format in struct
18021802
module syntax. This function is very sensitive to small changes. With this
18031803
layout gcc automatically generates a fast jump table. */
18041804
static inline PyObject *
@@ -1918,7 +1918,7 @@ unpack_single(PyMemoryViewObject *self, const char *ptr, const char *fmt)
19181918
memcpy(ptr, (char *)&x, sizeof x); \
19191919
} while (0)
19201920

1921-
/* Pack a single item. 'fmt' can be any native format character in
1921+
/* Pack a single item. 'fmt' can be any native format in
19221922
struct module syntax. */
19231923
static int
19241924
pack_single(PyMemoryViewObject *self, char *ptr, PyObject *item, const char *fmt)

0 commit comments

Comments
 (0)