# `readline` — Interface para o GNU readline

O módulo `readline` define uma série de funções para facilitar o autocomplemento e leitura/gravação de arquivos históricos do interpretador Python. Este módulo pode ser usado diretamente ou através do módulo `rlcompleter`, que provê o autocomplemento de identificadores Python no prompt interativo. As configurações feitas usando este módulo afetam o comportamento do prompt interativo do interpretador e dos prompts oferecidos pela função embutida `input()`.

Readline keybindings may be configured via an initialization file, typically `.inputrc` in your home directory. See Readline Init File in the GNU Readline manual for information about the format and allowable constructs of that file, and the capabilities of the Readline library in general.

Nota

A API da biblioteca Readline subjacente pode ser implementada pela biblioteca `libedit` em vez do GNU readline. No macOS, o módulo `readline` detecta qual biblioteca está sendo usada no tempo de execução.

O arquivo de configuração para `libedit` é diferente daquele do GNU readline. Se você carregar programaticamente strings de configuração, você pode verificar o texto “libedit” em `readline.__doc__` para diferenciar entre GNU readline e libedit.

Se você usar a emulação readline editline/`libedit` no macOS, o arquivo de inicialização localizado no seu diretório home será chamado `.editrc`. Por exemplo, o seguinte conteúdo em `~/.editrc` ativará as combinações de teclas vi e a conclusão por TAB:

    python:bind -v
    python:bind ^I rl_complete

## Arquivo init

As seguintes funções estão relacionadas ao arquivo init e à configuração do usuário:

`readline.``parse_and_bind`(string)

  Executa a linha de init fornecida no argumento string. Isso chama `rl_parse_and_bind()` na biblioteca subjacente.

`readline.``read_init_file`([filename])

  Executa um arquivo de inicialização do readline. O nome de arquivo padrão é o último nome de arquivo usado. Isso chama `rl_read_init_file()` na biblioteca subjacente.

## Buffer de linha

As seguintes funções operam no buffer de linha:

`readline.``get_line_buffer`()

  Retorna o conteúdo atual do buffer de linha (`rl_line_buffer` na biblioteca subjacente).

`readline.``insert_text`(string)

  Insere texto no buffer de linha na posição do cursor. Isso chama `rl_insert_text()` na biblioteca subjacente, mas ignora o valor de retorno.

`readline.``redisplay`()

  Altera o que é exibido na tela para refletir o conteúdo atual do buffer de linha. Isso chama `rl_redisplay()` na biblioteca subjacente.

## Arquivo de histórico

As seguintes funções operam em um arquivo histórico:

`readline.``read_history_file`([filename])

  Carrega um arquivo de histórico do readline e anexa-o à lista de histórico. O nome do arquivo padrão é `~/.history`. Isso chama `read_history()` na biblioteca subjacente.

`readline.``write_history_file`([filename])

  Salva a lista de histórico em um arquivo de histórico readline, substituindo qualquer arquivo existente. O nome do arquivo padrão é `~/.history`. Isso chama `write_history()` na biblioteca subjacente.

`readline.``append_history_file`(nelements[, filename])

  Anexa os últimos nelements itens do histórico a um arquivo. O nome do arquivo padrão é `~/.history`. O arquivo já deve existir. Isso chama `append_history()` na biblioteca subjacente. Esta função só existe se o Python foi compilado para uma versão da biblioteca que a suporta.

  Novo na versão 3.5.

`readline.``get_history_length`()
`readline.``set_history_length`(length)

  Define ou retorna o número desejado de linhas para salvar no arquivo de histórico. A função `write_history_file()` usa este valor para truncar o arquivo de histórico, chamando `history_truncate_file()` na biblioteca subjacente. Valores negativos implicam tamanho ilimitado do arquivo de histórico.

## Lista de histórico

As seguintes funções operam em uma lista de histórico global:

`readline.``clear_history`()

  Limpa o histórico atual. Isso chama `clear_history()` na biblioteca subjacente. A função Python só existe se o Python foi compilado para uma versão da biblioteca que a suporta.

`readline.``get_current_history_length`()

  Retorna o número de itens atualmente no histórico. (Isso é diferente de `get_history_length()`, que retorna o número máximo de linhas que serão gravadas em um arquivo de histórico.)

`readline.``get_history_item`(index)

  Retorna o conteúdo atual do item do histórico em index. O índice do item é baseado em um. Isso chama `history_get()` na biblioteca subjacente.

`readline.``remove_history_item`(pos)

  Remove o item de histórico especificado por sua posição do histórico. A posição conta a partir de zero. Isso chama `remove_history()` na biblioteca subjacente.

`readline.``replace_history_item`(pos, line)

  Substitui o item de histórico especificado pela sua posição por linha. A posição conta a partir do zero. Isso chama `replace_history_entry()` na biblioteca subjacente.

`readline.``add_history`(line)

  Acrescenta line ao buffer do histórico, como se fosse a última linha digitada. Isso chama `add_history()` na biblioteca subjacente.

`readline.``set_auto_history`(enabled)

  Habilita ou desabilita chamadas automáticas para `add_history()` ao ler a entrada via readline. O argumento enabled deve ser um valor booleano que, quando verdadeiro, ativa o histórico automático e, quando falso, desativa o histórico automático.

  Novo na versão 3.6.

  CPython implementation detail: Auto history is enabled by default, and changes to this do not persist across multiple sessions.

## Ganchos de inicialização

`readline.``set_startup_hook`([function])

  Define ou remove a função invocada pelo retorno de chamada `rl_startup_hook` da biblioteca subjacente. Se function for especificada, ela será usada como a nova função de gancho; se omitido ou `None`, qualquer função já instalada será removida. O gancho é chamado sem argumentos antes de readline imprimir o primeiro prompt.

`readline.``set_pre_input_hook`([function])

  Define ou remove a função invocada pelo retorno de chamada `rl_pre_input_hook` da biblioteca subjacente. Se function for especificada, ela será usada como a nova função de gancho; se omitida ou `None`, qualquer função já instalada será removida. O gancho é chamado sem argumentos após a impressão do primeiro prompt e pouco antes de readline começar a ler os caracteres de entrada. Esta função só existe se o Python foi compilado para uma versão da biblioteca que a suporta.

## Autocomplemento

As funções a seguir estão relacionadas à implementação de uma função personalizada de autocomplemento ou completion, em inglês, de palavras. Isso normalmente é operado pela tecla Tab e pode sugerir e completar automaticamente uma palavra que está sendo digitada. Por padrão, Readline está configurado para ser usado por `rlcompleter` para completar identificadores Python para o interpretador interativo. Se o módulo `readline` for usado com um autocomplemento personalizado, um conjunto diferente de delimitadores de palavras deverá ser definido.

`readline.``set_completer`([function])

  Define ou remove a função de autocomplemento. Se function for especificada, ela será usada como a nova função de autocomplemento; se omitido ou `None`, qualquer função de autocomplemento já instalada será removida. A função de autocomplemento é chamada como `function(text, state)`, para state em `0`, `1`, `2`, …, até retornar um valor que não seja string. Deve retornar o próximo autocomplemento possível começando com text.

  A função de autocomplemento instalada é invocada pelo retorno de chamada entry_func passado para `rl_completion_matches()` na biblioteca subjacente. A string text vem do primeiro parâmetro para o retorno de chamada `rl_attempted_completion_function` da biblioteca subjacente.

`readline.``get_completer`()

  Obtém a função de autocomplemento ou `None` se nenhuma função de autocomplemento tiver sido definida.

`readline.``get_completion_type`()

  Obtém o tipo de autocomplemento que está sendo tentado. Isso retorna a variável `rl_completion_type` na biblioteca subjacente como um número inteiro.

`readline.``get_begidx`()
`readline.``get_endidx`()

  Get the beginning or ending index of the completion scope. These indexes are the start and end arguments passed to the `rl_attempted_completion_function` callback of the underlying library.

`readline.``set_completer_delims`(string)
`readline.``get_completer_delims`()

  Define ou obtém os delimitadores de palavras para autocomplemento. Estes determinam o início da palavra a ser considerada para autocomplemento (o escopo de autocomplemento). Essas funções acessam a variável `rl_completer_word_break_characters` na biblioteca subjacente.

`readline.``set_completion_display_matches_hook`([function])

  Define ou remove a função de exibição de autocomplemento. Se function for especificada, ela será usada como a nova função de exibição de autocomplemento; se omitida ou `None`, qualquer função de exibição de autocomplemento já instalada será removida. Isso define ou limpa o retorno de chamada `rl_completion_display_matches_hook` na biblioteca subjacente. A função de exibição de autocomplemento é chamada como `function(substitution, [correspondências], comprimento_da_correspondência_mais_longa)` uma vez que cada correspondência precisa ser exibida.

## Exemplo

O exemplo a seguir demonstra como usar as funções de leitura e gravação de histórico do módulo `readline` para carregar e salvar automaticamente um arquivo de histórico chamado `.python_history` do diretório inicial do usuário. O código abaixo normalmente seria executado automaticamente durante sessões interativas do arquivo `PYTHONSTARTUP` do usuário.

    import atexit
    import os
    import readline

    histfile = os.path.join(os.path.expanduser("~"), ".python_history")
    try:
        readline.read_history_file(histfile)
        # default history len is -1 (infinite), which may grow unruly
        readline.set_history_length(1000)
    except FileNotFoundError:
        pass

    atexit.register(readline.write_history_file, histfile)

Na verdade, este código é executado automaticamente quando o Python é executado no modo interativo (veja Configuração Readline).

O exemplo a seguir atinge o mesmo objetivo, mas oferece suporte a sessões interativas simultâneas, anexando apenas o novo histórico.

    import atexit
    import os
    import readline
    histfile = os.path.join(os.path.expanduser("~"), ".python_history")

    try:
        readline.read_history_file(histfile)
        h_len = readline.get_current_history_length()
    except FileNotFoundError:
        open(histfile, 'wb').close()
        h_len = 0

    def save(prev_h_len, histfile):
        new_h_len = readline.get_current_history_length()
        readline.set_history_length(1000)
        readline.append_history_file(new_h_len - prev_h_len, histfile)
    atexit.register(save, h_len, histfile)

O exemplo a seguir estende a classe `code.InteractiveConsole` para prover salvamento/restauração do histórico.

    import atexit
    import code
    import os
    import readline

    class HistoryConsole(code.InteractiveConsole):
        def __init__(self, locals=None, filename="<console>",
                     histfile=os.path.expanduser("~/.console-history")):
            code.InteractiveConsole.__init__(self, locals, filename)
            self.init_history(histfile)

        def init_history(self, histfile):
            readline.parse_and_bind("tab: complete")
            if hasattr(readline, "read_history_file"):
                try:
                    readline.read_history_file(histfile)
                except FileNotFoundError:
                    pass
                atexit.register(self.save_history, histfile)

        def save_history(self, histfile):
            readline.set_history_length(1000)
            readline.write_history_file(histfile)