From f9e091ae2d40ab78d7b077b11cd7789d679c23d2 Mon Sep 17 00:00:00 2001 From: Mark Dickinson Date: Sat, 12 Jun 2010 19:18:51 +0000 Subject: [PATCH] Merged revisions 81947-81950,81955-81956 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r81947 | mark.dickinson | 2010-06-12 16:17:02 +0100 (Sat, 12 Jun 2010) | 3 lines Issue #8973: Add __all__ to struct module, so that help(struct) correctly displays information for the struct.Struct class. ........ r81948 | mark.dickinson | 2010-06-12 16:19:23 +0100 (Sat, 12 Jun 2010) | 1 line Remove accidental (yet-to-be-reviewed) docstring changes included in r81947. ........ r81949 | mark.dickinson | 2010-06-12 16:43:45 +0100 (Sat, 12 Jun 2010) | 1 line Issue #8973: Improve struct module docstrings. ........ r81950 | mark.dickinson | 2010-06-12 17:30:53 +0100 (Sat, 12 Jun 2010) | 1 line More struct module docs and docstring tweaks. ........ r81955 | mark.dickinson | 2010-06-12 19:20:47 +0100 (Sat, 12 Jun 2010) | 1 line Issue #8469: add standard sizes to struct docs table. ........ r81956 | mark.dickinson | 2010-06-12 19:37:54 +0100 (Sat, 12 Jun 2010) | 2 lines Issue #8469: Reorder struct module sections for clarity; other minor tweaks. ........ --- Doc/library/struct.rst | 272 +++++++++++++++++++++-------------------- Lib/struct.py | 11 ++ Misc/NEWS | 3 + Modules/_struct.c | 59 +++++---- 4 files changed, 190 insertions(+), 155 deletions(-) diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index e924d39f9f..7018e47f40 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -38,38 +38,38 @@ The module defines the following exception and functions: .. function:: pack(fmt, v1, v2, ...) - 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. + Return a bytes object containing the values *v1*, *v2*, ... packed according + to the format string *fmt*. The arguments must match the values required by + the format exactly. .. function:: pack_into(fmt, buffer, offset, v1, v2, ...) - Pack the values ``v1, v2, ...`` according to the given format, write the - packed bytes into the writable *buffer* starting at *offset*. Note that the - offset is a required argument. + Pack the values *v1*, *v2*, ... according to the format string *fmt* and + write the packed bytes into the writable buffer *buffer* starting at + position *offset*. Note that *offset* is a required argument. -.. function:: unpack(fmt, bytes) +.. function:: unpack(fmt, buffer) - 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 bytes must contain exactly the amount of data required by the format - (``len(bytes)`` must equal ``calcsize(fmt)``). + Unpack from the buffer *buffer* (presumably packed by ``pack(fmt, ...)``) + according to the format string *fmt*. The result is a tuple even if it + contains exactly one item. The buffer must contain exactly the amount of + data required by the format (``len(bytes)`` must equal ``calcsize(fmt)``). .. function:: unpack_from(fmt, buffer, offset=0) - Unpack the *buffer* according to the given format. The result is a tuple even - if it contains exactly one item. The *buffer* must contain at least the - amount of data required by the format (``len(buffer[offset:])`` must be at - least ``calcsize(fmt)``). + Unpack from *buffer* starting at position *offset*, according to the format + string *fmt*. The result is a tuple even if it contains exactly one + item. *buffer* must contain at least the amount of data required by the + format (``len(buffer[offset:])`` must be at least ``calcsize(fmt)``). .. function:: calcsize(fmt) - Return the size of the struct (and hence of the bytes) corresponding to the - given format. + Return the size of the struct (and hence of the bytes object produced by + ``pack(fmt, ...)``) corresponding to the format string *fmt*. .. _struct-format-strings: @@ -77,114 +77,9 @@ Format Strings -------------- Format strings are the mechanism used to specify the expected layout when -packing and unpacking data. They are built up from format characters, which -specify the type of data being packed/unpacked. In addition, there are -special characters for controlling the byte order, size, and alignment. - -Format Characters -^^^^^^^^^^^^^^^^^ - -Format characters have the following meaning; the conversion between C and -Python values should be obvious given their types: - -+--------+-------------------------+--------------------+------------+ -| Format | C Type | Python | Notes | -+========+=========================+====================+============+ -| ``x`` | pad byte | no value | | -+--------+-------------------------+--------------------+------------+ -| ``c`` | :ctype:`char` | bytes of length 1 | | -+--------+-------------------------+--------------------+------------+ -| ``b`` | :ctype:`signed char` | integer | \(1),\(4) | -+--------+-------------------------+--------------------+------------+ -| ``B`` | :ctype:`unsigned char` | integer | \(4) | -+--------+-------------------------+--------------------+------------+ -| ``?`` | :ctype:`_Bool` | bool | \(2) | -+--------+-------------------------+--------------------+------------+ -| ``h`` | :ctype:`short` | integer | \(4) | -+--------+-------------------------+--------------------+------------+ -| ``H`` | :ctype:`unsigned short` | integer | \(4) | -+--------+-------------------------+--------------------+------------+ -| ``i`` | :ctype:`int` | integer | \(4) | -+--------+-------------------------+--------------------+------------+ -| ``I`` | :ctype:`unsigned int` | integer | \(4) | -+--------+-------------------------+--------------------+------------+ -| ``l`` | :ctype:`long` | integer | \(4) | -+--------+-------------------------+--------------------+------------+ -| ``L`` | :ctype:`unsigned long` | integer | \(4) | -+--------+-------------------------+--------------------+------------+ -| ``q`` | :ctype:`long long` | integer | \(3), \(4) | -+--------+-------------------------+--------------------+------------+ -| ``Q`` | :ctype:`unsigned long | integer | \(3), \(4) | -| | long` | | | -+--------+-------------------------+--------------------+------------+ -| ``f`` | :ctype:`float` | float | | -+--------+-------------------------+--------------------+------------+ -| ``d`` | :ctype:`double` | float | | -+--------+-------------------------+--------------------+------------+ -| ``s`` | :ctype:`char[]` | bytes | \(1) | -+--------+-------------------------+--------------------+------------+ -| ``p`` | :ctype:`char[]` | bytes | \(1) | -+--------+-------------------------+--------------------+------------+ -| ``P`` | :ctype:`void \*` | integer | | -+--------+-------------------------+--------------------+------------+ - -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. - -(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. - -A format character may be preceded by an integral repeat count. For example, -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 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 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). - -When packing a value ``x`` using one of the integer formats (``'b'``, -``'B'``, ``'h'``, ``'H'``, ``'i'``, ``'I'``, ``'l'``, ``'L'``, -``'q'``, ``'Q'``), if ``x`` is outside the valid range for that format -then :exc:`struct.error` is raised. - -.. versionchanged:: 3.1 - In 3.0, some of the integer formats wrapped out-of-range values and - raised :exc:`DeprecationWarning` instead of :exc:`struct.error`. - - -The ``'p'`` format character encodes a "Pascal string", meaning a short -variable-length string stored in a fixed number of bytes. The count is the total -number of bytes stored. 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 :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 bytes. - - - -For the ``'?'`` format character, the return value is either :const:`True` or -:const:`False`. When packing, the truth value of the argument object is used. -Either 0 or 1 in the native or standard bool representation will be packed, and -any non-zero value will be True when unpacking. +packing and unpacking data. They are built up from :ref:`format-characters`, +which specify the type of data being packed/unpacked. In addition, there are +special characters for controlling the :ref:`struct-alignment`. .. _struct-alignment: @@ -216,9 +111,11 @@ following table: If the first character is not one of these, ``'@'`` is assumed. -Native byte order is big-endian or little-endian, depending on the host system. -For example, Motorola and Sun processors are big-endian; Intel and DEC -processors are little-endian. +Native byte order is big-endian or little-endian, depending on the host +system. For example, Intel x86 and AMD64 (x86-64) are little-endian; +Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature +switchable endianness (bi-endian). Use ``sys.byteorder`` to check the +endianness of your system. Native size and alignment are determined using the C compiler's ``sizeof`` expression. This is always combined with native byte order. @@ -257,6 +154,115 @@ Notes: count of zero. See :ref:`struct-examples`. +.. _format-characters: + +Format Characters +^^^^^^^^^^^^^^^^^ + +Format characters have the following meaning; the conversion between C and +Python values should be obvious given their types: + ++--------+-------------------------+--------------------+----------------+------------+ +| Format | C Type | Python type | Standard size | Notes | ++========+=========================+====================+================+============+ +| ``x`` | pad byte | no value | | | ++--------+-------------------------+--------------------+----------------+------------+ +| ``c`` | :ctype:`char` | bytes of length 1 | 1 | | ++--------+-------------------------+--------------------+----------------+------------+ +| ``b`` | :ctype:`signed char` | integer | 1 | \(1),\(4) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``B`` | :ctype:`unsigned char` | integer | 1 | \(4) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``?`` | :ctype:`_Bool` | bool | 1 | \(2) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``h`` | :ctype:`short` | integer | 2 | \(4) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``H`` | :ctype:`unsigned short` | integer | 2 | \(4) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``i`` | :ctype:`int` | integer | 4 | \(4) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``I`` | :ctype:`unsigned int` | integer | 4 | \(4) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``l`` | :ctype:`long` | integer | 4 | \(4) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``L`` | :ctype:`unsigned long` | integer | 4 | \(4) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``q`` | :ctype:`long long` | integer | 8 | \(3), \(4) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``Q`` | :ctype:`unsigned long | integer | 8 | \(3), \(4) | +| | long` | | | | ++--------+-------------------------+--------------------+----------------+------------+ +| ``f`` | :ctype:`float` | float | 4 | | ++--------+-------------------------+--------------------+----------------+------------+ +| ``d`` | :ctype:`double` | float | 8 | | ++--------+-------------------------+--------------------+----------------+------------+ +| ``s`` | :ctype:`char[]` | bytes | | \(1) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``p`` | :ctype:`char[]` | bytes | | \(1) | ++--------+-------------------------+--------------------+----------------+------------+ +| ``P`` | :ctype:`void \*` | integer | | | ++--------+-------------------------+--------------------+----------------+------------+ + +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. + +(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. + +A format character may be preceded by an integral repeat count. For example, +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 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 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). + +When packing a value ``x`` using one of the integer formats (``'b'``, +``'B'``, ``'h'``, ``'H'``, ``'i'``, ``'I'``, ``'l'``, ``'L'``, +``'q'``, ``'Q'``), if ``x`` is outside the valid range for that format +then :exc:`struct.error` is raised. + +.. versionchanged:: 3.1 + In 3.0, some of the integer formats wrapped out-of-range values and + raised :exc:`DeprecationWarning` instead of :exc:`struct.error`. + + +The ``'p'`` format character encodes a "Pascal string", meaning a short +variable-length string stored in a fixed number of bytes. The count is the total +number of bytes stored. 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 :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 bytes. + + + +For the ``'?'`` format character, the return value is either :const:`True` or +:const:`False`. When packing, the truth value of the argument object is used. +Either 0 or 1 in the native or standard bool representation will be packed, and +any non-zero value will be True when unpacking. + + + .. _struct-examples: Examples @@ -320,7 +326,7 @@ alignment does not enforce any alignment. .. _struct-objects: -Objects +Classes ------- The :mod:`struct` module also defines the following type: @@ -347,10 +353,10 @@ The :mod:`struct` module also defines the following type: Identical to the :func:`pack_into` function, using the compiled format. - .. method:: unpack(bytes) + .. method:: unpack(buffer) Identical to the :func:`unpack` function, using the compiled format. - (``len(bytes)`` must equal :attr:`self.size`). + (``len(buffer)`` must equal :attr:`self.size`). .. method:: unpack_from(buffer, offset=0) @@ -365,6 +371,6 @@ The :mod:`struct` module also defines the following type: .. attribute:: size - The calculated size of the struct (and hence of the bytes) corresponding - to :attr:`format`. + The calculated size of the struct (and hence of the bytes object produced + by the :meth:`pack` method) corresponding to :attr:`format`. diff --git a/Lib/struct.py b/Lib/struct.py index b022355c18..dca15e2ad3 100644 --- a/Lib/struct.py +++ b/Lib/struct.py @@ -1,3 +1,14 @@ +__all__ = [ + # Functions + 'calcsize', 'pack', 'unpack', 'unpack', 'unpack_from', + + # Classes + 'Struct', + + # Exceptions + 'error' + ] + from _struct import * from _struct import _clearcache from _struct import __doc__ diff --git a/Misc/NEWS b/Misc/NEWS index 6f9f76f2a7..6ba4707979 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -241,6 +241,9 @@ Library Extension Modules ----------------- +- Issue #8973: Add __all__ to struct module; this ensures that + help(struct) includes documentation for the struct.Struct class. + - Issue #2810: Fix cases where the Windows registry API returns ERROR_MORE_DATA, requiring a re-try in order to get the complete result. diff --git a/Modules/_struct.c b/Modules/_struct.c index c91e2d1c9b..c3c79e7686 100644 --- a/Modules/_struct.c +++ b/Modules/_struct.c @@ -1384,9 +1384,9 @@ fail: PyDoc_STRVAR(s_unpack__doc__, "S.unpack(buffer) -> (v1, v2, ...)\n\ \n\ -Return tuple containing values unpacked according to this Struct's format.\n\ -Requires len(buffer) == self.size. See struct.__doc__ for more on format\n\ -strings."); +Return a tuple containing values unpacked according to the format\n\ +string S.format. Requires len(buffer) == S.size. See help(struct)\n\ +for more on format strings."); static PyObject * s_unpack(PyObject *self, PyObject *input) @@ -1412,12 +1412,11 @@ s_unpack(PyObject *self, PyObject *input) } PyDoc_STRVAR(s_unpack_from__doc__, -"S.unpack_from(buffer[, offset]) -> (v1, v2, ...)\n\ +"S.unpack_from(buffer[, offset=0]) -> (v1, v2, ...)\n\ \n\ -Return tuple containing values unpacked according to this Struct's format.\n\ -Unlike unpack, unpack_from can unpack values from any object supporting\n\ -the buffer API, not just str. Requires len(buffer[offset:]) >= self.size.\n\ -See struct.__doc__ for more on format strings."); +Return a tuple containing values unpacked according to the format\n\ +string S.format. Requires len(buffer[offset:]) >= S.size. See\n\ +help(struct) for more on format strings."); static PyObject * s_unpack_from(PyObject *self, PyObject *args, PyObject *kwds) @@ -1552,8 +1551,9 @@ s_pack_internal(PyStructObject *soself, PyObject *args, int offset, char* buf) PyDoc_STRVAR(s_pack__doc__, "S.pack(v1, v2, ...) -> bytes\n\ \n\ -Return a bytes containing values v1, v2, ... packed according to this\n\ -Struct's format. See struct.__doc__ for more on format strings."); +Return a bytes object containing values v1, v2, ... packed according\n\ +to the format string S.format. See help(struct) for more on format\n\ +strings."); static PyObject * s_pack(PyObject *self, PyObject *args) @@ -1589,10 +1589,10 @@ s_pack(PyObject *self, PyObject *args) PyDoc_STRVAR(s_pack_into__doc__, "S.pack_into(buffer, offset, v1, v2, ...)\n\ \n\ -Pack the values v1, v2, ... according to this Struct's format, write \n\ -the packed bytes into the writable buffer buf starting at offset. Note\n\ -that the offset is not an optional argument. See struct.__doc__ for \n\ -more on format strings."); +Pack the values v1, v2, ... according to the format string S.format\n\ +and write the packed bytes into the writable buffer buf starting at\n\ +offset. Note that the offset is a required argument. See\n\ +help(struct) for more on format strings."); static PyObject * s_pack_into(PyObject *self, PyObject *args) @@ -1767,7 +1767,9 @@ clearcache(PyObject *self) } PyDoc_STRVAR(calcsize_doc, -"Return size of C struct described by format string fmt."); +"calcsize(fmt) -> integer\n\ +\n\ +Return size in bytes of the struct described by the format string fmt."); static PyObject * calcsize(PyObject *self, PyObject *fmt) @@ -1782,7 +1784,10 @@ calcsize(PyObject *self, PyObject *fmt) } PyDoc_STRVAR(pack_doc, -"Return bytes containing values v1, v2, ... packed according to fmt."); +"pack(fmt, v1, v2, ...) -> bytes\n\ +\n\ +Return a bytes object containing the values v1, v2, ... packed according\n\ +to the format string fmt. See help(struct) for more on format strings."); static PyObject * pack(PyObject *self, PyObject *args) @@ -1811,8 +1816,12 @@ pack(PyObject *self, PyObject *args) } PyDoc_STRVAR(pack_into_doc, -"Pack the values v1, v2, ... according to fmt.\n\ -Write the packed bytes into the writable buffer buf starting at offset."); +"pack_into(fmt, buffer, offset, v1, v2, ...)\n\ +\n\ +Pack the values v1, v2, ... according to the format string fmt and write\n\ +the packed bytes into the writable buffer buf starting at offset. Note\n\ +that the offset is a required argument. See help(struct) for more\n\ +on format strings."); static PyObject * pack_into(PyObject *self, PyObject *args) @@ -1841,8 +1850,11 @@ pack_into(PyObject *self, PyObject *args) } PyDoc_STRVAR(unpack_doc, -"Unpack the bytes containing packed C structure data, according to fmt.\n\ -Requires len(bytes) == calcsize(fmt)."); +"unpack(fmt, buffer) -> (v1, v2, ...)\n\ +\n\ +Return a tuple containing values unpacked according to the format string\n\ +fmt. Requires len(buffer) == calcsize(fmt). See help(struct) for more\n\ +on format strings."); static PyObject * unpack(PyObject *self, PyObject *args) @@ -1861,8 +1873,11 @@ unpack(PyObject *self, PyObject *args) } PyDoc_STRVAR(unpack_from_doc, -"Unpack the buffer, containing packed C structure data, according to\n\ -fmt, starting at offset. Requires len(buffer[offset:]) >= calcsize(fmt)."); +"unpack_from(fmt, buffer[, offset=0]) -> (v1, v2, ...)\n\ +\n\ +Return a tuple containing values unpacked according to the format string\n\ +fmt. Requires len(buffer[offset:]) >= calcsize(fmt). See help(struct)\n\ +for more on format strings."); static PyObject * unpack_from(PyObject *self, PyObject *args, PyObject *kwds) -- 2.40.0