X Tutup
The Wayback Machine - https://web.archive.org/web/20230119202248/https://github.com/python/cpython/issues/101027
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

enumerate and filter documentation should explicitly mention that they accept any iterable #101027

Open
JustAnotherArchivist opened this issue Jan 14, 2023 · 3 comments
Labels
docs Documentation in the Doc dir

Comments

@JustAnotherArchivist
Copy link
Contributor

The documentation of enumerate(iterable, start=0) currently reads:

Return an enumerate object. iterable must be a sequence, an iterator, or some other object which supports iteration. The __next__() method of the iterator returned by enumerate() returns a tuple containing a count (from start which defaults to 0) and the values obtained from iterating over iterable.

This wording dates back to 2002 (commit 38f7197) with minimal changes ('the values obtained' was originally 'the corresponding value obtained', which was slightly more accurate in my opinion). An earlier issue about this paragraph can be found at #66914, though the specific issue at hand, the description of iterable's type, was not really discussed there.

While the parameter name indicates that enumerate accepts any iterable as the first argument, I find it strange that the description explicitly lists

a sequence, an iterator, or some other object which supports iteration

instead of/without actually mentioning 'iterable' and referencing the term's definition in the glossary.

My primary suggestion is to replace (the slightly vague, as it could mean iterable or iterator) 'object which supports iteration' with 'iterable' and a link to the glossary. Additionally, since all iterators are iterables, their mention could also be removed.

Suggestion 1 (with or without a link for 'iterator'):

iterable must be a sequence, an iterator, or some other iterable.

Suggestion 2:

iterable must be a sequence or some other iterable.


filter has a similar situation:

iterable may be either a sequence, a container which supports iteration, or an iterator.

'A container which supports iteration' is quite vague and mildly misleading since other parts of the documentation use the term 'container' for lists and similar types. It also uses 'may' instead of 'must'. I would suggest to use the same wording there as for enumerate.

@JustAnotherArchivist JustAnotherArchivist added the docs Documentation in the Doc dir label Jan 14, 2023
@Dasanant
Copy link

Hello! First time contributor here. I would like to take this issue.

@JustAnotherArchivist
Copy link
Contributor Author

@Dasanant I think this needs some opinion collecting on what's the best wording first. (That's also why I opened it as an issue, not a PR.)

@millsks
Copy link

millsks commented Jan 14, 2023

IMHO, I think would lean towards suggestion 2. It mentions sequence so the reader gets the general idea and if they look at the definition of iterable the other types are mentioned with links back to their entry. Keeps it short and concise while providing the reader a way to get to more information.

See also iterator, sequence, and generator.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir
Projects
None yet
Development

No branches or pull requests

3 participants
X Tutup