readline — GNU readline-Schnittstelle

---

Das Modul readline definiert eine Reihe von Funktionen zur Erleichterung der Vervollständigung und des Lesens/Schreibens von Verlaufsdateien aus dem Python-Interpreter. Dieses Modul kann direkt oder über das Modul rlcompleter verwendet werden, das die Vervollständigung von Python-Bezeichnern an der interaktiven Eingabeaufforderung unterstützt. Einstellungen, die mit diesem Modul vorgenommen werden, wirken sich auf das Verhalten sowohl der interaktiven Eingabeaufforderung des Interpreters als auch auf die durch die eingebaute Funktion input() angebotenen Eingabeaufforderungen aus.

Readline-Tastenkombinationen können über eine Initialisierungsdatei konfiguriert werden, typischerweise .inputrc in Ihrem Home-Verzeichnis. Informationen über das Format und zulässige Konstrukte dieser Datei sowie die Fähigkeiten der Readline-Bibliothek im Allgemeinen finden Sie unter Readline Init File im GNU Readline-Handbuch.

Verfügbarkeit: nicht Android, nicht iOS, nicht WASI.

Dieses Modul wird auf mobilen Plattformen oder WebAssembly-Plattformen nicht unterstützt.

Hinweis

Die zugrunde liegende Readline-Bibliotheks-API kann durch die Bibliothek editline (libedit) anstelle von GNU readline implementiert werden. Unter macOS erkennt das Modul readline zur Laufzeit, welche Bibliothek verwendet wird.

Die Konfigurationsdatei für editline unterscheidet sich von der von GNU readline. Wenn Sie Konfigurationsstrings programmgesteuert laden, können Sie backend verwenden, um festzustellen, welche Bibliothek verwendet wird.

Wenn Sie unter macOS die Emulation von editline/libedit readline verwenden, heißt die Initialisierungsdatei in Ihrem Home-Verzeichnis .editrc. Zum Beispiel schaltet der folgende Inhalt in ~/.editrc die vi-Tastenkombinationen und die TAB-Vervollständigung EIN.

python:bind -v
python:bind ^I rl_complete

Beachten Sie auch, dass verschiedene Bibliotheken unterschiedliche Verlaufsdateiformate verwenden können. Beim Wechseln der zugrunde liegenden Bibliothek können vorhandene Verlaufsdateien unbrauchbar werden.

readline.backend

Der Name der zugrunde liegenden Readline-Bibliothek, die verwendet wird, entweder "readline" oder "editline".

Hinzugefügt in Version 3.13.

Initialisierungsdatei

Die folgenden Funktionen beziehen sich auf die Initialisierungsdatei und die Benutzerkonfiguration

readline.parse_and_bind(string)

Führt die in string bereitgestellte Initialisierungszeile aus. Dies ruft rl_parse_and_bind() in der zugrunde liegenden Bibliothek auf.

readline.read_init_file([filename])

Führt eine Readline-Initialisierungsdatei aus. Der Standarddateiname ist der zuletzt verwendete Dateiname. Dies ruft rl_read_init_file() in der zugrunde liegenden Bibliothek auf. Sie löst ein Audit-Ereignis open mit dem Dateinamen aus, wenn dieser angegeben ist, andernfalls "<readline_init_file>", unabhängig davon, welche Datei die Bibliothek auflöst.

Geändert in Version 3.14: Das Audit-Ereignis wurde hinzugefügt.

Zeilenpuffer

Die folgenden Funktionen arbeiten auf dem Zeilenpuffer

readline.get_line_buffer()

Gibt den aktuellen Inhalt des Zeilenpuffers zurück (rl_line_buffer in der zugrunde liegenden Bibliothek).

readline.insert_text(string)

Fügt Text an der Cursorposition in den Zeilenpuffer ein. Dies ruft rl_insert_text() in der zugrunde liegenden Bibliothek auf, ignoriert aber den Rückgabewert.

readline.redisplay()

Ändert die Anzeige auf dem Bildschirm, um den aktuellen Inhalt des Zeilenpuffers widerzuspiegeln. Dies ruft rl_redisplay() in der zugrunde liegenden Bibliothek auf.

Verlaufsdatei

Die folgenden Funktionen arbeiten auf einer Verlaufsdatei

readline.read_history_file([filename])

Lädt eine Readline-Verlaufsdatei und hängt sie an die Verlaufsliste an. Der Standarddateiname ist ~/.history. Dies ruft read_history() in der zugrunde liegenden Bibliothek auf und löst ein Audit-Ereignis open mit dem Dateinamen aus, wenn dieser angegeben ist, andernfalls "~/.history".

Geändert in Version 3.14: Das Audit-Ereignis wurde hinzugefügt.

readline.write_history_file([filename])

Speichert die Verlaufsliste in einer Readline-Verlaufsdatei und überschreibt dabei eine eventuell vorhandene Datei. Der Standarddateiname ist ~/.history. Dies ruft write_history() in der zugrunde liegenden Bibliothek auf und löst ein Audit-Ereignis open mit dem Dateinamen aus, wenn dieser angegeben ist, andernfalls "~/.history".

Geändert in Version 3.14: Das Audit-Ereignis wurde hinzugefügt.

readline.append_history_file(nelements[, filename])

Hängt die letzten nelements Elemente des Verlaufs an eine Datei an. Der Standarddateiname ist ~/.history. Die Datei muss bereits existieren. Dies ruft append_history() in der zugrunde liegenden Bibliothek auf. Diese Funktion existiert nur, wenn Python für eine Version der Bibliothek kompiliert wurde, die sie unterstützt. Sie löst ein Audit-Ereignis open mit dem Dateinamen aus, wenn dieser angegeben ist, andernfalls "~/.history".

Hinzugefügt in Version 3.5.

Geändert in Version 3.14: Das Audit-Ereignis wurde hinzugefügt.

readline.get_history_length()

readline.set_history_length(length)

Setzt oder gibt die gewünschte Anzahl von Zeilen zurück, die in der Verlaufsdatei gespeichert werden sollen. Die Funktion write_history_file() verwendet diesen Wert, um die Verlaufsdatei zu kürzen, indem history_truncate_file() in der zugrunde liegenden Bibliothek aufgerufen wird. Negative Werte bedeuten unbegrenzte Größe der Verlaufsdatei.

Verlaufsliste

Die folgenden Funktionen arbeiten auf einer globalen Verlaufsliste

readline.clear_history()

Löscht den aktuellen Verlauf. Dies ruft clear_history() in der zugrunde liegenden Bibliothek auf. Die Python-Funktion existiert nur, wenn Python für eine Version der Bibliothek kompiliert wurde, die sie unterstützt.

readline.get_current_history_length()

Gibt die Anzahl der Elemente zurück, die sich derzeit im Verlauf befinden. (Dies unterscheidet sich von get_history_length(), das die maximale Anzahl von Zeilen zurückgibt, die in eine Verlaufsdatei geschrieben werden.)

readline.get_history_item(index)

Gibt den aktuellen Inhalt des Verlaufsdatensatzes am index zurück. Der Index ist eins-basiert. Dies ruft history_get() in der zugrunde liegenden Bibliothek auf.

readline.remove_history_item(pos)

Entfernt den durch seine Position angegebenen Verlaufsdatensatz aus dem Verlauf. Die Position ist nullbasiert. Dies ruft remove_history() in der zugrunde liegenden Bibliothek auf.

readline.replace_history_item(pos, line)

Ersetzt den durch seine Position angegebenen Verlaufsdatensatz durch line. Die Position ist nullbasiert. Dies ruft replace_history_entry() in der zugrunde liegenden Bibliothek auf.

readline.add_history(line)

Hängt line an den Verlaufsbuffer an, als ob es die letzte eingegebene Zeile wäre. Dies ruft add_history() in der zugrunde liegenden Bibliothek auf.

readline.set_auto_history(enabled)

Aktiviert oder deaktiviert automatische Aufrufe von add_history() beim Lesen von Eingaben über readline. Das Argument enabled sollte ein boolescher Wert sein, der bei True die automatische Verlaufsfunktion aktiviert und bei False deaktiviert.

Hinzugefügt in Version 3.6.

CPython-Implementierungsdetail: Auto-History ist standardmäßig aktiviert, und Änderungen daran bleiben über mehrere Sitzungen hinweg nicht erhalten.

Start-Hooks

readline.set_startup_hook([function])

Setzt oder entfernt die Funktion, die vom Rückruf rl_startup_hook der zugrunde liegenden Bibliothek aufgerufen wird. Wenn function angegeben ist, wird sie als neue Hook-Funktion verwendet; wenn sie weggelassen oder None ist, wird jede bereits installierte Funktion entfernt. Der Hook wird ohne Argumente aufgerufen, kurz bevor readline die erste Eingabeaufforderung ausgibt.

readline.set_pre_input_hook([function])

Setzt oder entfernt die Funktion, die vom Rückruf rl_pre_input_hook der zugrunde liegenden Bibliothek aufgerufen wird. Wenn function angegeben ist, wird sie als neue Hook-Funktion verwendet; wenn sie weggelassen oder None ist, wird jede bereits installierte Funktion entfernt. Der Hook wird ohne Argumente aufgerufen, nachdem die erste Eingabeaufforderung ausgegeben wurde und kurz bevor readline beginnt, Eingabezeichen zu lesen. Diese Funktion existiert nur, wenn Python für eine Version der Bibliothek kompiliert wurde, die sie unterstützt.

Vervollständigung

Die folgenden Funktionen beziehen sich auf die Implementierung einer benutzerdefinierten Wortvervollständigungsfunktion. Dies wird normalerweise durch die Tab-Taste ausgelöst und kann ein eingegebenes Wort vorschlagen und automatisch vervollständigen. Standardmäßig ist Readline so eingerichtet, dass es von rlcompleter zur Vervollständigung von Python-Bezeichnern für den interaktiven Interpreter verwendet wird. Wenn das Modul readline mit einem benutzerdefinierten Vervollständiger verwendet werden soll, sollten andere Wortbegrenzer festgelegt werden.

readline.set_completer([function])

Setzt oder entfernt die Vervollständigungsfunktion. Wenn function angegeben ist, wird sie als neue Vervollständigungsfunktion verwendet; wenn sie weggelassen oder None ist, wird jede bereits installierte Vervollständigungsfunktion entfernt. Die Vervollständigungsfunktion wird als function(text, state) für state in 0, 1, 2, … aufgerufen, bis sie einen Wert zurückgibt, der kein String ist. Sie sollte die nächste mögliche Vervollständigung zurückgeben, die mit text beginnt.

Die installierte Vervollständigungsfunktion wird durch den Rückruf entry_func aufgerufen, der an rl_completion_matches() in der zugrunde liegenden Bibliothek übergeben wird. Der String text stammt vom ersten Parameter des Rückrufs rl_attempted_completion_function der zugrunde liegenden Bibliothek.

readline.get_completer()

Ruft die Vervollständigungsfunktion ab oder None, wenn keine Vervollständigungsfunktion festgelegt wurde.

readline.get_completion_type()

Ruft den Typ der gerade versuchten Vervollständigung ab. Dies gibt die Variable rl_completion_type in der zugrunde liegenden Bibliothek als Ganzzahl zurück.

readline.get_begidx()

readline.get_endidx()

Ruft den Start- oder Endindex des Vervollständigungsbereichs ab. Diese Indizes sind die start- und end-Argumente, die an den Rückruf rl_attempted_completion_function der zugrunde liegenden Bibliothek übergeben werden. Die Werte können im selben Eingabebearbeitungsszenario basierend auf der zugrunde liegenden C-Readline-Implementierung unterschiedlich sein. Z.B. ist bekannt, dass libedit anders funktioniert als libreadline.

readline.set_completer_delims(string)

readline.get_completer_delims()

Legt die Wortbegrenzer für die Vervollständigung fest oder ruft sie ab. Diese bestimmen den Anfang des Wortes, das für die Vervollständigung berücksichtigt werden soll (der Vervollständigungsbereich). Diese Funktionen greifen auf die Variable rl_completer_word_break_characters in der zugrunde liegenden Bibliothek zu.

readline.set_completion_display_matches_hook([function])

Setzt oder entfernt die Anzeige der Vervollständigungsfunktion. Wenn function angegeben ist, wird sie als neue Vervollständigungsanzeigefunktion verwendet; wenn sie weggelassen oder None ist, wird jede bereits installierte Vervollständigungsanzeigefunktion entfernt. Dies setzt oder löscht den Rückruf rl_completion_display_matches_hook in der zugrunde liegenden Bibliothek. Die Vervollständigungsanzeigefunktion wird als function(substitution, [matches], longest_match_length) einmal jedes Mal aufgerufen, wenn Übereinstimmungen angezeigt werden müssen.

Beispiel

Das folgende Beispiel zeigt, wie die Funktionen zum Lesen und Schreiben von Verläufen des Moduls readline verwendet werden, um eine Verlaufsdatei namens .python_history aus dem Home-Verzeichnis des Benutzers automatisch zu laden und zu speichern. Der folgende Code würde normalerweise während interaktiver Sitzungen aus der PYTHONSTARTUP-Datei des Benutzers ausgeführt werden.

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)

Dieser Code wird tatsächlich automatisch ausgeführt, wenn Python im interaktiven Modus ausgeführt wird (siehe Readline-Konfiguration).

Das folgende Beispiel erreicht dasselbe Ziel, unterstützt aber gleichzeitige interaktive Sitzungen, indem nur der neue Verlauf angehängt wird.

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)

Das folgende Beispiel erweitert die Klasse code.InteractiveConsole, um das Speichern/Wiederherstellen des Verlaufs zu unterstützen.

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)