update the struct documentation to refer to bytes

patch from Matt Giuca #3478

1 files changed, 37 insertions, 32 deletions

diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index 282483d..7802fdb 100644
--- a/Doc/library/struct.rst
+++ b/Doc/library/struct.rst
@@ -1,19 +1,19 @@
 
-:mod:`struct` --- Interpret strings as packed binary data
+:mod:`struct` --- Interpret bytes as packed binary data
 =========================================================
 
 .. module:: struct
-   :synopsis: Interpret strings as packed binary data.
+   :synopsis: Interpret bytes as packed binary data.
 
 .. index::
    pair: C; structures
    triple: packing; binary; data
 
 This module performs conversions between Python values and C structs represented
-as Python strings.  It uses :dfn:`format strings` (explained below) as compact
-descriptions of the lay-out of the C structs and the intended conversion to/from
-Python values.  This can be used in handling binary data stored in files or from
-network connections, among other sources.
+as Python :class:`bytes` objects.  It uses :dfn:`format strings` (explained
+below) as compact descriptions of the lay-out of the C structs and the
+intended conversion to/from Python values.  This can be used in handling
+binary data stored in files or from network connections, among other sources.
 
 The module defines the following exception and functions:
 
@@ -26,7 +26,7 @@ The module defines the following exception and functions:
 
 .. function:: pack(fmt, v1, v2, ...)
 
-   Return a string containing the values ``v1, v2, ...`` packed according to the
+   Return a bytes containing the values ``v1, v2, ...`` packed according to the
    given format.  The arguments must match the values required by the format
    exactly.
 
@@ -38,12 +38,12 @@ The module defines the following exception and functions:
    a required argument.
 
 
-.. function:: unpack(fmt, string)
+.. function:: unpack(fmt, bytes)
 
-   Unpack the string (presumably packed by ``pack(fmt, ...)``) according to the
+   Unpack the bytes (presumably packed by ``pack(fmt, ...)``) according to the
    given format.  The result is a tuple even if it contains exactly one item.  The
-   string must contain exactly the amount of data required by the format
-   (``len(string)`` must equal ``calcsize(fmt)``).
+   bytes must contain exactly the amount of data required by the format
+   (``len(bytes)`` must equal ``calcsize(fmt)``).
 
 
 .. function:: unpack_from(fmt, buffer[,offset=0])
@@ -56,7 +56,7 @@ The module defines the following exception and functions:
 
 .. function:: calcsize(fmt)
 
-   Return the size of the struct (and hence of the string) corresponding to the
+   Return the size of the struct (and hence of the bytes) corresponding to the
    given format.
 
 Format characters have the following meaning; the conversion between C and
@@ -67,13 +67,13 @@ Python values should be obvious given their types:
 +========+=========================+====================+=======+
 | ``x``  | pad byte                | no value           |       |
 +--------+-------------------------+--------------------+-------+
-| ``c``  | :ctype:`char`           | string of length 1 |       |
+| ``c``  | :ctype:`char`           | bytes of length 1  |       |
 +--------+-------------------------+--------------------+-------+
-| ``b``  | :ctype:`signed char`    | integer            |       |
+| ``b``  | :ctype:`signed char`    | integer            | \(1)  |
 +--------+-------------------------+--------------------+-------+
 | ``B``  | :ctype:`unsigned char`  | integer            |       |
 +--------+-------------------------+--------------------+-------+
-| ``?``  | :ctype:`_Bool`          | bool               | \(1)  |
+| ``?``  | :ctype:`_Bool`          | bool               | \(2)  |
 +--------+-------------------------+--------------------+-------+
 | ``h``  | :ctype:`short`          | integer            |       |
 +--------+-------------------------+--------------------+-------+
@@ -87,18 +87,18 @@ Python values should be obvious given their types:
 +--------+-------------------------+--------------------+-------+
 | ``L``  | :ctype:`unsigned long`  | integer            |       |
 +--------+-------------------------+--------------------+-------+
-| ``q``  | :ctype:`long long`      | integer            | \(2)  |
+| ``q``  | :ctype:`long long`      | integer            | \(3)  |
 +--------+-------------------------+--------------------+-------+
-| ``Q``  | :ctype:`unsigned long   | integer            | \(2)  |
+| ``Q``  | :ctype:`unsigned long   | integer            | \(3)  |
 |        | long`                   |                    |       |
 +--------+-------------------------+--------------------+-------+
 | ``f``  | :ctype:`float`          | float              |       |
 +--------+-------------------------+--------------------+-------+
 | ``d``  | :ctype:`double`         | float              |       |
 +--------+-------------------------+--------------------+-------+
-| ``s``  | :ctype:`char[]`         | string             |       |
+| ``s``  | :ctype:`char[]`         | bytes              | \(1)  |
 +--------+-------------------------+--------------------+-------+
-| ``p``  | :ctype:`char[]`         | string             |       |
+| ``p``  | :ctype:`char[]`         | bytes              | \(1)  |
 +--------+-------------------------+--------------------+-------+
 | ``P``  | :ctype:`void \*`        | integer            |       |
 +--------+-------------------------+--------------------+-------+
@@ -106,11 +106,16 @@ Python values should be obvious given their types:
 Notes:
 
 (1)
+   The ``c``, ``s`` and ``p`` conversion codes operate on :class:`bytes`
+   objects, but packing with such codes also supports :class:`str` objects,
+   which are encoded using UTF-8.
+
+(2)
    The ``'?'`` conversion code corresponds to the :ctype:`_Bool` type defined by
    C99. If this type is not available, it is simulated using a :ctype:`char`. In
    standard mode, it is always represented by one byte.
 
-(2)
+(3)
    The ``'q'`` and ``'Q'`` conversion codes are available in native mode only if
    the platform C compiler supports C :ctype:`long long`, or, on Windows,
    :ctype:`__int64`.  They are always available in standard modes.
@@ -121,11 +126,11 @@ the format string ``'4h'`` means exactly the same as ``'hhhh'``.
 Whitespace characters between formats are ignored; a count and its format must
 not contain whitespace though.
 
-For the ``'s'`` format character, the count is interpreted as the size of the
-string, not a repeat count like for the other format characters; for example,
+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,
 ``'10s'`` means a single 10-byte string, while ``'10c'`` means 10 characters.
 For packing, the string is truncated or padded with null bytes as appropriate to
-make it fit. For unpacking, the resulting string always has exactly the
+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 ``'0c'`` means 0 characters).
 
@@ -137,7 +142,7 @@ 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, 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 characters.
+bytes, but that the string returned can never contain more than 255 bytes.
 
 
 
@@ -203,8 +208,8 @@ machine)::
 
    >>> from struct import *
    >>> pack('hhl', 1, 2, 3)
-   '\x00\x01\x00\x02\x00\x00\x00\x03'
-   >>> unpack('hhl', '\x00\x01\x00\x02\x00\x00\x00\x03')
+   b'\x00\x01\x00\x02\x00\x00\x00\x03'
+   >>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')
    (1, 2, 3)
    >>> calcsize('hhl')
    8
@@ -219,13 +224,13 @@ enforce any alignment.
 Unpacked fields can be named by assigning them to variables or by wrapping
 the result in a named tuple::
 
-    >>> record = 'raymond   \x32\x12\x08\x01\x08'
+    >>> record = b'raymond   \x32\x12\x08\x01\x08'
     >>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)
 
     >>> from collections import namedtuple
     >>> Student = namedtuple('Student', 'name serialnum school gradelevel')
-    >>> Student._make(unpack('<10sHHb', s))
-    Student(name='raymond   ', serialnum=4658, school=264, gradelevel=8)
+    >>> Student._make(unpack('<10sHHb', record))
+    Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)
 
 .. seealso::
 
@@ -265,10 +270,10 @@ The :mod:`struct` module also defines the following type:
       Identical to the :func:`pack_into` function, using the compiled format.
 
 
-   .. method:: unpack(string)
+   .. method:: unpack(bytes)
 
       Identical to the :func:`unpack` function, using the compiled format.
-      (``len(string)`` must equal :attr:`self.size`).
+      (``len(bytes)`` must equal :attr:`self.size`).
 
 
    .. method:: unpack_from(buffer[, offset=0])
@@ -283,6 +288,6 @@ The :mod:`struct` module also defines the following type:
 
    .. attribute:: size
 
-      The calculated size of the struct (and hence of the string) corresponding
+      The calculated size of the struct (and hence of the bytes) corresponding
       to :attr:`format`.