"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():
       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. Two useful
hooks are already provided by this module.

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

fileinput.input(files=None, inplace=False, backup='', *, mode='r', openhook=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')) 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.

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)

   Class "FileInput" is the implementation; its methods "filename()",
   "fileno()", "lineno()", "filelineno()", "isfirstline()",
   "isstdin()", "nextfile()" and "close()" correspond to the functions
   of the same name in the module. In addition it has a "readline()"
   method which returns the next input line, and a "__getitem__()"
   method which implements the sequence behavior. The sequence must be
   accessed in strictly sequential order; random access and
   "readline()" cannot be mixed.

   With *mode* you can specify which file mode will be passed to
   "open()". It must be one of "'r'", "'rU'", "'U'" and "'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.

   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.

   Obsoleto desde a versão 3.4: The "'rU'" and "'U'" modes.

   Obsoleto desde a versão 3.8: Support for "__getitem__()" method is
   deprecated.

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

**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)

   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).

   Usage example:  "fi =
   fileinput.FileInput(openhook=fileinput.hook_compressed)"

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*.
