[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Change by Raymond Hettinger :


--
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:

Paul, no worries.  Welcome to the team.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[miss-islington]

Change by miss-islington :


--
pull_requests: +15686
pull_request: https://github.com/python/cpython/pull/16063

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[miss-islington]

Change by miss-islington :


--
pull_requests: +15685
pull_request: https://github.com/python/cpython/pull/16062

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Paul Ganssle]

Paul Ganssle  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Change by Raymond Hettinger :


--
pull_requests: +15636
pull_request: https://github.com/python/cpython/pull/16010

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Tim Peters]

Tim Peters  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Paul Ganssle]

Change by Paul Ganssle :


--
pull_requests: +15596
stage: backport needed -> patch review
pull_request: https://github.com/python/cpython/pull/15962

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Paul Ganssle]

Change by Paul Ganssle :


--
pull_requests: +15595
status: pending -> open
pull_request: https://github.com/python/cpython/pull/15961

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Paul Ganssle]

Change by Paul Ganssle :


--
resolution:  -> fixed
stage: patch review -> backport needed
status: open -> pending

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Paul Ganssle]

Paul Ganssle  added the comment:


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


--
nosy: +p-ganssle

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Change by Raymond Hettinger :


--
keywords: +patch
pull_requests: +15536
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/15895

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Raymond Hettinger]

Raymond Hettinger  added the comment:

+1 from me.

I'd be happy to get this cleaned-up.  Will work on a PR shortly.

--
assignee: docs@python -> rhettinger
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue38096] Clean up the "struct sequence" / "named tuple" docs

[Tim Peters]

New submission from Tim Peters :

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@python
components: Documentation
messages: 351742
nosy: docs@python, tim.peters
priority: normal
severity: normal
status: open
title: Clean up the "struct sequence" / "named tuple" docs
versions: Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com