Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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
  • Loading branch information
rhettinger authored and pganssle committed Sep 11, 2019
1 parent 7b69069 commit 7117074
Show file tree
Hide file tree
Showing 8 changed files with 40 additions and 37 deletions.
41 changes: 22 additions & 19 deletions Doc/glossary.rst
Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down
12 changes: 6 additions & 6 deletions Doc/library/sys.rst
Expand Up @@ -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.

============================= =============================
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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`.

Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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|
Expand Down Expand Up @@ -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}|
Expand Down
4 changes: 2 additions & 2 deletions Doc/whatsnew/3.3.rst
Expand Up @@ -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`).


Expand Down
2 changes: 1 addition & 1 deletion Doc/whatsnew/3.4.rst
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion Objects/floatobject.c
Expand Up @@ -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.");

Expand Down
2 changes: 1 addition & 1 deletion Objects/longobject.c
Expand Up @@ -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[] = {
Expand Down
12 changes: 6 additions & 6 deletions Python/sysmodule.c
Expand Up @@ -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[] = {
Expand Down Expand Up @@ -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[] = {
Expand Down Expand Up @@ -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\
"
Expand Down
2 changes: 1 addition & 1 deletion Python/thread.c
Expand Up @@ -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"},
Expand Down

0 comments on commit 7117074

Please sign in to comment.