# `readline` — Interface para o GNU readline

The `readline` module defines a number of functions to facilitate completion and reading/writing of history files from the Python interpreter. This module can be used directly, or via the `rlcompleter` module, which supports completion of Python identifiers at the interactive prompt. Settings made using this module affect the behaviour of both the interpreter’s interactive prompt and the prompts offered by the built-in `input()` function.

As combinações de teclas do Readline podem ser configuradas através de um arquivo de inicialização, normalmente `.inputrc` em seu diretório inicial. Consulte Readline Init File no manual do GNU Readline para obter informações sobre o formato e construções permitidas desse arquivo e os recursos da biblioteca do Readline em geral.

Disponibilidade: not Android, not iOS, not WASI.

Este módulo não tem suporte em plataformas móveis ou plataformas WebAssembly.

Este é um módulo opcional. Se ele estiver faltando na sua cópia do CPython, procure a documentação do seu distribuidor (ou seja, quem lhe forneceu o Python). Se você for o distribuidor, consulte Requisitos para módulos opcionais.

Disponibilidade: Unix.

Nota

The underlying Readline library API may be implemented by the `editline` (`libedit`) library instead of GNU readline. On macOS the `readline` module detects which library is being used at run time.

O arquivo de configuração do `editline` é diferente daquele do GNU readline. Se você carregar strings de configuração programaticamente, você pode usar `backend` para determinar qual biblioteca está sendo usada.

Se você usar a emulação de readline do `editline`/`libedit` no macOS, o arquivo de inicialização localizado em seu diretório inicial será denominado `.editrc`. Por exemplo, o seguinte conteúdo em `~/.editrc` ativará os atalhos de teclado vi e o autocomplemento de TAB:

    python:bind -v
    python:bind ^I rl_complete

Observe também que bibliotecas diferentes podem usar formatos de arquivo de histórico diferentes. Ao alternar a biblioteca subjacente, os arquivos de histórico existentes podem se tornar inutilizáveis.

readline.backend

  O nome da biblioteca Readline subjacente que está sendo usada, seja `"readline"` ou `"editline"`.

  Adicionado na versão 3.13.

## 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 readline. O nome de arquivo padrão é o último usado. Isso chama `rl_read_init_file()` na biblioteca subjacente. Ele levanta um evento de auditoria `open` com o nome do arquivo, se fornecido, e `"<readline_init_file>"` caso contrário, independentemente de qual arquivo a biblioteca resolve.

  Alterado na versão 3.14: O evento de auditoria foi adicionado.

## 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 e levanta um evento de auditoria `open` com o nome de arquivo se dado e, do contrário, `"~/.history"`.

  Alterado na versão 3.14: O evento de auditoria foi adicionado.

readline.write_history_file([filename])

  Salva a lista de histórico para um arquivo de histórico do readline, sobrescrevendo qualquer arquivo existente. O nome do arquivo padrão é `~/.history`. Isso chama `write_history()` na biblioteca subjacente e levanta um evento de auditoria `open` com o nome de arquivo se dado e, do contrário, `"~/.history"`.

  Alterado na versão 3.14: O evento de auditoria foi adicionado.

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. Ela levanta um evento de auditoria `open` com o nome de arquivo se dado e, do contrário, `"~/.history"`.

  Adicionado na versão 3.5.

  Alterado na versão 3.14: O evento de auditoria foi adicionado.

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.

  Adicionado na versão 3.6.

  O histórico automático está ativado por padrão e as alterações não persistem em várias sessões.

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

readline.get_pre_input_hook()

  Get the current pre-input hook function, or `None` if no pre-input hook function has been set. This function only exists if Python was compiled for a version of the library that supports it.

  Adicionado na versão 3.15.

## Autocomplemento

The following functions relate to implementing a custom word completion function. This is typically operated by the Tab key, and can suggest and automatically complete a word being typed. By default, Readline is set up to be used by `rlcompleter` to complete Python identifiers for the interactive interpreter. If the `readline` module is to be used with a custom completer, a different set of word delimiters should be set.

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

  Obtém o índice inicial ou final do escopo de autocomplemento. Esses índices são os argumentos start e end passados para o retorno de chamada `rl_attempted_completion_function` da biblioteca subjacente. Os valores podem ser diferentes no mesmo cenário de edição de entrada com base na implementação de C readline subjacente. Por exemplo, sabe-se que o libedit se comporta de maneira diferente do libreadline.

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, [matches], longest_match_length)` uma vez que cada correspondência precisa ser exibida.

## Exemplo

The following example demonstrates how to use the `readline` module’s history reading and writing functions to automatically load and save a history file named `.python_history` from the user’s home directory. The code below would normally be executed automatically during interactive sessions from the user’s `PYTHONSTARTUP` file.

    import atexit
    import os
    import readline

    histfile = os.path.join(os.path.expanduser("~"), ".python_history")
    try:
        readline.read_history_file(histfile)
        # comprimento padrão do histórico é -1 (infinito), que pode crescer sem controle
        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)

Nota

O novo REPL introduzido na versão 3.13 não oferece suporte a readline. No entanto, readline ainda pode ser usado definindo a variável de ambiente `PYTHON_BASIC_REPL`.