readline
--- GNU readline interface¶
Le module readline
définit des fonctions pour faciliter la complétion et la lecture/écriture des fichiers d'historique depuis l'interpréteur Python. Ce module peut être utilisé directement, ou depuis le module rlcompleter
, qui gère la complétion des mots clefs dans l'invite de commande interactive. Les paramétrages faits en utilisant ce module affectent à la fois le comportement de l'invite de commande interactive et l'invite de commande fournie par la fonction native 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.
Availability: not Android, not iOS, not WASI.
This module is not supported on mobile platforms or WebAssembly platforms.
Note
The underlying Readline library API may be implemented by
the editline
(libedit
) library instead of GNU readline.
On macOS the readline
module detects which library is being used
at run time.
The configuration file for editline
is different from that
of GNU readline. If you programmatically load configuration strings
you can use backend
to determine which library is being used.
If you use editline
/libedit
readline emulation on macOS, the
initialization file located in your home directory is named
.editrc
. For example, the following content in ~/.editrc
will
turn ON vi keybindings and TAB completion:
python:bind -v
python:bind ^I rl_complete
Also note that different libraries may use different history file formats. When switching the underlying library, existing history files may become unusable.
- readline.backend¶
The name of the underlying Readline library being used, either
"readline"
or"editline"
.Ajouté dans la version 3.13.
Fichier d'initialisation¶
Les fonctions suivantes se rapportent au fichier d'initialisation et à la configuration utilisateur :
- readline.parse_and_bind(string)¶
Exécute la ligne d'initialisation fournie dans l'argument string. Cela appelle la fonction
rl_parse_and_bind()
de la bibliothèque sous-jacente.
- readline.read_init_file([filename])¶
Exécute un fichier d'initialisation readline. Le nom de fichier par défaut est le dernier nom de fichier utilisé. Cela appelle la fonction
rl_read_init_file()
de la bibliothèque sous-jacente.
Tampon de ligne¶
Les fonctions suivantes opèrent sur le tampon de ligne :
- readline.get_line_buffer()¶
Renvoie le contenu courant du tampon de ligne (
rl_line_buffer
dans la bibliothèque sous-jacente).
- readline.insert_text(string)¶
Insère du texte dans le tampon de ligne à la position du curseur. Cela appelle la fonction
rl_insert_text()
de la bibliothèque sous-jacente, mais ignore la valeur de retour.
- readline.redisplay()¶
Change ce qui est affiché sur l'écran pour représenter le contenu courant de la ligne de tampon. Cela appelle la fonction
rl_redisplay()
dans la bibliothèque sous-jacente.
Fichier d'historique¶
les fonctions suivantes opèrent sur un fichier d'historique :
- readline.read_history_file([filename])¶
Charge un fichier d'historique de readline, et l'ajoute à la liste d'historique. Le fichier par défaut est
~/.history
. Cela appelle la fonctionread_history()
de la bibliothèque sous-jacente.
- readline.write_history_file([filename])¶
Enregistre la liste de l'historique dans un fichier d'historique de readline, en écrasant un éventuel fichier existant. Le nom de fichier par défaut est
~/.history
. Cela appelle la fonctionwrite_history()
de la bibliothèque sous-jacente.
- readline.append_history_file(nelements[, filename])¶
Ajoute les derniers objets nelements de l'historique dans un fichier. Le nom de fichier par défaut est
~/.history
. Le fichier doit déjà exister. Cela appelle la fonctionappend_history()
de la bibliothèque sous-jacente.Ajouté dans la version 3.5.
- readline.get_history_length()¶
- readline.set_history_length(length)¶
Définit ou renvoie le nombre souhaité de lignes à enregistrer dans le fichier d'historique. La fonction
write_history_file()
utilise cette valeur pour tronquer le fichier d'historique, en appelanthistory_truncate_file()
de la bibliothèque sous-jacente. Les valeurs négatives impliquent une taille de fichier d'historique illimitée.
Liste d'historique¶
Les fonctions suivantes opèrent sur une liste d'historique globale :
- readline.clear_history()¶
Effacer l'historique courant. Cela appelle la fonction
clear_history()
de la bibliothèque sous-jacente. La fonction Python existe seulement si Python à été compilé pour une version de la bibliothèque qui le gère.
- readline.get_current_history_length()¶
Renvoie le nombre d'objets actuellement dans l'historique. (C'est différent de
get_history_length()
, qui renvoie le nombre maximum de lignes qui vont être écrites dans un fichier d'historique.)
- readline.get_history_item(index)¶
Renvoie le contenu courant de l'objet d'historique à index. L'index de l'objet commence à 1. Cela appelle
history_get()
de la bibliothèque sous-jacente.
- readline.remove_history_item(pos)¶
Supprime l'objet de l'historique défini par sa position depuis l'historique. L'index de la position commence à zéro. Cela appelle la fonction
remove_history()
de la bibliothèque sous-jacente.
- readline.replace_history_item(pos, line)¶
Remplace un objet de l'historique à la position définie par line. L'index de la position commence à zéro. Cela appelle
replace_history_entry()
de la bibliothèque sous-jacente.
- readline.add_history(line)¶
Ajoute line au tampon d'historique, comme si c'était la dernière ligne saisie. Cela appelle la fonction
add_history()
de la libraire sous-jacente.
- readline.set_auto_history(enabled)¶
Active ou désactive les appels automatiques à la fonction
add_history()
lors de la lecture d'une entrée via readline. L'argument enabled doit être une valeur booléenne qui lorsqu'elle est vraie, active l'historique automatique, et qui lorsqu'elle est fausse, désactive l'historique automatique.Ajouté dans la version 3.6.
Particularité de l'implémentation CPython : Auto history is enabled by default, and changes to this do not persist across multiple sessions.
Fonctions de rappel au démarrage¶
- readline.set_startup_hook([function])¶
Définit ou supprime la fonction invoquée par le la fonction de retour
rl_startup_hook
de la bibliothèque sous-jacente. Si function est spécifié, il est utilisé en tant que nouvelle fonction de rappel ; si omis ouNone
, toute fonction déjà installée est supprimée. La fonction de rappel est appelée sans arguments juste avant que readline affiche la première invite de commande.
- readline.set_pre_input_hook([function])¶
Définit ou supprime la fonction invoquée par la fonction de retour
rl_pre_input_hook
de la bibliothèque sous-jacente. Si function est spécifié, il sera utilisé par la nouvelle fonction de rappel ; si omis ouNone
, toute fonction déjà installée est supprimée. La fonction de rappel est appelée sans arguments après que la première invite de commande ait été affichée et juste avant que readline commence à lire les caractères saisis. Cette fonction existe seulement si Python a été compilé pour une version de la bibliothèque qui le gère.
Complétion¶
Les fonctions suivantes relatent comment implémenter une fonction de complétion d'un mot spécifique. C'est typiquement déclenché par la touche Tab, et peut suggérer et automatiquement compléter un mot en cours de saisie. Par défaut, Readline est configuré pour être utilisé par rlcompleter
pour compléter les mots clefs de Python pour l'interpréteur interactif. Si le module readline
doit être utilisé avec une complétion spécifique, un ensemble de mots délimiteurs doivent être définis.
- readline.set_completer([function])¶
Définit ou supprime la fonction de complétion. Si function est spécifié, il sera utilisé en tant que nouvelle fonction de complétion; si omis ou
None
, toute fonction de complétion déjà installé est supprimé. La fonction de complétion est appelée telle quefunction(text, state)
, pour state valant0
,1
,2
, ..., jusqu'à ce qu'elle renvoie une valeur qui n'est pas une chaîne de caractères. Elle doit renvoyer les prochaines complétions possibles commençant par text.La fonction de complétion installée est invoquée par la fonction de retour entry_func passée à
rl_completion_matches()
de la bibliothèque sous-jacente. La chaîne de caractère text va du premier paramètres vers la fonction de retourrl_attempted_completion_function
de la bibliothèque sous-jacente.
- readline.get_completer()¶
Récupère la fonction de complétion, ou
None
si aucune fonction de complétion n'a été définie.
- readline.get_completion_type()¶
Récupère le type de complétion essayé. Cela renvoie la variable
rl_completion_type
dans la bibliothèque sous-jacente en tant qu'entier.
- 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()¶
Définit ou récupère les mots délimitants pour la complétion. Ceux-ci déterminent le début du mot devant être considéré pour la complétion (le contexte de la complétion). Ces fonctions accèdent à la variable
rl_completer_word_break_characters
de la bibliothèque sous-jacente.
- readline.set_completion_display_matches_hook([function])¶
Définit ou supprime la fonction d'affichage de la complétion. Si function est spécifié, il sera utilisé en tant que nouvelle fonction d'affichage de complétion; si omis ou
None
, toute fonction de complétion déjà installée est supprimée. Cela définit ou supprime la fonction de retourrl_completion_display_matches_hook
dans la bibliothèque sous-jacente. La fonction d'affichage de complétion est appelée telle quefunction(substitution, [matches], longest_match_length)
une seule fois lorsque les correspondances doivent être affichées.
Exemple¶
L'exemple suivant démontre comment utiliser les fonctions de lecture et d'écriture de l'historique du module readline
pour charger ou sauvegarder automatiquement un fichier d'historique nommé .python_history
depuis le répertoire d’accueil de l’utilisateur. Le code ci-dessous doit normalement être exécuté automatiquement durant une session interactive depuis le fichier de l'utilisateur 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)
Ce code est en réalité automatiquement exécuté lorsque Python tourne en mode interactif (voir Readline configuration).
L'exemple suivant atteint le même objectif mais gère des sessions interactives concurrentes, en ajoutant seulement le nouvel historique.
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)
L'exemple suivant étend la classe code.InteractiveConsole
pour gérer la sauvegarde/restauration de l'historique.
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)