PublicArchive/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-05-06 04:37:33 -04:00
Code Issues Packages Projects Releases Wiki Activity

[3.14] gh-148529: Minor improvements of the struct module documentation (GH-148565) (GH-149063)

Browse Source 
* Document that 's' and 'p' accept bytes and bytearray.
* Fix some footnotes.
* Clarify that "string" is a byte string.
* Fix the module docstring.
(cherry picked from commit 3e5a3cb2bd)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
This commit is contained in:
Miss Islington (bot)
2026-04-27 22:07:00 +02:00
committed by GitHub
parent 2459faaaa9
commit 22d53a9141
2 changed files with 37 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Doc/library/struct.rst
+24 -20
View File
@@ -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
Modules/_struct.c
+13 -14
View File
@@ -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
@@ -2158,7 +2158,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.
*
@@ -2699,8 +2699,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\
@@ -2710,19 +2710,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");