From 7117074410118086938044c7a4ef6846ec1662b2 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Wed, 11 Sep 2019 07:17:32 -0700 Subject: bpo-38096: Clean up the "struct sequence" / "named tuple" docs (GH-15895) * bpo-38096: Clean up the "struct sequence" / "named tuple" docs * Fix remaining occurrences of "struct sequence" * Repair a user visible docstring --- Doc/glossary.rst | 41 ++++++++++++++++++++++------------------- Doc/library/sys.rst | 12 ++++++------ Doc/whatsnew/3.3.rst | 4 ++-- Doc/whatsnew/3.4.rst | 2 +- Objects/floatobject.c | 2 +- Objects/longobject.c | 2 +- Python/sysmodule.c | 12 ++++++------ Python/thread.c | 2 +- 8 files changed, 40 insertions(+), 37 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 0f2a3a1..84d0fca 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -739,17 +739,28 @@ Glossary also :term:`immutable`. named tuple - Any tuple-like class whose indexable elements are also accessible using - named attributes (for example, :func:`time.localtime` returns a - tuple-like object where the *year* is accessible either with an - index such as ``t[0]`` or with a named attribute like ``t.tm_year``). - - A named tuple can be a built-in type such as :class:`time.struct_time`, - or it can be created with a regular class definition. A full featured - named tuple can also be created with the factory function - :func:`collections.namedtuple`. The latter approach automatically - provides extra features such as a self-documenting representation like - ``Employee(name='jones', title='programmer')``. + The term "named tuple" applies to any type or class that inherits from + tuple and whose indexable elements are also accessible using named + attributes. The type or class may have other features as well. + + Several built-in types are named tuples, including the values returned + by :func:`time.localtime` and :func:`os.stat`. Another example is + :data:`sys.float_info`:: + + >>> sys.float_info[1] # indexed access + 1024 + >>> sys.float_info.max_exp # named field access + 1024 + >>> isinstance(sys.float_info, tuple) # kind of tuple + True + + Some named tuples are built-in types (such as the above examples). + Alternatively, a named tuple can be created from a regular class + definition that inherits from :class:`tuple` and that defines named + fields. Such as class can be written by hand or it can be created with + the factory function :func:`collections.namedtuple`. The latter + technique also adds some extra methods that may not be found in + hand-written or built-in named tuples. namespace The place where a variable is stored. Namespaces are implemented as @@ -1032,14 +1043,6 @@ Glossary an :term:`expression` or one of several constructs with a keyword, such as :keyword:`if`, :keyword:`while` or :keyword:`for`. - struct sequence - A tuple with named elements. Struct sequences expose an interface similar - to :term:`named tuple` in that elements can be accessed either by - index or as an attribute. However, they do not have any of the named tuple - methods like :meth:`~collections.somenamedtuple._make` or - :meth:`~collections.somenamedtuple._asdict`. Examples of struct sequences - include :data:`sys.float_info` and the return value of :func:`os.stat`. - text encoding A codec which encodes Unicode strings to bytes. diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 01df026..a5528f7 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -408,7 +408,7 @@ always available. .. data:: flags - The :term:`struct sequence` *flags* exposes the status of command line + The :term:`named tuple` *flags* exposes the status of command line flags. The attributes are read only. ============================= ============================= @@ -450,7 +450,7 @@ always available. .. data:: float_info - A :term:`struct sequence` holding information about the float type. It + A :term:`named tuple` holding information about the float type. It contains low level information about the precision and internal representation. The values correspond to the various floating-point constants defined in the standard header file :file:`float.h` for the 'C' @@ -782,7 +782,7 @@ always available. .. data:: hash_info - A :term:`struct sequence` giving parameters of the numeric hash + A :term:`named tuple` giving parameters of the numeric hash implementation. For more details about hashing of numeric types, see :ref:`numeric-hash`. @@ -830,7 +830,7 @@ always available. This is called ``hexversion`` since it only really looks meaningful when viewed as the result of passing it to the built-in :func:`hex` function. The - :term:`struct sequence` :data:`sys.version_info` may be used for a more + :term:`named tuple` :data:`sys.version_info` may be used for a more human-friendly encoding of the same information. More details of ``hexversion`` can be found at :ref:`apiabiversion`. @@ -882,7 +882,7 @@ always available. .. data:: int_info - A :term:`struct sequence` that holds information about Python's internal + A :term:`named tuple` that holds information about Python's internal representation of integers. The attributes are read only. .. tabularcolumns:: |l|L| @@ -1457,7 +1457,7 @@ always available. .. data:: thread_info - A :term:`struct sequence` holding information about the thread + A :term:`named tuple` holding information about the thread implementation. .. tabularcolumns:: |l|p{0.7\linewidth}| diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst index ea03684..f1a033c 100644 --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -2002,8 +2002,8 @@ platform-independent fashion. (Contributed by Ross Lagerwall in sys --- -The :mod:`sys` module has a new :data:`~sys.thread_info` :term:`struct -sequence` holding information about the thread implementation +The :mod:`sys` module has a new :data:`~sys.thread_info` :term:`named +tuple` holding information about the thread implementation (:issue:`11223`). diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst index 845e327..822ba81 100644 --- a/Doc/whatsnew/3.4.rst +++ b/Doc/whatsnew/3.4.rst @@ -1849,7 +1849,7 @@ Python's default implementation to a SipHash implementation on platforms that have a 64 bit data type. Any performance differences in comparison with the older FNV algorithm are trivial. -The PEP adds additional fields to the :attr:`sys.hash_info` struct sequence to +The PEP adds additional fields to the :attr:`sys.hash_info` named tuple to describe the hash algorithm in use by the currently executing binary. Otherwise, the PEP does not alter any existing CPython APIs. diff --git a/Objects/floatobject.c b/Objects/floatobject.c index 6643ff3..20b7f51 100644 --- a/Objects/floatobject.c +++ b/Objects/floatobject.c @@ -43,7 +43,7 @@ static PyTypeObject FloatInfoType; PyDoc_STRVAR(floatinfo__doc__, "sys.float_info\n\ \n\ -A structseq holding information about the float type. It contains low level\n\ +A named tuple holding information about the float type. It contains low level\n\ information about the precision and internal representation. Please study\n\ your system's :file:`float.h` for more information."); diff --git a/Objects/longobject.c b/Objects/longobject.c index ed25e0b..6afec18 100644 --- a/Objects/longobject.c +++ b/Objects/longobject.c @@ -5780,7 +5780,7 @@ static PyTypeObject Int_InfoType; PyDoc_STRVAR(int_info__doc__, "sys.int_info\n\ \n\ -A struct sequence that holds information about Python's\n\ +A named tuple that holds information about Python's\n\ internal representation of integers. The attributes are read only."); static PyStructSequence_Field int_info_fields[] = { diff --git a/Python/sysmodule.c b/Python/sysmodule.c index 8509aaf..476e154 100644 --- a/Python/sysmodule.c +++ b/Python/sysmodule.c @@ -1160,7 +1160,7 @@ static PyTypeObject AsyncGenHooksType; PyDoc_STRVAR(asyncgen_hooks_doc, "asyncgen_hooks\n\ \n\ -A struct sequence providing information about asynchronous\n\ +A named tuple providing information about asynchronous\n\ generators hooks. The attributes are read only."); static PyStructSequence_Field asyncgen_hooks_fields[] = { @@ -1269,7 +1269,7 @@ static PyTypeObject Hash_InfoType; PyDoc_STRVAR(hash_info_doc, "hash_info\n\ \n\ -A struct sequence providing parameters used for computing\n\ +A named tuple providing parameters used for computing\n\ hashes. The attributes are read only."); static PyStructSequence_Field hash_info_fields[] = { @@ -2293,17 +2293,17 @@ builtin_module_names -- tuple of module names built into this interpreter\n\ copyright -- copyright notice pertaining to this interpreter\n\ exec_prefix -- prefix used to find the machine-specific Python library\n\ executable -- absolute path of the executable binary of the Python interpreter\n\ -float_info -- a struct sequence with information about the float implementation.\n\ +float_info -- a named tuple with information about the float implementation.\n\ float_repr_style -- string indicating the style of repr() output for floats\n\ -hash_info -- a struct sequence with information about the hash algorithm.\n\ +hash_info -- a named tuple with information about the hash algorithm.\n\ hexversion -- version information encoded as a single integer\n\ implementation -- Python implementation information.\n\ -int_info -- a struct sequence with information about the int implementation.\n\ +int_info -- a named tuple with information about the int implementation.\n\ maxsize -- the largest supported length of containers.\n\ maxunicode -- the value of the largest Unicode code point\n\ platform -- platform identifier\n\ prefix -- prefix used to find the Python library\n\ -thread_info -- a struct sequence with information about the thread implementation.\n\ +thread_info -- a named tuple with information about the thread implementation.\n\ version -- the version of this interpreter as a string\n\ version_info -- version information as a named tuple\n\ " diff --git a/Python/thread.c b/Python/thread.c index c5364f9..c36ce6f 100644 --- a/Python/thread.c +++ b/Python/thread.c @@ -147,7 +147,7 @@ PyThread_tss_is_created(Py_tss_t *key) PyDoc_STRVAR(threadinfo__doc__, "sys.thread_info\n\ \n\ -A struct sequence holding information about the thread implementation."); +A named tuple holding information about the thread implementation."); static PyStructSequence_Field threadinfo_fields[] = { {"name", "name of the thread implementation"}, -- cgit v0.12