Nota
¡Ayúdanos a traducir la documentación oficial de Python al Español! Puedes encontrar más información en Como contribuir. Ayuda a acercar Python a más personas de habla hispana.
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()
.
Las combinaciones de teclas de Readline se pueden configurar mediante un archivo de inicialización, generalmente .inputrc
en su directorio de inicio. Consulte Readline Init File en el manual de GNU Readline para obtener información sobre el formato y las construcciones permitidas de ese archivo, y las capacidades de la biblioteca Readline en 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ónread_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ónwrite_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ónappend_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ónhistory_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 esNone
, 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 esNone
, 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 comofunction(text, state)
, para state en0
,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 retornorl_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 retornorl_completion_display_matches_hook
de la biblioteca subyacente. La función de visualización de finalización se llama tal como lafunction(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)