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

Note:

  L'API de la bibliothèque utilisée par *readline* peut être
  implémentée par la bibliothèque "libedit" au lieu de *GNU readline*.
  Sur MacOS le module "readline" détecte quelle bibliothèque est
  utilisée au cours de l'exécution du programme.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*.Si vous utilisez l'émulation *editline*/"libedit" sur
  MacOS, le fichier d'initialisation situé dans votre répertoire
  d’accueil est appelé ".editrc". Par exemple, le contenu suivant dans
  "~/.editrc" active l'association de touches *vi*  et la complétion
  avec la touche de tabulation :

     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.


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 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.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 fonction "append_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 appelant
   "history_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 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.


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.

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


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)
