`enumerate` and `filter` documentation should explicitly mention that they accept any iterable
Nessuno ha ancora preso questa issue.
- Lingua principale
- Python
- Stelle
- 77.2k
- Fork
- 36k
- Metriche di merge delle PR
- Metriche PR in attesa
Descrizione
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
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Controlla prima la PR collegata gh-101771, quindi esamina le voci della documentazione per enumerate e filter e la loro formulazione esistente. Il lavoro è completato quando entrambe le voci descrivono esplicitamente l’accettazione di un iterabile e utilizzano in modo coerente la terminologia richiesta nel glossario.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python
- Ambito
- documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 2/5
- Tempo stimato
- 1-3 ore
- Stato di attività
- Ferma
- Chiarezza
- Specificata chiaramente
- Idoneità per principianti
- 30/100