python / python/cpython

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

Abierto
#101,027 3 comentarios 1 reacción 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

docs
Lenguaje dominante
Python
Estrellas
77.2k
Forks
36k
Métricas de merge de PR
Métricas de PR pendientes

Descripción

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

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Línea de trabajo

Comprueba primero el PR vinculado gh-101771 y, después, revisa las entradas de documentación de enumerate y filter y su redacción actual. Se considera completado cuando ambas entradas describen explícitamente la aceptación de un iterable y utilizan de forma coherente la terminología solicitada del glosario.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
python
Área
documentation
Tipo de issue
Documentación
Dificultad
2/5
Tiempo estimado
1-3 horas
Estado de actividad
Estancado
Claridad
Bien especificado
Aptitud para principiantes
30/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.