Skip to content

bpo-40636: Clarify the zip built-in docstring.#20118

Merged
gpshead merged 7 commits into
python:masterfrom
gpshead:improve_zip_docstring
May 15, 2020
Merged

bpo-40636: Clarify the zip built-in docstring.#20118
gpshead merged 7 commits into
python:masterfrom
gpshead:improve_zip_docstring

Conversation

@gpshead

@gpshead gpshead commented May 15, 2020 •
edited by bedevere-bot
Loading

Copy link
Copy Markdown
Member

This puts much simpler text up front along with an example.

As it was, the zip built-in docstring was technically correct. But too
technical for the reader who shouldn't need to know about __next__ and
StopIteration as most people do not need to understand the internal
implementation details of the iterator protocol in their daily life.

This is a documentation only change, intended to be backported to 3.8; it is
only tangentially related to PEP-618 which might offer new behavior options
in the future.

https://bugs.python.org/issue40636

@gpshead
Clarify the zip built-in docstring.
bf5a80b 
This puts much simpler text up front along with an example.

As it was, the zip built-in docstring was technically correct.  But too
technical for the reader who shouldn't _need_ to know about `__next__` and
`StopIteration` as most people do not need to understand the internal
implementation details of the iterator protocol in their daily life.

This is a documentation only change, intended to be backported to 3.8; it is
only tangentially related to PEP-618 which might offer new behavior options
in the future.
@gpshead gpshead added docs Documentation in the Doc dir skip news needs backport to 3.8 labels May 15, 2020
@gpshead
gpshead requested a review from brandtbucher May 15, 2020 19:27
@gpshead gpshead self-assigned this May 15, 2020
gpshead
gpshead commented May 15, 2020
View reviewed changes
Comment thread Python/bltinmodule.c Outdated
@brandtbucher

brandtbucher commented May 15, 2020

Copy link
Copy Markdown
Member

I really like the docstring for enumerate. I wonder if we could follow its example:

Return an enumerate object.

  iterable
    an object supporting iteration

The enumerate object yields pairs containing a count (from start, which
defaults to zero) and a value yielded by the iterable argument.

enumerate is useful for obtaining an indexed list:
    (0, seq[0]), (1, seq[1]), (2, seq[2]), ...

gpshead added 2 commits May 15, 2020 13:02
@gpshead
Wording based a bit more on enumerate per Brandt's suggestion.
ad88165 
This gets rid of the legacy wording paragraph which seems too tied to
implementation details of the iterator protocol which isn't relevant here.
@gpshead
Update the doctest change detector test.
99fefe7 
My zip docstring contains a doctest example.
@gpshead

gpshead commented May 15, 2020

Copy link
Copy Markdown
Member Author

Good suggestion, take a look at the latest proposed wording.

gpshead
gpshead commented May 15, 2020
View reviewed changes
Comment thread Python/bltinmodule.c Outdated
brandtbucher
brandtbucher requested changes May 15, 2020
View reviewed changes

@brandtbucher brandtbucher left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this... just a couple of suggestions.

Comment thread Python/bltinmodule.c Outdated
Comment thread Python/bltinmodule.c Outdated
Comment thread Python/bltinmodule.c Outdated
gpshead and others added 3 commits May 15, 2020 13:39
@gpshead @brandtbucher
Update Python/bltinmodule.c
9f956cb 
Co-authored-by: Brandt Bucher <brandtbucher@gmail.com>
@gpshead @brandtbucher
Update Python/bltinmodule.c
a902fb0 
Co-authored-by: Brandt Bucher <brandtbucher@gmail.com>
@gpshead @brandtbucher
Update Python/bltinmodule.c
0c1e931 
Co-authored-by: Brandt Bucher <brandtbucher@gmail.com>
@gpshead

gpshead commented May 15, 2020

Copy link
Copy Markdown
Member Author

good suggestios, this is looking good.

@gpshead
gpshead merged commit 6a5d3ff into python:master May 15, 2020
@miss-islington

miss-islington commented May 15, 2020

Copy link
Copy Markdown
Contributor

Thanks @gpshead for the PR 🌮🎉.. I'm working now to backport this PR to: 3.7, 3.8.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 15, 2020
@gpshead @miss-islington
bpo-40636: Clarify the zip built-in docstring. (pythonGH-20118)
60a23d3 
Clarify the zip built-in docstring.

This puts much simpler text up front along with an example.

As it was, the zip built-in docstring was technically correct.  But too
technical for the reader who shouldn't _need_ to know about `__next__` and
`StopIteration` as most people do not need to understand the internal
implementation details of the iterator protocol in their daily life.

This is a documentation only change, intended to be backported to 3.8; it is
only tangentially related to PEP-618 which might offer new behavior options
in the future.

Wording based a bit more on enumerate per Brandt's suggestion.

This gets rid of the legacy wording paragraph which seems too tied to
implementation details of the iterator protocol which isn't relevant here.

Co-authored-by: Brandt Bucher <brandtbucher@gmail.com>
(cherry picked from commit 6a5d3ff)

Co-authored-by: Gregory P. Smith <greg@krypto.org>
@bedevere-bot

bedevere-bot commented May 15, 2020

Copy link
Copy Markdown

GH-20124 is a backport of this pull request to the 3.8 branch.

@miss-islington

miss-islington commented May 15, 2020

Copy link
Copy Markdown
Contributor

Sorry, @gpshead, I could not cleanly backport this to 3.7 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 6a5d3ff67644af42b1a781be2eacb2e82913441c 3.7

@gpshead
gpshead deleted the improve_zip_docstring branch May 15, 2020 21:26
miss-islington added a commit that referenced this pull request May 15, 2020
@miss-islington @gpshead
bpo-40636: Clarify the zip built-in docstring. (GH-20118)
c3d025a 
Clarify the zip built-in docstring.

This puts much simpler text up front along with an example.

As it was, the zip built-in docstring was technically correct.  But too
technical for the reader who shouldn't _need_ to know about `__next__` and
`StopIteration` as most people do not need to understand the internal
implementation details of the iterator protocol in their daily life.

This is a documentation only change, intended to be backported to 3.8; it is
only tangentially related to PEP-618 which might offer new behavior options
in the future.

Wording based a bit more on enumerate per Brandt's suggestion.

This gets rid of the legacy wording paragraph which seems too tied to
implementation details of the iterator protocol which isn't relevant here.

Co-authored-by: Brandt Bucher <brandtbucher@gmail.com>
(cherry picked from commit 6a5d3ff)

Co-authored-by: Gregory P. Smith <greg@krypto.org>
arturoescaip pushed a commit to arturoescaip/cpython that referenced this pull request May 24, 2020
@gpshead @brandtbucher @arturoescaip
bpo-40636: Clarify the zip built-in docstring. (pythonGH-20118)
9e75a3c 
Clarify the zip built-in docstring.

This puts much simpler text up front along with an example.

As it was, the zip built-in docstring was technically correct.  But too
technical for the reader who shouldn't _need_ to know about `__next__` and
`StopIteration` as most people do not need to understand the internal
implementation details of the iterator protocol in their daily life.

This is a documentation only change, intended to be backported to 3.8; it is
only tangentially related to PEP-618 which might offer new behavior options
in the future.

Wording based a bit more on enumerate per Brandt's suggestion.

This gets rid of the legacy wording paragraph which seems too tied to
implementation details of the iterator protocol which isn't relevant here.

Co-authored-by: Brandt Bucher <brandtbucher@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@brandtbucher brandtbucher brandtbucher approved these changes

Assignees

@gpshead gpshead

Labels

docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@gpshead @brandtbucher @miss-islington @bedevere-bot @the-knights-who-say-ni