fileinput — Iterate over lines from multiple input streams

Código-fonte: Lib/fileinput.py

Este módulo implementa uma classe auxiliar e funções para escrever rapidamente um laço sobre uma entrada padrão ou uma lista de arquivos. Se você quiser apenas ler ou escrever um arquivo veja open().

O uso típico é:

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

Isto itera sobre as linhas de todos os arquivos listados em sys.argv[1:], padronizando sys.stdin se a lista estiver vazia. Se o nome de um arquivo for '-', ele também será substituído por sys.stdin e os argumentos opcionais mode e openhook serão ignorados. Para especificar uma lista alternativa de nomes de arquivos, passe-a como primeiro argumento para input(). Um único nome de arquivo também é permitido.

Todos os arquivos são abertos em modo texto por padrão, mas você pode substituir isso especificando o parâmetro mode na chamada para input() ou FileInput. Se ocorrer um erro de E/S durante a abertura ou leitura de um arquivo, OSError será levantada.

Alterado na versão 3.3: IOError costumava ser levantada; agora é um apelido de OSError.

Se sys.stdin for usado mais de uma vez, o segundo e posterior uso não retornará nenhuma linha, exceto talvez para uso interativo, ou se tiver sido explicitamente redefinido (por exemplo, usando sys.stdin.seek(0)).

Arquivos vazios são abertos e fechados imediatamente; a única vez que sua presença na lista de nomes de arquivos é perceptível é quando o último arquivo aberto está vazio.

As linhas são retornadas com novas linhas intactas, o que significa que a última linha de um arquivo pode não ter nenhuma.

You can control how files are opened by providing an opening hook via the openhook parameter to fileinput.input() or FileInput(). The hook must be a function that takes two arguments, filename and mode, and returns an accordingly opened file-like object. If encoding and/or errors are specified, they will be passed to the hook as additional keyword arguments. This module provides a hook_compressed() to support compressed files.

A seguinte função é a interface principal deste módulo:

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

Cria uma instância da classe FileInput. A instância será usada como estado global para as funções deste módulo e também será retornada para uso durante a iteração. Os parâmetros desta função serão passados ​​para o construtor da classe FileInput.

A instância FileInput pode ser usada como um gerenciador de contexto na instrução with. Neste exemplo, input é fechado após a saída da instrução with, mesmo se ocorrer uma exceção:

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

Alterado na versão 3.2: Pode ser usado como gerenciador de contexto.

Alterado na versão 3.8: Os parâmetros nomeados mode e openhook agora são somente-nomeados.

Alterado na versão 3.10: Os parâmetros somente-nomeados encoding e errors foram adicionados.

As funções a seguir usam o estado global criado por fileinput.input(); se não houver estado ativo, RuntimeError será levantada.

fileinput.filename()

Retorna o nome do arquivo que está sendo lido no momento. Antes da primeira linha ser lida, retorna None.

fileinput.fileno()

Retorna o número inteiro de “descritor de arquivo” para o arquivo atual. Quando nenhum arquivo é aberto (antes da primeira linha e entre arquivos), retorna -1.

fileinput.lineno()

Retorna o número cumulativo da linha que acabou de ser lida. Antes da primeira linha ser lida, retorna 0. Após a leitura da última linha do último arquivo, retorna o número da linha dessa linha.

fileinput.filelineno()

Retorna o número da linha no arquivo atual. Antes da primeira linha ser lida, retorna 0. Após a leitura da última linha do último arquivo, retorna o número da linha dessa linha no arquivo.

fileinput.isfirstline()

Retorna True se a linha que acabou de ler for a primeira linha do seu arquivo, caso contrário retorna False.

fileinput.isstdin()

Retorna True se a última linha foi lida em sys.stdin, caso contrário retorna False.

fileinput.nextfile()

Fecha o arquivo atual para que a próxima iteração leia a primeira linha do próximo arquivo (se houver); as linhas não lidas do arquivo não contarão para a contagem cumulativa de linhas. O nome do arquivo não é alterado até que a primeira linha do próximo arquivo seja lida. Antes da leitura da primeira linha, esta função não tem efeito; ele não pode ser usado para pular o primeiro arquivo. Após a leitura da última linha do último arquivo, esta função não terá efeito.

fileinput.close()

Fecha a sequência.

A classe que implementa o comportamento de sequência fornecido pelo módulo também está disponível para subclasses:

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

A classe FileInput é a implementação; seus métodos filename(), fileno(), lineno(), filelineno(), isfirstline(), isstdin(), nextfile() e close() correspondem às funções de mesmo nome no módulo. Além disso, é iterável e possui um método readline() que retorna a próxima linha de entrada. A sequência deve ser acessada em ordem estritamente sequencial; acesso aleatório e readline() não podem ser misturados.

Com mode você pode especificar qual modo de arquivo será passado para open(). Deve ser um entre 'r' e 'rb'.

O openhook, quando fornecido, deve ser uma função que recebe dois argumentos, filename e mode, e retorna um objeto arquivo ou similar aberto de acordo. Você não pode usar inplace e openhook juntos.

Você pode especificar encoding e errors que são passados ​​para open() ou openhook.

Uma instância FileInput pode ser usada como um gerenciador de contexto na instrução with. Neste exemplo, input é fechado após a saída da instrução with, mesmo se ocorrer uma exceção:

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

Alterado na versão 3.2: Pode ser usado como gerenciador de contexto.

Alterado na versão 3.8: Os parâmetros nomeados mode e openhook agora são somente-nomeados.

Alterado na versão 3.10: Os parâmetros somente-nomeados encoding e errors foram adicionados.

Alterado na versão 3.11: Os modos 'rU' e 'U' e o método __getitem__() foram removidos.

Filtragem local opcional: se o argumento nomeado inplace=True for passado para fileinput.input() ou para o construtor FileInput, o arquivo é movido para um arquivo de backup e a saída padrão é direcionada para o arquivo de entrada (se já existir um arquivo com o mesmo nome do arquivo de backup, ele será substituído silenciosamente). Isso torna possível escrever um filtro que reescreva seu arquivo de entrada internamente. Se o parâmetro backup for fornecido (normalmente como backup='.<some extension>'), ele especifica a extensão do arquivo de backup, e o arquivo de backup permanece disponível; por padrão, a extensão é '.bak' e é excluída quando o arquivo de saída é fechado. A filtragem local é desativada quando a entrada padrão é lida.

Os dois ganchos de abertura a seguir são fornecidos por este módulo:

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

Abre de forma transparente arquivos compactados com gzip e bzip2 (reconhecidos pelas extensões '.gz' e '.bz2') usando os módulos gzip e bz2. Se a extensão do nome do arquivo não for '.gz' ou '.bz2', o arquivo é aberto normalmente (ou seja, usando open() sem qualquer descompactação).

Os valores encoding e errors são passados ​​para io.TextIOWrapper para arquivos compactados e abertos para arquivos normais.

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

Alterado na versão 3.10: Os parâmetros somente-nomeados encoding e errors foram adicionados.

fileinput.hook_encoded(encoding, errors=None)

Retorna um gancho que abre cada arquivo com open(), usando a encoding e errors fornecidas para ler o arquivo.

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

Alterado na versão 3.6: Adicionado o parâmetro opcional errors.

Obsoleto desde a versão 3.10: Esta função foi descontinuado já que fileinput.input() e FileInput agora possuem parâmetros encoding e errors.