bpo-38096: Clean up the "struct sequence" / "named tuple" docs (GH-15895) (GH-15961)
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 @@
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``).
+ 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.
- 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')``.
+ 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 @@
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 5f8afa8..975c14c 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -408,7 +408,7 @@
.. 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 @@
.. 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'
@@ -790,7 +790,7 @@
.. 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`.
@@ -838,7 +838,7 @@
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`.
@@ -890,7 +890,7 @@
.. 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|
@@ -1480,7 +1480,7 @@
.. 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 @@
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 @@
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.