fileinput — Iterar sobre líneas de múltiples flujos de entrada

Código fuente: Lib/fileinput.py

Este módulo implementa una clase auxiliar y funciones para escribir rápidamente un bucle sobre una entrada estándar o una lista de archivos. Si solo quiere leer o escribir un archivo, vea open().

El uso común es:

import fileinput
for line in fileinput.input(encoding="utf-8"):
    process(line)

Esto itera sobre las líneas de todos los archivos enumerados en sys.argv[1:], por defecto a sys.stdin si la lista está vacía. Si un nombre de archivo es '-', también se reemplaza por sys.stdin y los argumentos opcionales mode y openhook se ignoran. Para especificar una lista alternativa de nombres de archivo, se pasa como primer argumento a input(). También se permite un único nombre de archivo.

Todos los archivos se abren en modo texto de manera predeterminada, pero puede anular esto especificando el parámetro mode en la llamada a input() o FileInput. Si se produce un error de E/S durante la apertura o lectura de un archivo, se lanza OSError.

Distinto en la versión 3.3: IOError solía ser lanzado; ahora es un alias de OSError.

Si sys.stdin se usa más de una vez, el segundo y siguientes usos no retornarán líneas, excepto tal vez para uso interactivo, o si se ha reiniciado explícitamente (por ejemplo, usando sys.stdin.seek(0)).

Los archivos vacíos se abren e inmediatamente se cierran; la única vez que su presencia en la lista de nombres de archivo es notable es cuando el último archivo abierto está vacío.

Las líneas se retornan con cualquier nueva línea intacta, lo que significa que la última línea en un archivo puede no tener una.

Puede controlar cómo se abren los archivos proporcionando un enlace de apertura a través del parámetro openhook a fileinput.input() o FileInput(). El enlace debe ser una función que tome dos argumentos, filename y mode, y en consecuencia retorna un objeto similar a un archivo abierto. Si encoding y/o errors son especificados, serán pasados al enlace como argumentos de palabras clave adicionales. Este módulo proporciona hook_compressed() para admitir archivos comprimidos.

La siguiente función es la interfaz principal de este módulo:

fileinput.input(files=None, inplace=False, backup='', *, mode='r', openhook=None, encoding=None, errors=None)

Crea una instancia de la clase FileInput. La instancia se usará como estado global para las funciones de este módulo y también se volverá a usar durante la iteración. Los parámetros de esta función se pasarán al constructor de la clase FileInput.

La instancia FileInput se puede usar como gestor de contexto en la declaración with. En este ejemplo, input se cierra después de salir de la instrucción with, incluso si se produce una excepción:

with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding="utf-8") as f:
    for line in f:
        process(line)

Distinto en la versión 3.2: Se puede usar como gestor de contexto.

Distinto en la versión 3.8: Los parámetros de palabras clave mode y openhook ahora son solo palabras clave.

Distinto en la versión 3.10: Los parámetros exclusivos de palabra clave encoding y errors son añadidos.

Las siguientes funciones utilizan el estado global creado por fileinput.input(); si no hay estado activo, es lanzado RuntimeError.

fileinput.filename()

Retorna el nombre del archivo que se está leyendo actualmente. Antes de leer la primera línea, retorna None.

fileinput.fileno()

Retorna el entero «file descriptor» para el archivo actual. Cuando no se abre ningún archivo (antes de la primera línea y entre archivos), retorna -1.

fileinput.lineno()

Retorna el número de línea acumulativa de la línea que se acaba de leer. Antes de que se haya leído la primera línea, retorna 0. Después de leer la última línea del último archivo, retorna el número de línea de esa línea.

fileinput.filelineno()

Retorna el número de línea en el archivo actual. Antes de que se haya leído la primera línea, retorna 0. Después de leer la última línea del último archivo, retorna el número de línea de esa línea dentro del archivo.

fileinput.isfirstline()

Retorna True si la línea que acaba de leer es la primera línea de su archivo; de lo contrario, retorna False.

fileinput.isstdin()

Retorna True si la última línea se leyó de sys.stdin, de lo contrario, retorna False.

fileinput.nextfile()

Cierra el archivo actual para que la próxima iteración lea la primera línea del siguiente archivo (si corresponde); las líneas no leídas del archivo no contarán para el recuento de líneas acumuladas. El nombre del archivo no se cambia hasta que se haya leído la primera línea del siguiente archivo. Antes de que se haya leído la primera línea, esta función no tiene efecto; no se puede usar para omitir el primer archivo. Después de leer la última línea del último archivo, esta función no tiene efecto.

fileinput.close()

Cierra la secuencia.

La clase que implementa el comportamiento de secuencia proporcionado por el módulo también está disponible para la subclasificación:

class fileinput.FileInput(files=None, inplace=False, backup='', *, mode='r', openhook=None, encoding=None, errors=None)

La Clase FileInput es la implementación; sus métodos filename(), fileno(), lineno(), filelineno(), isfirstline(), isstdin(), nextfile() y close() corresponden a las funciones del mismo nombre en el módulo. Además es iterable y tiene un método readline() que retorna la siguiente línea de entrada. Se debe acceder a la secuencia en orden estrictamente secuencial; acceso aleatorio y readline() no se pueden mezclar.

Con mode puede especificar qué modo de archivo se pasará a open(). Debe ser uno de 'r' y 'rb'.

El openhook, cuando se proporciona, debe ser una función que tome dos argumentos, filename y mode, y retorne un objeto similar a un archivo abierto en consecuencia. No puede usar inplace y openhook juntos.

Puedes especificar encoding y errors que son pasados a open() o openhook.

Una instancia FileInput se puede usar como gestor de contexto en la instrucción with. En este ejemplo, input se cierra después de salir de la palabra with, incluso si se produce una excepción:

with FileInput(files=('spam.txt', 'eggs.txt')) as input:
    process(input)

Distinto en la versión 3.2: Se puede usar como gestor de contexto.

Distinto en la versión 3.8: El parámetro de palabra clave mode y openhook ahora son solo palabras clave.

Distinto en la versión 3.10: Los parámetros exclusivos de palabra clave encoding y errors son añadidos.

Distinto en la versión 3.11: The 'rU' and 'U' modes and the __getitem__() method have been removed.

Filtrado al instante opcional: si el argumento de la palabra clave inplace=True se pasa a fileinput.input() o al constructor FileInput, el archivo se mueve a una copia de seguridad y la salida estándar es dirigida al archivo de entrada (si ya existe un archivo con el mismo nombre que el archivo de copia de seguridad, se reemplazará en silencio). Esto hace posible escribir un filtro que reescribe su archivo de entrada en su lugar. Si se proporciona el parámetro backup (generalmente como backup='.<some extension>'), este especifica la extensión para el archivo de respaldo y el archivo de respaldo permanece; de forma predeterminada, la extensión es '.bak' y se elimina cuando se cierra el archivo de salida. El filtrado en el lugar se desactiva cuando se lee la entrada estándar.

Este módulo proporciona los dos enlaces de apertura siguientes:

fileinput.hook_compressed(filename, mode, *, encoding=None, errors=None)

Abre de forma transparente archivos comprimidos con gzip y bzip2 (reconocidos por las extensiones '.gz' and '.bz2') utilizando los módulos gzip y bz2. Si la extensión del nombre de archivo no es '.gz' or '.bz2', el archivo se abre normalmente (es decir, usando open() sin descompresión).

Los valores encoding y errors se pasan a io.TextIOWrapper para archivos comprimidos y para abrir archivos normales.

Ejemplo de uso: fi = fileinput.FileInput(openhook=fileinput.hook_compressed, encoding="utf-8")

Distinto en la versión 3.10: Los parámetros exclusivos de palabra clave encoding y errors son añadidos.

fileinput.hook_encoded(encoding, errors=None)

Retorna un enlace que abre cada archivo con open(), usando el encoding y errors dados para leer el archivo.

Ejemplo de uso: fi = fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8", "surrogateescape"))

Distinto en la versión 3.6: Se agregó el parámetro opcional errors.

Obsoleto desde la versión 3.10: Esta función está en desuso ya que fileinput.input() y FileInput ahora tienen los parámetros encoding y errors.