readline — Interfaz readline de GNU

---

El módulo readline define una serie de funciones para facilitar la finalización y lectura/escritura de archivos de historial desde el intérprete de Python. Este módulo se puede usar directamente o mediante el módulo rlcompleter, que administra la finalización de identificadores de Python en la solicitud interactiva. Los ajustes realizados con este módulo afectan el comportamiento tanto del aviso interactivo del intérprete como de los avisos ofrecidos por la función incorporada 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

La API de la biblioteca utilizada por Readline puede implementarse mediante la biblioteca libedit en lugar de readline de GNU. En macOS, el módulo readline detecta qué biblioteca se está utilizando en tiempo de ejecución.

El archivo de configuración para libedit es diferente del readline de GNU. Si carga cadenas de caracteres de configuración mediante programación, puede verificar el texto «libedit» en readline.__ doc__ para diferenciar entre readline de GNU y libedit.

Si usa emulación readline editline/libedit en macOS, el archivo de inicialización ubicado en su directorio de inicio se llama .editrc. Por ejemplo, el siguiente contenido en ~/.editrc activa atajos del teclado de vi y completado con TAB:

python:bind -v
python:bind ^I rl_complete

Archivo de inicio

Las siguientes funciones se relacionan con el archivo de inicio y la configuración del usuario:

readline.parse_and_bind(string)

Ejecuta la línea de inicio proporcionada en el argumento string. Esto llama a la función rl_parse_and_bind() de la biblioteca subyacente.

readline.read_init_file([filename])

Ejecuta un archivo de inicialización readline. El nombre de archivo predeterminado es el último nombre de archivo utilizado. Esto llama a la función rl_read_init_file() de la biblioteca subyacente.

Búfer de línea

Las siguientes funciones operan en el búfer de línea:

readline.get_line_buffer()

Retorna el contenido actual del búfer de línea (rl_line_buffer en la biblioteca subyacente).

readline.insert_text(string)

Inserta texto en el búfer de línea en la posición del cursor. Esto llama a la función rl_insert_text() de la biblioteca subyacente, pero ignora el valor de retorno.

readline.redisplay()

Cambia lo que se muestra en la pantalla para reflejar el contenido actual del búfer de línea. Esto llama a la función rl_redisplay() de la biblioteca subyacente.

Archivo de historial

Las siguientes funciones operan en un archivo de historial:

readline.read_history_file([filename])

Carga un archivo de historial readline y lo adjunta a la lista de historial. El nombre de archivo predeterminado es ~/.history. Esto llama a la función read_history() de la biblioteca subyacente.

readline.write_history_file([filename])

Guarda la lista de historial en un archivo de historial readline, sobrescribiendo cualquier archivo existente. El nombre de archivo predeterminado es ~/.history. Esto llama a la función write_history() de la biblioteca subyacente.

readline.append_history_file(nelements[, filename])

Agrega los últimos nelements del historial a un archivo. El nombre de archivo predeterminado es ~/.history. El archivo ya debe existir. Esto llama a la función append_history() de la biblioteca subyacente. Esta función solo existe si Python se compiló para una versión de la biblioteca que lo admita.

Nuevo en la versión 3.5.

readline.get_history_length()

readline.set_history_length(length)

Establece o retorna el número deseado de líneas para guardar en el archivo de historial. La función write_history_file() usa este valor para truncar el archivo de historial, llamando a la función history_truncate_file() en la biblioteca subyacente. Los valores negativos implican un tamaño de archivo de historial ilimitado.

Lista del historial

Las siguientes funciones operan en una lista de historial global:

readline.clear_history()

Borra el historial actual. Esto llama a la función clear_history() en la biblioteca subyacente. La función de Python solo existe si Python se compiló para una versión de la biblioteca que lo admita.

readline.get_current_history_length()

Retorna el número de elementos actuales en el historial. (Esto es diferente de la función get_history_length(), que retorna el número máximo de líneas que se escribirán en un archivo de historial).

readline.get_history_item(index)

Retorna el contenido actual de historial en index. El índice comienza en 1. Esto llama a la función history_get() en la biblioteca subyacente.

readline.remove_history_item(pos)

Elimina el objeto del historial definido por su posición del historial. La posición comienza en cero. Esto llama a la función remove_history() en la biblioteca subyacente.

readline.replace_history_item(pos, line)

Reemplaza el elemento del historial especificado por su posición con line. La posición comienza en cero. Esto llama a la función replace_history_entry() en la biblioteca subyacente.

readline.add_history(line)

Agrega line al búfer de historial, como si fuera la última línea escrita. Esto llama a la función add_history() en la biblioteca subyacente.

readline.set_auto_history(enabled)

Habilita o deshabilita las llamadas automáticas a la función add_history() al leer la entrada a través de readline. El argumento enabled debe ser un valor booleano que cuando es verdadero, habilita el historial automático, y que cuando es falso, desactiva el historial automático.

Nuevo en la versión 3.6.

Detalles de implementación de CPython: Auto history está habilitado de forma predeterminada, y cambiarlo no hará que persista en múltiples sesiones.

Ganchos (hooks) de inicialización

readline.set_startup_hook([function])

Establece o elimina la función invocada por la función de retorno rl_startup_hook de la biblioteca subyacente. Si se especifica function, se utilizará como la nueva función de enlace; Si se omite o es None, se elimina cualquier función ya instalada. La función de devolución de llamada se llama sin argumentos justo antes de que readline muestre el primer símbolo del sistema.

readline.set_pre_input_hook([function])

Establece o elimina la función invocada por la función de retorno rl_pre_input_hook de la biblioteca subyacente. Si se especifica function, se utilizará como la nueva función de devolución de llamada; Si se omite o es None, se elimina cualquier función ya instalada. La función de devolución de llamada se llama sin argumentos después de que se haya visualizado el primer símbolo del sistema y justo antes de que readline comience a leer los caracteres ingresados. Esta función solo existe si Python se ha compilado para una versión de la biblioteca que lo admite.

Terminación

Las siguientes funciones se relacionan con la implementación de una función de finalización de palabra personalizada. Esto típicamente es operado por la tecla Tab y puede sugerir y completar automáticamente una palabra que se está escribiendo. Por defecto, Readline está configurado para ser utilizado por rlcompleter para completar los identificadores de Python para el intérprete interactivo. Si el módulo readline se va a utilizar con una terminación específica, se debe definir un conjunto de palabras delimitadoras.

readline.set_completer([function])

Establece o elimina la función de finalización. Si se especifica function, se usará como la nueva función de finalización; Si se omite o es None, se elimina cualquier función de finalización ya instalada. La función completa se llama como function(text, state), para state en 0, 1, 2, …, hasta que retorna un valor que no es una cadena de caracteres. Debería retornar las siguientes terminaciones posibles comenzando con text.

La función de finalización instalada es invocada por la función de retorno entry_func que se pasa a rl_completion_matches() en la biblioteca subyacente. La cadena de texto va desde el primer parámetro a la función de retorno rl_attempted_completion_function de la biblioteca subyacente.

readline.get_completer()

Obtiene la función de finalización o None si no se ha definido ninguna función de finalización.

readline.get_completion_type()

Obtiene el tipo de finalización que se está intentando. Esto retorna la variable rl_completion_type en la biblioteca subyacente como un entero.

readline.get_begidx()

readline.get_endidx()

Obtenga el índice inicial o final del alcance de finalización. Estos índices son los argumentos start y end pasados a la devolución de llamada rl_attempted_completion_function de la biblioteca subyacente. Los valores pueden ser diferentes en el mismo escenario de edición de entrada según la implementación de la línea de lectura de C subyacente. Ejemplo: se sabe que libedit se comporta de manera diferente a libreadline.

readline.set_completer_delims(string)

readline.get_completer_delims()

Define o recupera palabras delimitadoras para completar. Estos determinan el comienzo de la palabra que se considerará para su finalización (el contexto de finalización). Estas funciones acceden a la variable rl_completer_word_break_characters desde la biblioteca subyacente.

readline.set_completion_display_matches_hook([function])

Establece o elimina la función de visualización de finalización. Si se especifica function, se utilizará como una nueva función de visualización de finalización; si se omite o es None, se elimina cualquier función de finalización ya instalada. Esto establece o elimina la función de retorno rl_completion_display_matches_hook de la biblioteca subyacente. La función de visualización de finalización se llama tal como la function(substitution, [matches], longest_match_length) solo una vez cuando se muestran las coincidencias.

Ejemplo

El siguiente ejemplo muestra cómo usar las funciones de lectura y escritura del historial del módulo readline para cargar o guardar automáticamente un archivo de historial llamado .python_history desde el directorio de inicio del usuario. El siguiente código normalmente debe ejecutarse automáticamente durante una sesión interactiva desde el archivo de usuario PYTHONSTARTUP.

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)

Este código se ejecuta automáticamente cuando Python se ejecuta en modo interactivo (ver Configuración de Readline).

El siguiente ejemplo logra el mismo objetivo pero administra sesiones interactivas concurrentes, agregando solo el nuevo historial.

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)

El siguiente ejemplo amplía la clase code.InteractiveConsole para administrar el guardado/restauración del historial.

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)