classification
Title: Clean up the "struct sequence" / "named tuple" docs
Type: Stage: resolved
Components: Documentation Versions: Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, p-ganssle, rhettinger, tim.peters
Priority: normal Keywords: patch

Created on 2019-09-10 22:05 by tim.peters, last changed 2019-09-12 20:14 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 15895 merged rhettinger, 2019-09-11 07:15
PR 15961 merged p-ganssle, 2019-09-11 14:23
PR 15962 merged p-ganssle, 2019-09-11 14:25
PR 16010 merged rhettinger, 2019-09-12 03:03
PR 16062 merged miss-islington, 2019-09-12 14:56
PR 16063 merged miss-islington, 2019-09-12 14:56
Messages (13)
msg351742 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2019-09-10 22:05
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 ;-)
msg351744 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-09-10 22:20
+1 from me.

I'd be happy to get this cleaned-up.  Will work on a PR shortly.
msg351896 - (view) Author: Paul Ganssle (p-ganssle) * (Python committer) Date: 2019-09-11 14:17
New changeset 7117074410118086938044c7a4ef6846ec1662b2 by Paul Ganssle (Raymond Hettinger) in branch 'master':
bpo-38096: Clean up the "struct sequence" / "named tuple" docs (GH-15895)
https://github.com/python/cpython/commit/7117074410118086938044c7a4ef6846ec1662b2
msg351945 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-09-11 15:31
Paul, the usual procedure is for you to mark the PR as approved and leave the commit step for the core developer who created the patch.  

Also, Tim filed this issue and had put thought into it.  The commit shouldn't have occurred until he had a chance to make review comments.

Tim, did the proposed (and prematurely committed) PR fully address your concerns?
msg352012 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2019-09-11 18:47
Paul, please heed what Raymond said:  it's not good to merge another core dev's PR unless they ask you to.  Besides what Raymond said, a core dev may well check in incomplete work for any number of reasons (e.g., to see how the automated test runs turn out).  When I do that, I add a "DO NOT MERGE" label just to be sure, but that really shouldn't be necessary.

Raymond, I added a review anyway, despite that it's already been merged.  One comment suggests repairing an obvious trivial typo.
msg352040 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-09-12 02:50
New changeset 2bb6bf0c8cf863c057027b10751c0fb74189871f by Raymond Hettinger (Paul Ganssle) in branch '3.8':
bpo-38096: Clean up the "struct sequence" / "named tuple" docs (GH-15895) (GH-15961)
https://github.com/python/cpython/commit/2bb6bf0c8cf863c057027b10751c0fb74189871f
msg352041 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-09-12 02:50
New changeset b7a310d865347eabc60d387dbec82ee408315050 by Raymond Hettinger (Paul Ganssle) in branch '3.7':
bpo-38096: Clean up the "struct sequence" / "named tuple" docs (GH-15895) (GH-15962)
https://github.com/python/cpython/commit/b7a310d865347eabc60d387dbec82ee408315050
msg352042 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-09-12 02:51
Tim, I'll make the fix-ups in a separate PR.  There wasn't a clear workflow for reverting, adding fixes, re-applying, and backporting.
msg352076 - (view) Author: Paul Ganssle (p-ganssle) * (Python committer) Date: 2019-09-12 09:32
Sorry guys, my mistake. I think I was a bit caught up in the workflow at the sprint where I've been going through the review-cleanup-merge process a lot faster than I usually do (partially since I have the time and partially since the huge number of PRs getting merged is requiring a lot of rebases, so it's better to get them in quicker).

No need to worry, I will not merge any of your PRs in the future unless you request it for some reason.
msg352190 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-09-12 14:56
New changeset 4210ad5ebd5769f585035e022876e161cd0e9a3e by Raymond Hettinger in branch 'master':
bpo-38096:  Complete the "structseq" and "named tuple" cleanup (GH-16010)
https://github.com/python/cpython/commit/4210ad5ebd5769f585035e022876e161cd0e9a3e
msg352196 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-09-12 15:17
Paul, no worries.  Welcome to the team.
msg352197 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-09-12 15:20
New changeset e3c25fc902eedcd5c593fac58f35645961f55bf4 by Raymond Hettinger (Miss Islington (bot)) in branch '3.7':
bpo-38096:  Complete the "structseq" and "named tuple" cleanup (GH-16010) (GH-16063)
https://github.com/python/cpython/commit/e3c25fc902eedcd5c593fac58f35645961f55bf4
msg352198 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-09-12 15:20
New changeset d04c85f5a74e61637ee17e8d4870c6a1d3b07d3e by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-38096:  Complete the "structseq" and "named tuple" cleanup (GH-16010) (GH-16062)
https://github.com/python/cpython/commit/d04c85f5a74e61637ee17e8d4870c6a1d3b07d3e
History
Date User Action Args
2019-09-12 20:14:30rhettingersetstatus: open -> closed
stage: patch review -> resolved
2019-09-12 15:20:34rhettingersetmessages: + msg352198
2019-09-12 15:20:10rhettingersetmessages: + msg352197
2019-09-12 15:17:37rhettingersetmessages: + msg352196
2019-09-12 14:56:45miss-islingtonsetpull_requests: + pull_request15686
2019-09-12 14:56:39miss-islingtonsetpull_requests: + pull_request15685
2019-09-12 14:56:30rhettingersetmessages: + msg352190
2019-09-12 09:32:19p-gansslesetmessages: + msg352076
2019-09-12 03:03:09rhettingersetpull_requests: + pull_request15636
2019-09-12 02:51:56rhettingersetmessages: + msg352042
2019-09-12 02:50:54rhettingersetmessages: + msg352041
2019-09-12 02:50:32rhettingersetmessages: + msg352040
2019-09-11 18:47:19tim.peterssetmessages: + msg352012
2019-09-11 15:31:51rhettingersetmessages: + msg351945
2019-09-11 14:25:24p-gansslesetstage: backport needed -> patch review
pull_requests: + pull_request15596
2019-09-11 14:23:09p-gansslesetstatus: pending -> open
pull_requests: + pull_request15595
2019-09-11 14:18:25p-gansslesetstatus: open -> pending
resolution: fixed
stage: patch review -> backport needed
2019-09-11 14:17:35p-gansslesetnosy: + p-ganssle
messages: + msg351896
2019-09-11 07:15:58rhettingersetkeywords: + patch
stage: patch review
pull_requests: + pull_request15536
2019-09-10 22:20:13rhettingersetassignee: docs@python -> rhettinger

messages: + msg351744
nosy: + rhettinger
2019-09-10 22:05:24tim.peterscreate