FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

bpo-38096: Clean up the "struct sequence" / "named tuple" docs (GH-15… · python/cpython@7117074 · GitHub

/ cpython Public

Commit 7117074

Browse files
authored andcommitted
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
1 parent 7b69069 commit 7117074

8 files changed

Lines changed: 40 additions & 37 deletions

File tree

‎Doc/glossary.rst‎

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -739,17 +739,28 @@ Glossary
739739
also :term:`immutable`.
740740

741741
named tuple
742-
Any tuple-like class whose indexable elements are also accessible using
743-
named attributes (for example, :func:`time.localtime` returns a
744-
tuple-like object where the *year* is accessible either with an
745-
index such as ``t[0]`` or with a named attribute like ``t.tm_year``).
746-
747-
A named tuple can be a built-in type such as :class:`time.struct_time`,
748-
or it can be created with a regular class definition. A full featured
749-
named tuple can also be created with the factory function
750-
:func:`collections.namedtuple`. The latter approach automatically
751-
provides extra features such as a self-documenting representation like
752-
``Employee(name='jones', title='programmer')``.
742+
The term "named tuple" applies to any type or class that inherits from
743+
tuple and whose indexable elements are also accessible using named
744+
attributes. The type or class may have other features as well.
745+
746+
Several built-in types are named tuples, including the values returned
747+
by :func:`time.localtime` and :func:`os.stat`. Another example is
748+
:data:`sys.float_info`::
749+
750+
>>> sys.float_info[1] # indexed access
751+
1024
752+
>>> sys.float_info.max_exp # named field access
753+
1024
754+
>>> isinstance(sys.float_info, tuple) # kind of tuple
755+
True
756+
757+
Some named tuples are built-in types (such as the above examples).
758+
Alternatively, a named tuple can be created from a regular class
759+
definition that inherits from :class:`tuple` and that defines named
760+
fields. Such as class can be written by hand or it can be created with
761+
the factory function :func:`collections.namedtuple`. The latter
762+
technique also adds some extra methods that may not be found in
763+
hand-written or built-in named tuples.
753764

754765
namespace
755766
The place where a variable is stored. Namespaces are implemented as
@@ -1032,14 +1043,6 @@ Glossary
10321043
an :term:`expression` or one of several constructs with a keyword, such
10331044
as :keyword:`if`, :keyword:`while` or :keyword:`for`.
10341045

1035-
struct sequence
1036-
A tuple with named elements. Struct sequences expose an interface similar
1037-
to :term:`named tuple` in that elements can be accessed either by
1038-
index or as an attribute. However, they do not have any of the named tuple
1039-
methods like :meth:`~collections.somenamedtuple._make` or
1040-
:meth:`~collections.somenamedtuple._asdict`. Examples of struct sequences
1041-
include :data:`sys.float_info` and the return value of :func:`os.stat`.
1042-
10431046
text encoding
10441047
A codec which encodes Unicode strings to bytes.
10451048

‎Doc/library/sys.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -408,7 +408,7 @@ always available.
408408

409409
.. data:: flags
410410

411-
The :term:`struct sequence` *flags* exposes the status of command line
411+
The :term:`named tuple` *flags* exposes the status of command line
412412
flags. The attributes are read only.
413413

414414
============================= =============================
@@ -450,7 +450,7 @@ always available.
450450

451451
.. data:: float_info
452452

453-
A :term:`struct sequence` holding information about the float type. It
453+
A :term:`named tuple` holding information about the float type. It
454454
contains low level information about the precision and internal
455455
representation. The values correspond to the various floating-point
456456
constants defined in the standard header file :file:`float.h` for the 'C'
@@ -782,7 +782,7 @@ always available.
782782

783783
.. data:: hash_info
784784

785-
A :term:`struct sequence` giving parameters of the numeric hash
785+
A :term:`named tuple` giving parameters of the numeric hash
786786
implementation. For more details about hashing of numeric types, see
787787
:ref:`numeric-hash`.
788788

@@ -830,7 +830,7 @@ always available.
830830

831831
This is called ``hexversion`` since it only really looks meaningful when viewed
832832
as the result of passing it to the built-in :func:`hex` function. The
833-
:term:`struct sequence` :data:`sys.version_info` may be used for a more
833+
:term:`named tuple` :data:`sys.version_info` may be used for a more
834834
human-friendly encoding of the same information.
835835

836836
More details of ``hexversion`` can be found at :ref:`apiabiversion`.
@@ -882,7 +882,7 @@ always available.
882882

883883
.. data:: int_info
884884

885-
A :term:`struct sequence` that holds information about Python's internal
885+
A :term:`named tuple` that holds information about Python's internal
886886
representation of integers. The attributes are read only.
887887

888888
.. tabularcolumns:: |l|L|
@@ -1457,7 +1457,7 @@ always available.
14571457

14581458
.. data:: thread_info
14591459

1460-
A :term:`struct sequence` holding information about the thread
1460+
A :term:`named tuple` holding information about the thread
14611461
implementation.
14621462

14631463
.. tabularcolumns:: |l|p{0.7\linewidth}|

‎Doc/whatsnew/3.3.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2002,8 +2002,8 @@ platform-independent fashion. (Contributed by Ross Lagerwall in
20022002
sys
20032003
---
20042004

2005-
The :mod:`sys` module has a new :data:`~sys.thread_info` :term:`struct
2006-
sequence` holding information about the thread implementation
2005+
The :mod:`sys` module has a new :data:`~sys.thread_info` :term:`named
2006+
tuple` holding information about the thread implementation
20072007
(:issue:`11223`).
20082008

20092009

‎Doc/whatsnew/3.4.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1849,7 +1849,7 @@ Python's default implementation to a SipHash implementation on platforms that
18491849
have a 64 bit data type. Any performance differences in comparison with the
18501850
older FNV algorithm are trivial.
18511851

1852-
The PEP adds additional fields to the :attr:`sys.hash_info` struct sequence to
1852+
The PEP adds additional fields to the :attr:`sys.hash_info` named tuple to
18531853
describe the hash algorithm in use by the currently executing binary. Otherwise,
18541854
the PEP does not alter any existing CPython APIs.
18551855

‎Objects/floatobject.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ static PyTypeObject FloatInfoType;
4343
PyDoc_STRVAR(floatinfo__doc__,
4444
"sys.float_info\n\
4545
\n\
46-
A structseq holding information about the float type. It contains low level\n\
46+
A named tuple holding information about the float type. It contains low level\n\
4747
information about the precision and internal representation. Please study\n\
4848
your system's :file:`float.h` for more information.");
4949

‎Objects/longobject.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5780,7 +5780,7 @@ static PyTypeObject Int_InfoType;
57805780
PyDoc_STRVAR(int_info__doc__,
57815781
"sys.int_info\n\
57825782
\n\
5783-
A struct sequence that holds information about Python's\n\
5783+
A named tuple that holds information about Python's\n\
57845784
internal representation of integers. The attributes are read only.");
57855785

57865786
static PyStructSequence_Field int_info_fields[] = {

‎Python/sysmodule.c‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1160,7 +1160,7 @@ static PyTypeObject AsyncGenHooksType;
11601160
PyDoc_STRVAR(asyncgen_hooks_doc,
11611161
"asyncgen_hooks\n\
11621162
\n\
1163-
A struct sequence providing information about asynchronous\n\
1163+
A named tuple providing information about asynchronous\n\
11641164
generators hooks. The attributes are read only.");
11651165

11661166
static PyStructSequence_Field asyncgen_hooks_fields[] = {
@@ -1269,7 +1269,7 @@ static PyTypeObject Hash_InfoType;
12691269
PyDoc_STRVAR(hash_info_doc,
12701270
"hash_info\n\
12711271
\n\
1272-
A struct sequence providing parameters used for computing\n\
1272+
A named tuple providing parameters used for computing\n\
12731273
hashes. The attributes are read only.");
12741274

12751275
static PyStructSequence_Field hash_info_fields[] = {
@@ -2293,17 +2293,17 @@ builtin_module_names -- tuple of module names built into this interpreter\n\
22932293
copyright -- copyright notice pertaining to this interpreter\n\
22942294
exec_prefix -- prefix used to find the machine-specific Python library\n\
22952295
executable -- absolute path of the executable binary of the Python interpreter\n\
2296-
float_info -- a struct sequence with information about the float implementation.\n\
2296+
float_info -- a named tuple with information about the float implementation.\n\
22972297
float_repr_style -- string indicating the style of repr() output for floats\n\
2298-
hash_info -- a struct sequence with information about the hash algorithm.\n\
2298+
hash_info -- a named tuple with information about the hash algorithm.\n\
22992299
hexversion -- version information encoded as a single integer\n\
23002300
implementation -- Python implementation information.\n\
2301-
int_info -- a struct sequence with information about the int implementation.\n\
2301+
int_info -- a named tuple with information about the int implementation.\n\
23022302
maxsize -- the largest supported length of containers.\n\
23032303
maxunicode -- the value of the largest Unicode code point\n\
23042304
platform -- platform identifier\n\
23052305
prefix -- prefix used to find the Python library\n\
2306-
thread_info -- a struct sequence with information about the thread implementation.\n\
2306+
thread_info -- a named tuple with information about the thread implementation.\n\
23072307
version -- the version of this interpreter as a string\n\
23082308
version_info -- version information as a named tuple\n\
23092309
"

‎Python/thread.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ PyThread_tss_is_created(Py_tss_t *key)
147147
PyDoc_STRVAR(threadinfo__doc__,
148148
"sys.thread_info\n\
149149
\n\
150-
A struct sequence holding information about the thread implementation.");
150+
A named tuple holding information about the thread implementation.");
151151

152152
static PyStructSequence_Field threadinfo_fields[] = {
153153
{"name", "name of the thread implementation"},

0 commit comments

Comments
 (0)

Back | FazBrowse Home | New Git URL