"linecache" --- Acesso aleatório a linhas de texto
**************************************************

**Código-fonte:** Lib/linecache.py

======================================================================

The "linecache" module allows one to get any line from a Python source
file, while attempting to optimize internally, using a cache, the
common case where many lines are read from a single file.  This is
used by the "traceback" module to retrieve source lines for inclusion
in  the formatted traceback.

A função "tokenize.open()" é usada para abrir arquivos. Esta função
usa "tokenize.detect_encoding()" para obter a codificação do arquivo;
na ausência de um token de codificação, o padrão de codificação do
arquivo é UTF-8.

The "linecache" module defines the following functions:

linecache.getline(filename, lineno, module_globals=None)

   Obtém a linha *lineno* do arquivo chamado *filename*. Essa função
   nunca levanta uma exceção --- ela retornará "''" em erros (o
   caractere de nova linha final será incluído para as linhas
   encontradas).

   If *filename* indicates a frozen module (starting with "'<frozen
   '"), the function will attempt to get the real file name from
   "module_globals['__file__']" if *module_globals* is not "None".

   Se um arquivo chamado *filename* não for encontrado, a função
   primeiro verifica por um "__loader__" da **PEP 302** em
   *module_globals*. Se existe um carregador e ele define um método
   "get_source", isso determina as linhas fonte (se "get_source()"
   retornar "None", então "''" será retornado). Por fim, se *filename*
   for um nome de arquivo relativo, ele será procurado em relação às
   entradas no caminho de pesquisa do módulo, "sys.path".

   Alterado na versão 3.14: Suporte a *filename* de módulos
   congelados.

linecache.clearcache()

   Limpa o cache. Use esta função se você não precisar mais de linhas
   de arquivos lidos anteriormente usando "getline()".

linecache.checkcache(filename=None)

   Verifica a validade do cache. Use esta função se os arquivos no
   cache tiverem sido alterados no disco e você precisar da versão
   atualizada. Se *filename* for omitido, ele verificará todas as
   entradas no cache.

linecache.lazycache(filename, module_globals)

   Captura detalhes suficientes sobre um módulo não baseado em arquivo
   para permitir obter suas linhas posteriormente via "getline()"
   mesmo se *module_globals* for "None" na chamada posterior. Isso
   evita a execução de E/S até que uma linha seja realmente
   necessária, sem ter que carregar o módulo global indefinidamente.

   Adicionado na versão 3.5.

Exemplo:

   >>> import linecache
   >>> linecache.getline(linecache.__file__, 8)
   'import sys\n'
