Skip to content
Permalink
Browse files

bpo-38096: Clean up the "struct sequence" / "named tuple" docs (GH-15895

  • Loading branch information...
pganssle authored and rhettinger committed Sep 12, 2019
1 parent a5a7102 commit 2bb6bf0c8cf863c057027b10751c0fb74189871f
Showing with 40 additions and 37 deletions.
  1. +22 −19 Doc/glossary.rst
  2. +6 −6 Doc/library/sys.rst
  3. +2 −2 Doc/whatsnew/3.3.rst
  4. +1 −1 Doc/whatsnew/3.4.rst
  5. +1 −1 Objects/floatobject.c
  6. +1 −1 Objects/longobject.c
  7. +6 −6 Python/sysmodule.c
  8. +1 −1 Python/thread.c
@@ -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.

@@ -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'
@@ -790,7 +790,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`.

@@ -838,7 +838,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`.
@@ -890,7 +890,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|
@@ -1480,7 +1480,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}|
@@ -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`).


@@ -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.

@@ -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.");

@@ -5771,7 +5771,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[] = {
@@ -1162,7 +1162,7 @@ static PyTypeObject AsyncGenHooksType;
PyDoc_STRVAR(asyncgen_hooks_doc,
"asyncgen_hooks\n\
\n\
A struct sequence providing information about asynhronous\n\
A named tuple providing information about asynchronous\n\
generators hooks. The attributes are read only.");

static PyStructSequence_Field asyncgen_hooks_fields[] = {
@@ -1270,7 +1270,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[] = {
@@ -2321,17 +2321,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\
"
@@ -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"},

0 comments on commit 2bb6bf0

Please sign in to comment.
You can’t perform that action at this time.