`enumerate` and `filter` documentation should explicitly mention that they accept any iterable
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 36k
- PR merge metrics
- PR metrics pending
Description
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 byenumerate()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 38f71973) 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.
Linked PRs
- gh-101771
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Check linked PR gh-101771 first, then review the documentation entries for enumerate and filter and their existing wording. Done means both entries explicitly describe acceptance of an iterable and use the requested glossary terminology consistently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 30/100