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.

diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index fa0fb19d852f862e666bf2cfe0d056ee482c2e8f..f504f931f0fa20a9a0e44ee2d512b8e41903994e 100644 (file)
--- 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 c235e27a4155436c88c11621fefd6da21e6836a4..47119cb3961e3c5c2e7436de27e813d28c72287e 100644 (file)
--- 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");