[New-bugs-announce] [issue38096] Clean up the "struct sequence" / "named tuple" docs

[Tim Peters]

New submission from Tim Peters <tim at python.org>:

The Glossary has this entry:

"""
struct sequence
A tuple with named elements. Struct sequences expose an interface similar to 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 _make() or _asdict(). Examples of struct sequences include sys.float_info and the return value of os.stat().
"""

It's trying to document the internal CPython implementation `structseq` detail, a class of which can only be created from the C API (no Python interface is exposed).

But the glossary _also_ has an entry for "named tuple", and the docs just above are confusing that for the related but distinct `collections.namedtuple` facility, which does allow creating a named tuple class from Python, but is NOT the only kind of "named tuple".

This is a mess ;-)

I suggest:

- Throw away the "struct sequence" glossary entry, and remove all references to it from the docs.

- Use "named tuple" everywhere instead.

- Clarify the "named tuple" docs to make clear that it applies to any class that supports tuple methods and also named elements.

- Make clear that `collections.namedtuple` classes are "named tuples" classes, but not the only kind, and support a number of methods beyond what's required for "named tuples".

- Optionally, effectively expose `structseq` to Python code, so that users have one obvious way to create their own bare-bones named tuple types.

- I'd prefer to insist that for any named tuple class C,

  issubclass(C, tuple)
  
  is True.  That's true now of structseqs and collections.namedtuples, and is a sane way to make clear that they must support all tuple methods.
  
I'd mark this as "newcomer friendly", except it's likely to become a bikeshedding nightmare ;-)

----------
assignee: docs at python
components: Documentation
messages: 351742
nosy: docs at python, tim.peters
priority: normal
severity: normal
status: open
title: Clean up the "struct sequence" / "named tuple" docs
versions: Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38096>
_______________________________________