fileinput
— Itera sobre linhas de múltiplos fluxos de entrada¶
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.
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.
Você pode controlar como os arquivos são abertos fornecendo um gancho de abertura através do parâmetro openhook para fileinput.input()
ou FileInput()
. O gancho deve ser uma função que recebe dois argumentos, filename e mode, e retorna um objeto arquivo ou similar aberto de acordo. Se encoding e/ou errors forem especificados, eles serão passados para o gancho como argumentos nomeados adicionais. Este módulo fornece um hook_compressed()
para oferece suporte a arquivos compactados.
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 classeFileInput
.A instância
FileInput
pode ser usada como um gerenciador de contexto na instruçãowith
. Neste exemplo, input é fechado após a saída da instruçãowith
, 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 retornaFalse
.
- fileinput.isstdin()¶
Retorna
True
se a última linha foi lida emsys.stdin
, caso contrário retornaFalse
.
- 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étodosfilename()
,fileno()
,lineno()
,filelineno()
,isfirstline()
,isstdin()
,nextfile()
eclose()
correspondem às funções de mesmo nome no módulo. Além disso, é iterável e possui um métodoreadline()
que retorna a próxima linha de entrada. A sequência deve ser acessada em ordem estritamente sequencial; acesso aleatório ereadline()
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çãowith
. Neste exemplo, input é fechado após a saída da instruçãowith
, 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ódulosgzip
ebz2
. Se a extensão do nome do arquivo não for'.gz'
ou'.bz2'
, o arquivo é aberto normalmente (ou seja, usandoopen()
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()
eFileInput
agora possuem parâmetros encoding e errors.