16.8. "readline" — interface pour GNU *readline*
************************************************

The "readline" module defines a number of functions to facilitate
completion and reading/writing of history files from the Python
interpreter. This module can be used directly, or via the
"rlcompleter" module, which supports completion of Python identifiers
at the interactive prompt.  Settings made using  this module affect
the behaviour of both the interpreter’s interactive prompt  and the
prompts offered by the "raw_input()" and "input()" built-in functions.

Note: The underlying Readline library API may be implemented by the
  "libedit" library instead of GNU readline. On MacOS X the "readline"
  module detects which library is being used at run time.Le fichier de
  configuration pour *libedit* est différent de celui de *GNU
  readline*. Si, dans votre programme, vous chargez les chaines de
  configuration vous pouvez valider le texte *libedit* dans
  "readline.__doc__" pour faire la différence entre *GNU readline* et
  *libedit*.

L’association de touches de *readline* peut être configurée via un
fichier d’initialisation, typiquement nommé ".inputrc" dans votre
répertoire utilisateur. Voir Readline Init File dans le manuel GNU
pour *readline* pour des information à propos du format et de la
construction autorisée de ce fichier, ainsi que les possibilités de la
bibliothèque *readline* en général.


16.8.1. 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.


16.8.2. 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.


16.8.3. 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 fonction "read_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 fonction
   "write_history()" de la bibliothèque sous-jacente.

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 appelant
   "history_truncate_file()" de la bibliothèque sous-jacente. Les
   valeurs négatives impliquent une taille de fichier d’historique
   illimitée.


16.8.4. 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.

   Nouveau dans la version 2.4.

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

   Nouveau dans la version 2.3.

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.

   Nouveau dans la version 2.3.

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.

   Nouveau dans la version 2.4.

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.

   Nouveau dans la version 2.4.

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.


16.8.5. Fonctions de rappel au démarrage
========================================

   Nouveau dans la version 2.3.

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 ou "None", 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 ou "None", 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.


16.8.6. 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
   que "function(text, state)", pour *state* valant "0", "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 retour
   "rl_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.

   Nouveau dans la version 2.3.

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.

   Nouveau dans la version 2.6.

readline.get_begidx()
readline.get_endidx()

   Récupère l’indexe de début ou de fin d’un contexte de complétion.
   Ces indexes sont les arguments *start* et *end* passés à la
   fonction de retour "rl_attempted_completion_function" de la
   bibliothèque sous-jacente.

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 retour
   "rl_completion_display_matches_hook" dans la bibliothèque sous-
   jacente. La fonction d’affichage de complétion est appelée telle
   que "function(substitution, [matches], longest_match_length)" une
   seule fois lorsque les correspondances doivent être affichées.

   Nouveau dans la version 2.6.


16.8.7. Exemple
===============

The following example demonstrates how to use the "readline" module’s
history reading and writing functions to automatically load and save a
history file named ".pyhist" from the user’s home directory.  The code
below would normally be executed automatically during interactive
sessions from the user’s "PYTHONSTARTUP" file.

   import os
   import readline
   histfile = os.path.join(os.path.expanduser("~"), ".pyhist")
   try:
       readline.read_history_file(histfile)
       # default history len is -1 (infinite), which may grow unruly
       readline.set_history_length(1000)
   except IOError:
       pass
   import atexit
   atexit.register(readline.write_history_file, histfile)
   del os, histfile

L’exemple suivant étend la classe "code.InteractiveConsole" pour gérer
la sauvegarde/restauration de l’historique. :

   import code
   import readline
   import atexit
   import os

   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 IOError:
                   pass
               atexit.register(self.save_history, histfile)

       def save_history(self, histfile):
           readline.set_history_length(1000)
           readline.write_history_file(histfile)
