Documentación de Python: ¿iterable muchas veces?

En la documentación de una función de Python, lo encuentro más Pythonic decir:Documentación de Python: ¿iterable muchas veces?

def Foo(i): 
    """i: An interable containing…"""

... ... en lugar de

def Foo(i): 
    """i: A list of …"""

Cuando i realmente no tiene que ser un list. (Foo operará felizmente en un set, tuple, etc.) El problema son los generadores. Los generadores generalmente solo permiten 1 iteración. La mayoría de las funciones de son correctas con generadores o iterables que solo permiten una sola pasada, pero otras no.

Para aquellas funciones que no pueden aceptar generadores/cosas que solo se pueden repetir una vez, ¿hay un término Python claro y consistente para decir "cosa que solo se puede iterar más de una vez"?

El glosario de Python para iterable y iterator parece tener una definición de "una vez, pero quizás más si tiene suerte".

Fuente

2011-11-29 Thanatos

¿Una "colección"? Parece describir todos los tipos de ejemplos aquí. – ephemient

+1 al uso del contenedor, que parece capturar la idea subyacente de la manera más concisa, pero ... ¿No creo que haya visto el "contenedor" utilizado en ninguna documentación de Python? –

Un contenedor es un objeto con un método '__contains __()', que no es ni necesario ni suficiente para un iterable reutilizable. http://docs.python.org/library/collections.html#collections.Container –

No conozco un término estándar para esto, al menos no fuera de contexto, pero creo que "iterable reutilizable" aclararía el asunto si necesita una frase corta.

En la práctica, generalmente es posible estructurar su función para que no tenga que iterar más de i más de una vez. Alternativamente, puede crear una lista de iterable y luego iterar sobre la lista tantas veces como desee; o puede usar itertools.tee para obtener múltiples "copias" independientes del iterador. Eso le permite aceptar un generador incluso si necesita usarlo más de una vez.

Fuente

2011-11-29 06:07:48

Tenga en cuenta que, como se señala en [docs] (https://docs.python.org/3/library/itertools.html# itertools.tee), "En general, si un iterador usa la mayoría o la totalidad de los datos antes de que se inicie otro iterador, es más rápido usar list() en lugar de tee()." En ese caso, 'tee()' copiará/almacenará el contenido varias veces, mientras que 'list()' solo lo almacenará una vez. – waterproof

Esto es probablemente más una cuestión de estilo y preferencia que cualquier otra cosa, pero ... tengo una opinión diferente sobre mi documentación: Siempre escribo la cadena de documentación de acuerdo con la aportación prevista en el marco del programa de.

Ejemplo: si escribía una función que esperar para repasar las claves de un diccionario e ignorar sus valores que escribo:

arg : a dictionary of...

incluso si for e in arg: funcionaría con otros iterables. Elegí hacerlo, porque dentro del contexto de mi código, no me importa si la función aún funciona ... Me preocupa más que quien lea la documentación entienda cómo esa función es destinada a ser usada.

Por otro lado, si estoy escribiendo una función utilidad que puede hacer frente a un amplio espectro de iterables por diseño, voy a una de estas dos maneras:

documento qué tipo de excepción se levantó bajo ciertas condiciones [antiguos: "Raise TypeError si el iterable no puede repetirse más de una vez"]
realizan alguna manipulación argumento de suscripción preferente que hará la función compatible con iterables 'una sola vez'.

En otras palabras, trato de ya sea que mi función lo suficientemente sólido como para manejar casos extremos, o para ser muy franco en sus limitaciones.

Nuevamente: no hay nada de malo con el enfoque que desea tomar, pero considero que este es uno de los casos en que "explicit is better than implicit": una documentación en la que se menciona "iterable reutilizable" es definitivamente precisa, pero el adjetivo podría fácilmente ser pasado por alto.

HTH!

Fuente

2011-11-29 06:48:27 mac

Documentación de Python: ¿iterable muchas veces?

Respuesta

Cuestiones relacionadas