# `linecache` — Acesso aleatório a linhas de texto

Código-fonte: Lib/linecache.py

O módulo `linecache` permite obter qualquer linha de um arquivo fonte Python, enquanto tenta otimizar internamente, usando um cache, o caso comum em que muitas linhas são lidas em um único arquivo. Isso é usado pelo módulo `traceback` para recuperar as linhas de origem para inclusão no traceback (situação da pilha de execução) formatado.

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.

O módulo `linecache` define as seguintes funções:

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

  Se filename indicar um módulo congelado (começando com `'<frozen '`), a função tentará obter o nome real do arquivo de `module_globals['__file__']` se module_globals não for `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'