readline
— GNU readline interface¶
Модуль readline
визначає низку функцій для полегшення завершення та читання/запису файлів історії з інтерпретатора Python. Цей модуль можна використовувати безпосередньо або через модуль rlcompleter
, який підтримує завершення ідентифікаторів Python за інтерактивним запитом. Параметри, зроблені за допомогою цього модуля, впливають на поведінку як інтерактивної підказки інтерпретатора, так і підказок, запропонованих вбудованою функцією 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.
Availability: not Android, not iOS, not WASI.
This module is not supported on mobile platforms or WebAssembly platforms.
Примітка
The underlying Readline library API may be implemented by
the editline
(libedit
) library instead of GNU readline.
On macOS the readline
module detects which library is being used
at run time.
The configuration file for editline
is different from that
of GNU readline. If you programmatically load configuration strings
you can use backend
to determine which library is being used.
If you use editline
/libedit
readline emulation on macOS, the
initialization file located in your home directory is named
.editrc
. For example, the following content in ~/.editrc
will
turn ON vi keybindings and TAB completion:
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.
- readline.backend¶
The name of the underlying Readline library being used, either
"readline"
or"editline"
.Added in version 3.13.
Ініціальний файл¶
Наступні функції стосуються файлу ініціалізації та конфігурації користувача:
- readline.parse_and_bind(string)¶
Виконайте рядок ініціалізації, наданий в аргументі string. Це викликає
rl_parse_and_bind()
у базовій бібліотеці.
- readline.read_init_file([filename])¶
Виконайте файл ініціалізації рядка читання. Назва файлу за замовчуванням — це останнє використане ім’я файлу. Це викликає
rl_read_init_file()
у базовій бібліотеці.
Лінійний буфер¶
На буфері лінії працюють такі функції:
- readline.get_line_buffer()¶
Повертає поточний вміст буфера рядків (
rl_line_buffer
у базовій бібліотеці).
- readline.insert_text(string)¶
Вставте текст у буфер рядків у позиції курсора. Це викликає
rl_insert_text()
у базовій бібліотеці, але ігнорує повернуте значення.
- readline.redisplay()¶
Змініть те, що відображається на екрані, щоб відобразити поточний вміст рядкового буфера. Це викликає
rl_redisplay()
у базовій бібліотеці.
Файл історії¶
З файлом історії працюють такі функції:
- readline.read_history_file([filename])¶
Завантажте файл історії рядка читання та додайте його до списку історії. Назва файлу за замовчуванням
~/.history
. Це викликаєread_history()
у базовій бібліотеці.
- readline.write_history_file([filename])¶
Збережіть список історії у файл історії рядка читання, перезаписавши будь-який існуючий файл. Назва файлу за замовчуванням
~/.history
. Це викликаєwrite_history()
у базовій бібліотеці.
- readline.append_history_file(nelements[, filename])¶
Додайте останні elements елементи історії до файлу. Назва файлу за замовчуванням
~/.history
. Файл уже має існувати. Це викликаєappend_history()
у базовій бібліотеці. Ця функція існує, лише якщо Python було скомпільовано для версії бібліотеки, яка її підтримує.Added in version 3.5.
- readline.get_history_length()¶
- readline.set_history_length(length)¶
Установіть або поверніть потрібну кількість рядків для збереження у файлі історії. Функція
write_history_file()
використовує це значення для скорочення файлу історії, викликаючиhistory_truncate_file()
у базовій бібліотеці. Від’ємні значення означають необмежений розмір файлу історії.
Список історії¶
У списку глобальної історії працюють такі функції:
- readline.clear_history()¶
Очистити поточну історію. Це викликає
clear_history()
у базовій бібліотеці. Функція Python існує, лише якщо Python було скомпільовано для версії бібліотеки, яка її підтримує.
- readline.get_current_history_length()¶
Повертає кількість елементів в історії. (Це відрізняється від
get_history_length()
, який повертає максимальну кількість рядків, які будуть записані у файл історії.)
- readline.get_history_item(index)¶
Повернути поточний вміст елемента історії за index. Індекс позиції складається з однієї основи. Це викликає
history_get()
у базовій бібліотеці.
- readline.remove_history_item(pos)¶
Видалити з історії елемент історії, визначений його позицією. Позиція відраховується з нуля. Це викликає
remove_history()
у базовій бібліотеці.
- readline.replace_history_item(pos, line)¶
Замінити елемент історії, визначений його позицією, на рядок. Позиція відраховується з нуля. Це викликає
replace_history_entry()
у базовій бібліотеці.
- readline.add_history(line)¶
Додайте рядок до буфера історії, ніби це був останній введений рядок. Це викликає
add_history()
у базовій бібліотеці.
- readline.set_auto_history(enabled)¶
Увімкнути або вимкнути автоматичні виклики
add_history()
під час читання введених даних через рядок читання. Аргумент enabled має бути логічним значенням, яке, коли істина, вмикає автоматичну історію, а коли хибна, вимикає автоматичну історію.Added in version 3.6.
Деталі реалізації CPython: Auto history is enabled by default, and changes to this do not persist across multiple sessions.
Хуки для запуску¶
- readline.set_startup_hook([function])¶
Установіть або видаліть функцію, викликану зворотним викликом
rl_startup_hook
основної бібліотеки. Якщо вказано функцію, її буде використано як нову функцію підключення; якщо опущено абоNone
, усі вже встановлені функції буде видалено. Хук викликається без аргументів безпосередньо перед тим, як readline надрукує перший запит.
- readline.set_pre_input_hook([function])¶
Установіть або видаліть функцію, викликану зворотним викликом
rl_pre_input_hook
основної бібліотеки. Якщо вказано функцію, її буде використано як нову функцію підключення; якщо опущено абоNone
, усі вже встановлені функції буде видалено. Хук викликається без аргументів після того, як перше запрошення буде надруковано та безпосередньо перед тим, як readline почне читати введені символи. Ця функція існує, лише якщо Python було скомпільовано для версії бібліотеки, яка її підтримує.
Завершення¶
Наступні функції стосуються реалізації спеціальної функції доповнення слів. Зазвичай це працює за допомогою клавіші Tab і може пропонувати та автоматично завершувати введене слово. За замовчуванням Readline налаштовано на використання rlcompleter
для заповнення ідентифікаторів Python для інтерактивного інтерпретатора. Якщо модуль readline
використовуватиметься з настроюваним доповнювачем, слід встановити інший набір розділювачів слів.
- readline.set_completer([function])¶
Встановити або видалити функцію завершення. Якщо вказано функцію, вона використовуватиметься як нова функція завершення; якщо опущено або
None
, усі вже встановлені завершальні функції видаляються. Функція завершення викликається якfunction(text, state)
для state в0
,1
,2
, …, доки вона не поверне не- значення рядка. Він має повернути наступне можливе завершення, починаючи з тексту.Встановлена функція завершувача викликається зворотним викликом entry_func, переданим до
rl_completion_matches()
у базовій бібліотеці. Рядок text надходить із першого параметра зворотного викликуrl_attempted_completion_function
основної бібліотеки.
- readline.get_completer()¶
Отримайте функцію завершувача або
None
, якщо функцію завершувача не встановлено.
- readline.get_completion_type()¶
Отримайте тип завершення, яке намагається виконати. Це повертає змінну
rl_completion_type
у базовій бібліотеці як ціле число.
- readline.get_begidx()¶
- readline.get_endidx()¶
Отримати початковий або кінцевий індекс області завершення. Ці індекси є аргументами start і end, що передаються до зворотного виклику
rl_attempted_completion_function
основної бібліотеки. Значення можуть відрізнятися в тому самому сценарії редагування введення на основі базової реалізації C readline. Приклад: libedit, як відомо, поводиться інакше, ніж libreadline.
- readline.set_completer_delims(string)¶
- readline.get_completer_delims()¶
Установіть або отримайте роздільники слів для завершення. Вони визначають початок слова, яке розглядається для завершення (область завершення). Ці функції отримують доступ до змінної
rl_completer_word_break_characters
у базовій бібліотеці.
- readline.set_completion_display_matches_hook([function])¶
Встановіть або видаліть функцію відображення завершення. Якщо вказано функцію, вона використовуватиметься як нова функція відображення завершення; якщо опущено або
None
, усі вже встановлені функції відображення завершення видаляються. Це встановлює або очищає зворотний викликrl_completion_display_matches_hook
у базовій бібліотеці. Функція відображення завершення викликається якfunction(substitution, [matches], longest_match_length)
щоразу, коли потрібно відображати збіги.
приклад¶
У наступному прикладі показано, як використовувати функції читання та запису історії модуля readline
для автоматичного завантаження та збереження файлу історії під назвою .python_history
з домашнього каталогу користувача. Наведений нижче код зазвичай виконується автоматично під час інтерактивних сеансів із файлу користувача 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)
Цей код насправді запускається автоматично, коли Python запускається в інтерактивному режимі (див. Конфігурація Readline).
Наступний приклад досягає тієї ж мети, але підтримує одночасні інтерактивні сеанси, лише додаючи нову історію.
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)
Наступний приклад розширює клас code.InteractiveConsole
для підтримки збереження/відновлення історії.
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)