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