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@2bb6bf0 · GitHub

/ cpython Public

Commit 2bb6bf0

Browse files
authored andcommitted
bpo-38096: Clean up the "struct sequence" / "named tuple" docs (GH-15895) (GH-15961)
1 parent a5a7102 commit 2bb6bf0

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'
@@ -790,7 +790,7 @@ always available.
790790

791791
.. data:: hash_info
792792

793-
A :term:`struct sequence` giving parameters of the numeric hash
793+
A :term:`named tuple` giving parameters of the numeric hash
794794
implementation. For more details about hashing of numeric types, see
795795
:ref:`numeric-hash`.
796796

@@ -838,7 +838,7 @@ always available.
838838

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

844844
More details of ``hexversion`` can be found at :ref:`apiabiversion`.
@@ -890,7 +890,7 @@ always available.
890890

891891
.. data:: int_info
892892

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

896896
.. tabularcolumns:: |l|L|
@@ -1480,7 +1480,7 @@ always available.
14801480

14811481
.. data:: thread_info
14821482

1483-
A :term:`struct sequence` holding information about the thread
1483+
A :term:`named tuple` holding information about the thread
14841484
implementation.
14851485

14861486
.. 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
@@ -5771,7 +5771,7 @@ static PyTypeObject Int_InfoType;
57715771
PyDoc_STRVAR(int_info__doc__,
57725772
"sys.int_info\n\
57735773
\n\
5774-
A struct sequence that holds information about Python's\n\
5774+
A named tuple that holds information about Python's\n\
57755775
internal representation of integers. The attributes are read only.");
57765776

57775777
static PyStructSequence_Field int_info_fields[] = {

‎Python/sysmodule.c‎

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

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

12761276
static PyStructSequence_Field hash_info_fields[] = {
@@ -2321,17 +2321,17 @@ builtin_module_names -- tuple of module names built into this interpreter\n\
23212321
copyright -- copyright notice pertaining to this interpreter\n\
23222322
exec_prefix -- prefix used to find the machine-specific Python library\n\
23232323
executable -- absolute path of the executable binary of the Python interpreter\n\
2324-
float_info -- a struct sequence with information about the float implementation.\n\
2324+
float_info -- a named tuple with information about the float implementation.\n\
23252325
float_repr_style -- string indicating the style of repr() output for floats\n\
2326-
hash_info -- a struct sequence with information about the hash algorithm.\n\
2326+
hash_info -- a named tuple with information about the hash algorithm.\n\
23272327
hexversion -- version information encoded as a single integer\n\
23282328
implementation -- Python implementation information.\n\
2329-
int_info -- a struct sequence with information about the int implementation.\n\
2329+
int_info -- a named tuple with information about the int implementation.\n\
23302330
maxsize -- the largest supported length of containers.\n\
23312331
maxunicode -- the value of the largest Unicode code point\n\
23322332
platform -- platform identifier\n\
23332333
prefix -- prefix used to find the Python library\n\
2334-
thread_info -- a struct sequence with information about the thread implementation.\n\
2334+
thread_info -- a named tuple with information about the thread implementation.\n\
23352335
version -- the version of this interpreter as a string\n\
23362336
version_info -- version information as a named tuple\n\
23372337
"

‎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