Skip to content

gh-148529: Minor improvements of the struct module documentation #148565

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
serhiy-storchaka wants to merge 1 commit into
base: main
Choose a base branch
from
+37 −34
Open

gh-148529: Minor improvements of the struct module documentation #148565

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 24 additions & 20 deletions Doc/library/struct.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
+--------+--------------------------+--------------------+----------------+------------+
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
27 changes: 13 additions & 14 deletions Modules/_struct.c
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.
*
Expand Down Expand Up @@ -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\
Expand All @@ -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");
Expand Down
Loading