https://github.com/python/cpython/commit/3e5a3cb2bd222f97f793b01bc1c0f7bb62aefc31
commit: 3e5a3cb2bd222f97f793b01bc1c0f7bb62aefc31
branch: main
author: Serhiy Storchaka <[email protected]>
committer: serhiy-storchaka <[email protected]>
date: 2026-04-27T21:30:48+03:00
summary:
gh-148529: Minor improvements of the struct module documentation (GH-148565)
* Document that 's' and 'p' accept bytes and bytearray.
* Fix some footnotes.
* Clarify that "string" is a byte string.
* Fix the module docstring.
files:
M Doc/library/struct.rst
M Modules/_struct.c
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index fa0fb19d852f86..f504f931f0fa20 100644
--- a/Doc/library/struct.rst
+++ b/Doc/library/struct.rst
@@ -227,32 +227,32 @@ platform-dependent.
+--------+--------------------------+--------------------+----------------+------------+
| ``c`` | :c:expr:`char` | bytes of length 1 | 1 |
|
+--------+--------------------------+--------------------+----------------+------------+
-| ``b`` | :c:expr:`signed char` | integer | 1 |
\(1), \(2) |
+| ``b`` | :c:expr:`signed char` | int | 1 |
\(2) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``B`` | :c:expr:`unsigned char` | integer | 1 |
\(2) |
+| ``B`` | :c:expr:`unsigned char` | int | 1 |
\(2) |
+--------+--------------------------+--------------------+----------------+------------+
| ``?`` | :c:expr:`_Bool` | bool | 1 |
\(1) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``h`` | :c:expr:`short` | integer | 2 |
\(2) |
+| ``h`` | :c:expr:`short` | int | 2 |
\(2) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``H`` | :c:expr:`unsigned short` | integer | 2 |
\(2) |
+| ``H`` | :c:expr:`unsigned short` | int | 2 |
\(2) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``i`` | :c:expr:`int` | integer | 4 |
\(2) |
+| ``i`` | :c:expr:`int` | int | 4 |
\(2) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``I`` | :c:expr:`unsigned int` | integer | 4 |
\(2) |
+| ``I`` | :c:expr:`unsigned int` | int | 4 |
\(2) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``l`` | :c:expr:`long` | integer | 4 |
\(2) |
+| ``l`` | :c:expr:`long` | int | 4 |
\(2) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``L`` | :c:expr:`unsigned long` | integer | 4 |
\(2) |
+| ``L`` | :c:expr:`unsigned long` | int | 4 |
\(2) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``q`` | :c:expr:`long long` | integer | 8 |
\(2) |
+| ``q`` | :c:expr:`long long` | int | 8 |
\(2) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``Q`` | :c:expr:`unsigned long | integer | 8 |
\(2) |
+| ``Q`` | :c:expr:`unsigned long | int | 8 |
\(2) |
| | long` | | |
|
+--------+--------------------------+--------------------+----------------+------------+
-| ``n`` | :c:type:`ssize_t` | integer | |
\(3) |
+| ``n`` | :c:type:`ssize_t` | int | |
\(2), \(3) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``N`` | :c:type:`size_t` | integer | |
\(3) |
+| ``N`` | :c:type:`size_t` | int | |
\(2), \(3) |
+--------+--------------------------+--------------------+----------------+------------+
| ``e`` | :c:expr:`_Float16` | float | 2 |
\(4), \(6) |
+--------+--------------------------+--------------------+----------------+------------+
@@ -268,7 +268,7 @@ platform-dependent.
+--------+--------------------------+--------------------+----------------+------------+
| ``p`` | :c:expr:`char[]` | bytes | |
\(8) |
+--------+--------------------------+--------------------+----------------+------------+
-| ``P`` | :c:expr:`void \*` | integer | |
\(5) |
+| ``P`` | :c:expr:`void \*` | int | |
\(2), \(5) |
+--------+--------------------------+--------------------+----------------+------------+
.. versionchanged:: 3.3
@@ -342,27 +342,31 @@ Notes:
The ``'p'`` format character 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 string passed in to
+ 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 string is shorter than
+ ``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
- ``count`` bytes, but that the string returned can never contain more than
255
+ ``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
- bytes, not a repeat count like for the other format characters; for example,
+ byte string, not a repeat count like for the other format characters; 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
to or from ten different Python byte objects. (See :ref:`struct-examples`
for a concrete demonstration of the difference.)
- If a count is not given, it defaults to 1. For packing, the string is
+ If a count is not given, it defaults to 1. For packing, the byte string is
truncated or padded with null bytes as appropriate to make it fit. For
- unpacking, the resulting bytes object always has exactly the specified
number
- of bytes. As a special case, ``'0s'`` means a single, empty string (while
+ unpacking, the resulting :class:`!bytes` object always has exactly the
specified number
+ of bytes. As a special case, ``'0s'`` means a single, empty byte string
(while
``'0c'`` means 0 characters).
+ When packing, arguments of types :class:`bytes` and :class:`bytearray`
+ are accepted.
(10)
For the ``'F'`` and ``'D'`` format characters, the packed representation
uses
diff --git a/Modules/_struct.c b/Modules/_struct.c
index c235e27a415543..47119cb3961e3c 100644
--- a/Modules/_struct.c
+++ b/Modules/_struct.c
@@ -1,7 +1,7 @@
/* struct module -- pack values into and (out of) bytes objects */
/* New version supporting byte order, alignment and size options,
- character strings, and unsigned numbers */
+ byte strings, and unsigned numbers */
#ifndef Py_BUILD_CORE_BUILTIN
# define Py_BUILD_CORE_MODULE 1
@@ -2297,7 +2297,7 @@ Struct_iter_unpack_impl(PyStructObject *self, PyObject
*buffer)
*
* Takes a struct object, a tuple of arguments, and offset in that tuple of
* argument for where to start processing the arguments for packing, and a
- * character buffer for writing the packed string. The caller must insure
+ * character buffer for writing the packed data. The caller must ensure
* that the buffer may contain the required length for packing the arguments.
* 0 is returned on success, 1 is returned if there is an error.
*
@@ -2774,8 +2774,8 @@ static struct PyMethodDef module_functions[] = {
PyDoc_STRVAR(module_doc,
"Functions to convert between Python values and C structs.\n\
-Python bytes objects are used to hold the data representing the C struct\n\
-and also as format strings (explained below) to describe the layout of data\n\
+Python bytes objects are used to hold the data representing the C struct.\n\
+The format string (explained below) describes the layout of data\n\
in the C struct.\n\
\n\
The optional first format char indicates byte order, size and alignment:\n\
@@ -2785,19 +2785,18 @@ The optional first format char indicates byte order,
size and alignment:\n\
>: big-endian, std. size & alignment\n\
!: same as >\n\
\n\
-The remaining chars indicate types of args and must match exactly;\n\
+The remaining characters indicate types of args and must match exactly;\n\
these can be preceded by a decimal repeat count:\n\
- x: pad byte (no data); c:char; b:signed byte; B:unsigned byte;\n\
- ?:_Bool; h:short; H:unsigned short; i:int; I:unsigned int;\n\
- l:long; L:unsigned long; f:float; d:double; e:half-float.\n\
- F:float complex; D:double complex.\n\
+ x: pad byte (no data); c: char; b: signed byte; B: unsigned byte;\n\
+ ?: _Bool; h: short; H: unsigned short; i: int; I: unsigned int;\n\
+ l: long; L: unsigned long; q: long long; Q: unsigned long long;\n\
+ f: float; d: double; e: half-float;\n\
+ F: float complex; D: double complex.\n\
Special cases (preceding decimal count indicates length):\n\
- s:string (array of char); p: pascal string (with count byte).\n\
+ s: byte string (array of char); p: Pascal string (with count byte).\n\
Special cases (only available in native format):\n\
- n:ssize_t; N:size_t;\n\
- P:an integer type that is wide enough to hold a pointer.\n\
-Special case (not in native mode unless 'long long' in platform C):\n\
- q:long long; Q:unsigned long long\n\
+ n: ssize_t; N: size_t;\n\
+ P: an integer type that is wide enough to hold a pointer.\n\
Whitespace between formats is ignored.\n\
\n\
The variable struct.error is an exception raised on errors.\n");
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
