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