python / python/cpython

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

Open
#101,027 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

docs
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 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 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.