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

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.

Nota

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

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)

Execute the init line provided in the string argument. This calls rl_parse_and_bind() in the underlying library.

readline.read_init_file([filename])

Execute a readline initialization file. The default filename is the last filename used. This calls rl_read_init_file() in the underlying library.

Buffer de linha

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

readline.get_line_buffer()

Return the current contents of the line buffer (rl_line_buffer in the underlying library).

readline.insert_text(string)

Insert text into the line buffer at the cursor position. This calls rl_insert_text() in the underlying library, but ignores the return value.

readline.redisplay()

Change what’s displayed on the screen to reflect the current contents of the line buffer. This calls rl_redisplay() in the underlying library.

Arquivo de histórico

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

readline.read_history_file([filename])

Load a readline history file, and append it to the history list. The default filename is ~/.history. This calls read_history() in the underlying library.

readline.write_history_file([filename])

Save the history list to a readline history file, overwriting any existing file. The default filename is ~/.history. This calls write_history() in the underlying library.

readline.append_history_file(nelements[, filename])

Append the last nelements items of history to a file. The default filename is ~/.history. The file must already exist. This calls append_history() in the underlying library. This function only exists if Python was compiled for a version of the library that supports it.

Adicionado na versão 3.5.

readline.get_history_length()
readline.set_history_length(length)

Set or return the desired number of lines to save in the history file. The write_history_file() function uses this value to truncate the history file, by calling history_truncate_file() in the underlying library. Negative values imply unlimited history file size.

Lista de histórico

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

readline.clear_history()

Clear the current history. This calls clear_history() in the underlying library. The Python function only exists if Python was compiled for a version of the library that supports it.

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)

Return the current contents of history item at index. The item index is one-based. This calls history_get() in the underlying library.

readline.remove_history_item(pos)

Remove history item specified by its position from the history. The position is zero-based. This calls remove_history() in the underlying library.

readline.replace_history_item(pos, line)

Replace history item specified by its position with line. The position is zero-based. This calls replace_history_entry() in the underlying library.

readline.add_history(line)

Append line to the history buffer, as if it was the last line typed. This calls add_history() in the underlying library.

readline.set_auto_history(enabled)

Enable or disable automatic calls to add_history() when reading input via readline. The enabled argument should be a Boolean value that when true, enables auto history, and that when false, disables auto history.

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

Set or remove the function invoked by the rl_startup_hook callback of the underlying library. If function is specified, it will be used as the new hook function; if omitted or None, any function already installed is removed. The hook is called with no arguments just before readline prints the first prompt.

readline.set_pre_input_hook([function])

Set or remove the function invoked by the rl_pre_input_hook callback of the underlying library. If function is specified, it will be used as the new hook function; if omitted or None, any function already installed is removed. The hook is called with no arguments after the first prompt has been printed and just before readline starts reading input characters. This function only exists if Python was compiled for a version of the library that supports it.

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.

The installed completer function is invoked by the entry_func callback passed to rl_completion_matches() in the underlying library. The text string comes from the first parameter to the rl_attempted_completion_function callback of the underlying library.

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

Get the type of completion being attempted. This returns the rl_completion_type variable in the underlying library as an integer.

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. The values may be different in the same input editing scenario based on the underlying C readline implementation. Ex: libedit is known to behave differently than libreadline.

readline.set_completer_delims(string)
readline.get_completer_delims()

Set or get the word delimiters for completion. These determine the start of the word to be considered for completion (the completion scope). These functions access the rl_completer_word_break_characters variable in the underlying library.

readline.set_completion_display_matches_hook([function])

Set or remove the completion display function. If function is specified, it will be used as the new completion display function; if omitted or None, any completion display function already installed is removed. This sets or clears the rl_completion_display_matches_hook callback in the underlying library. The completion display function is called as function(substitution, [matches], longest_match_length) once each time matches need to be displayed.

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