readline — GNU:s gränssnitt för readline

Modulen readline definierar ett antal funktioner för att underlätta komplettering och läsning/skrivning av historikfiler från Python-tolken. Den här modulen kan användas direkt eller via modulen rlcompleter, som stöder komplettering av Python-identifierare i den interaktiva prompten. Inställningar som görs med denna modul påverkar beteendet hos både tolkens interaktiva prompt och de prompter som erbjuds av den inbyggda funktionen input().

Readlines tangentbindningar kan konfigureras via en initialiseringsfil, vanligtvis .inputrc i din hemkatalog. Se Readline Init File i GNU Readline-manualen för information om formatet och tillåtna konstruktioner i den filen, och Readline-bibliotekets möjligheter i allmänhet.

Tillgänglighet: not Android, not iOS, not WASI.

Denna modul stöds inte på mobile platforms eller WebAssembly platforms.

Anteckning

Det underliggande API:et för Readline-biblioteket kan implementeras av biblioteket editline (libedit) istället för GNU readline. På macOS upptäcker modulen readline vilket bibliotek som används vid körning.

Konfigurationsfilen för editline skiljer sig från den för GNU readline. Om du laddar konfigurationssträngar programmatiskt kan du använda backend för att avgöra vilket bibliotek som används.

Om du använder editline/libedit readline-emulering på macOS heter initialiseringsfilen i din hemkatalog .editrc. Till exempel kommer följande innehåll i ~/.editrc att aktivera vi-tangentbindningar och TAB-komplettering:

python:bind -v
python:bind ^I rl_complete

Observera också att olika bibliotek kan använda olika format för historikfiler. Vid byte av underliggande bibliotek kan befintliga historikfiler bli oanvändbara.

readline.backend

Namnet på det underliggande Readline-biblioteket som används, antingen "readline" eller "editline".

Tillagd i version 3.13.

Init-fil

Följande funktioner är relaterade till init-filen och användarkonfigurationen:

readline.parse_and_bind(string)

Exekverar den init-rad som anges i argumentet string. Detta anropar rl_parse_and_bind() i det underliggande biblioteket.

readline.read_init_file([filename])

Exekverar en initialiseringsfil för readline. Standardfilnamnet är det senast använda filnamnet. Detta anropar rl_read_init_file() i det underliggande biblioteket. Det utlöser en auditing event open med filnamnet om det anges, och "<readline_init_file>" annars, oavsett vilken fil biblioteket löser.

Ändrad i version 3.14: Evenemanget för revision lades till.

Linjebuffert

Följande funktioner arbetar på linjebufferten:

readline.get_line_buffer()

Returnera det aktuella innehållet i radbufferten (rl_line_buffer i det underliggande biblioteket).

readline.insert_text(string)

Infoga text i radbufferten vid markörens position. Detta anropar rl_insert_text() i det underliggande biblioteket, men ignorerar returvärdet.

readline.redisplay()

Ändra vad som visas på skärmen så att det återspeglar det aktuella innehållet i radbufferten. Detta anropar rl_redisplay() i det underliggande biblioteket.

Historikfil

Följande funktioner arbetar med en historikfil:

readline.read_history_file([filename])

Läser in en readline-historikfil och lägger till den i historiklistan. Standardfilnamnet är ~/.history. Detta anropar read_history() i det underliggande biblioteket och skapar en auditing event open med filnamnet om det är givet och "~/.history" annars.

Ändrad i version 3.14: Evenemanget för revision lades till.

readline.write_history_file([filename])

Spara historiklistan i en historikfil för readline och skriv över en eventuell befintlig fil. Standardfilnamnet är ~/.history. Detta anropar write_history() i det underliggande biblioteket och skapar en auditing event open med filnamnet om det anges och "~/.history" annars.

Ändrad i version 3.14: Evenemanget för revision lades till.

readline.append_history_file(nelements[, filename])

Lägg till de sista nelements-posterna i historiken till en fil. Standardfilnamnet är ~/.history. Filen måste redan existera. Detta anropar append_history() i det underliggande biblioteket. Denna funktion existerar endast om Python kompilerades för en version av biblioteket som stödjer den. Den skapar en auditing event open med filnamnet om det anges och "~/.history" annars.

Tillagd i version 3.5.

Ändrad i version 3.14: Evenemanget för revision lades till.

readline.get_history_length()
readline.set_history_length(length)

Ställ in eller returnera önskat antal rader som ska sparas i historikfilen. Funktionen write_history_file() använder detta värde för att trunkera historikfilen genom att anropa history_truncate_file() i det underliggande biblioteket. Negativa värden innebär obegränsad storlek på historikfilen.

Historisk lista

Följande funktioner arbetar med en global historiklista:

readline.clear_history()

Rensa den aktuella historiken. Detta anropar clear_history() i det underliggande biblioteket. Python-funktionen finns bara om Python kompilerades för en version av biblioteket som stöder den.

readline.get_current_history_length()

Returnerar antalet objekt som för närvarande finns i historiken. (Detta skiljer sig från get_history_length(), som returnerar det maximala antalet rader som kommer att skrivas till en historikfil)

readline.get_history_item(index)

Returnerar det aktuella innehållet i historikobjektet på index. Objektets index är ettbaserat. Detta anropar history_get() i det underliggande biblioteket.

readline.remove_history_item(pos)

Tar bort ett historiskt objekt som specificeras av dess position i historiken. Positionen är nollbaserad. Detta anropar remove_history() i det underliggande biblioteket.

readline.replace_history_item(pos, line)

Ersätt historikobjektet som specificeras av dess position med line. Positionen är nollbaserad. Detta anropar replace_history_entry() i det underliggande biblioteket.

readline.add_history(line)

Lägger till rad till historiebufferten, som om det var den senast skrivna raden. Detta anropar add_history() i det underliggande biblioteket.

readline.set_auto_history(enabled)

Aktivera eller inaktivera automatiska anrop till add_history() när indata läses via readline. Argumentet enabled bör vara ett booleskt värde som när det är sant aktiverar automatisk historik och som när det är falskt inaktiverar automatisk historik.

Tillagd i version 3.6.

Automatisk historik är aktiverad som standard och ändringar i denna sparas inte över flera sessioner.

Hooks för uppstart

readline.set_startup_hook([function])

Ställ in eller ta bort den funktion som anropas av rl_startup_hook callback i det underliggande biblioteket. Om function anges kommer den att användas som den nya hook-funktionen; om den utelämnas eller None, kommer alla funktioner som redan är installerade att tas bort. Hooken anropas utan argument strax innan readline skriver ut den första prompten.

readline.set_pre_input_hook([function])

Ställ in eller ta bort den funktion som anropas av rl_pre_input_hook callback i det underliggande biblioteket. Om function anges kommer den att användas som den nya hook-funktionen; om den utelämnas eller None tas alla funktioner som redan är installerade bort. Hooken anropas utan argument efter att den första prompten har skrivits ut och strax innan readline börjar läsa in tecken. Den här funktionen finns bara om Python kompilerades för en version av biblioteket som stöder den.

Slutfört

Följande funktioner handlar om att implementera en anpassad ordkompletteringsfunktion. Denna styrs vanligtvis av tabbtangenten och kan föreslå och automatiskt komplettera ett ord som skrivs. Som standard är Readline inställt på att användas av rlcompleter för att komplettera Python-identifierare för den interaktiva tolken. Om modulen readline ska användas med en anpassad kompletterare, bör en annan uppsättning ordavgränsare anges.

readline.set_completer([function])

Ställ in eller ta bort kompletteringsfunktionen. Om function anges kommer den att användas som den nya kompletteringsfunktionen; om den utelämnas eller None, kommer alla kompletteringsfunktioner som redan är installerade att tas bort. Kompletteringsfunktionen anropas som function(text, state), för state i 0, 1, 2, …, tills den returnerar ett icke-strängvärde. Den bör returnera nästa möjliga komplettering som börjar med text.

Den installerade kompletteringsfunktionen anropas av den entry_func callback som skickas till rl_completion_matches() i det underliggande biblioteket. Strängen text kommer från den första parametern till anropet rl_attempted_completion_function i det underliggande biblioteket.

readline.get_completer()

Hämta kompletteringsfunktionen, eller None om ingen kompletteringsfunktion har angetts.

readline.get_completion_type()

Hämtar den typ av avslutning som försöks. Detta returnerar rl_completion_type-variabeln i det underliggande biblioteket som ett heltal.

readline.get_begidx()
readline.get_endidx()

Hämtar start- eller slutindex för slutförandets omfattning. Dessa index är de start och slut argument som skickas till rl_attempted_completion_function callback i det underliggande biblioteket. Värdena kan vara olika i samma inmatningsredigeringsscenario beroende på den underliggande C readline-implementeringen. Ex: libedit är känt för att bete sig annorlunda än libreadline.

readline.set_completer_delims(string)
readline.get_completer_delims()

Ange eller hämta ordavgränsare för komplettering. Dessa bestämmer början på det ord som ska beaktas för komplettering (kompletteringens omfattning). Dessa funktioner använder variabeln rl_completer_word_break_characters i det underliggande biblioteket.

readline.set_completion_display_matches_hook([function])

Ställ in eller ta bort funktionen för visning av komplettering. Om function anges kommer den att användas som ny funktion för visning av kompletteringar; om den utelämnas eller None tas alla funktioner för visning av kompletteringar som redan är installerade bort. Detta ställer in eller rensar rl_completion_display_matches_hook callback i det underliggande biblioteket. Funktionen för visning av komplettering anropas som function(substitution, [matches], longest_match_length) en gång varje gång matchningar behöver visas.

Exempel

Följande exempel visar hur man använder readline-modulens funktioner för att läsa och skriva historik för att automatiskt ladda och spara en historikfil med namnet .python_history från användarens hemkatalog. Koden nedan skulle normalt exekveras automatiskt under interaktiva sessioner från användarens PYTHONSTARTUP-fil.

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)

Den här koden körs faktiskt automatiskt när Python körs i interaktivt läge (se Konfiguration av läslinje).

Följande exempel uppnår samma mål men stöder samtidiga interaktiva sessioner genom att bara lägga till den nya historiken.

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)

Följande exempel utökar code.InteractiveConsole-klassen för att stödja historiksparande/återställning.

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)