python / python/cpython

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

Ouverte
#101,027 3 commentaires 1 réaction 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

docs
Langage dominant
Python
Étoiles
77.2k
Forks
36k
Métriques de merge des PR
Métriques de PR en attente

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

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Vérifiez d’abord la PR liée gh-101771, puis examinez les entrées de documentation pour enumerate et filter ainsi que leur formulation actuelle. C’est terminé lorsque les deux entrées décrivent explicitement l’acceptation d’un itérable et utilisent systématiquement la terminologie demandée du glossaire.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
python
Domaine
documentation
Type d'issue
Documentation
Difficulté
2/5
Temps estimé
1-3 heures
Activité
À l'abandon
Clarté
Clairement spécifiée
Accessibilité débutants
30/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.