[Python-checkins] bpo-38096: Clean up the "struct sequence" / "named tuple" docs (GH-15895)
Paul Ganssle
webhook-mailer at python.org
Wed Sep 11 10:17:36 EDT 2019
https://github.com/python/cpython/commit/7117074410118086938044c7a4ef6846ec1662b2
commit: 7117074410118086938044c7a4ef6846ec1662b2
branch: master
author: Raymond Hettinger <rhettinger at users.noreply.github.com>
committer: Paul Ganssle <paul at ganssle.io>
date: 2019-09-11T15:17:32+01:00
summary:
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
files:
M Doc/glossary.rst
M Doc/library/sys.rst
M Doc/whatsnew/3.3.rst
M Doc/whatsnew/3.4.rst
M Objects/floatobject.c
M Objects/longobject.c
M Python/sysmodule.c
M Python/thread.c
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 0f2a3a1fdf05..84d0fcab9d75 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 01df026a6e8a..a5528f72e4b7 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 ea036840d671..f1a033c6dae6 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 845e327cabc8..822ba81be8a7 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 6643ff340ea5..20b7f5120bd4 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 ed25e0bee329..6afec180a56e 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 8509aaf86693..476e154b1194 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 c5364f91948f..c36ce6ff9835 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"},
More information about the Python-checkins
mailing list