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