readline — Интерфейс GNU readline

---

Модуль readline определяет ряд функций, облегчающих завершение и чтение/запись файлов истории из интерпретатора Python. Этот модуль может использоваться напрямую или через модуль rlcompleter, который поддерживает завершение идентификаторов Python в интерактивной подсказке. Настройки, сделанные с помощью этого модуля, влияют на поведение как интерактивной подсказки интерпретатора, так и подсказок, предлагаемых встроенной функцией input().

Связки клавиш Readline могут быть настроены с помощью файла инициализации, обычно .inputrc в вашем домашнем каталоге. Информацию о формате и допустимых конструкциях этого файла, а также о возможностях библиотеки Readline в целом смотрите в Readline Init File в руководстве GNU Readline.

Availability: не WASI, не iOS.

Этот модуль не работает или недоступен на платформах WebAssembly или iOS. Дополнительные сведения о доступности WASM см. в разделе Платформы WebAssembly; о доступности iOS - в разделе iOS.

Примечание

Основной API библиотеки Readline может быть реализован библиотекой editline (libedit) вместо GNU readline. В macOS модуль readline определяет, какая библиотека используется во время выполнения.

Конфигурационный файл для editline отличается от файла GNU readline. Если вы программно загружаете строки конфигурации, вы можете использовать backend, чтобы определить, какая библиотека используется.

Если вы используете эмуляцию линии чтения editline/libedit в macOS, файл инициализации, расположенный в вашем домашнем каталоге, имеет имя .editrc. Например, следующее содержимое в ~/.editrc включит привязку клавиш vi и завершение TAB:

python:bind -v
python:bind ^I rl_complete

readline.backend

Имя используемой базовой библиотеки Readline, либо "readline", либо "editline".

Added in version 3.13.

Начальный файл

Следующие функции относятся к файлу init и пользовательской конфигурации:

readline.parse_and_bind(string)

Выполнение строки init, указанной в аргументе string. При этом вызывается rl_parse_and_bind() в базовой библиотеке.

readline.read_init_file([filename])

Выполнение файла инициализации readline. По умолчанию используется последнее использованное имя файла. При этом вызывается 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])

Загружает файл истории readline и добавляет его в список истории. По умолчанию используется имя файла ~/.history. Это вызывает read_history() в базовой библиотеке.

readline.write_history_file([filename])

Сохраняет список истории в файл истории readline, перезаписывая существующий файл. По умолчанию используется имя файла ~/.history. Это вызывает write_history() в базовой библиотеке.

readline.append_history_file(nelements[, filename])

Добавляет последние nelements элементы истории в файл. По умолчанию используется имя файла ~/.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)

Заменить элемент истории, указанный его позицией, на line. Позиция основана на нулях. Это вызывает replace_history_entry() в базовой библиотеке.

readline.add_history(line)

Добавляет строку в буфер истории, как если бы это была последняя набранная строка. Это вызывает add_history() в базовой библиотеке.

readline.set_auto_history(enabled)

Включает или отключает автоматические обращения к add_history() при чтении ввода через readline. Аргумент enabled должен быть булевым значением, которое при true включает автоматическую историю, а при false отключает ее.

Added in version 3.6.

Детали реализации CPython: Автоистория включена по умолчанию, и изменения в ней не сохраняются в нескольких сеансах.

Крючки для запуска

readline.set_startup_hook([function])

Устанавливает или удаляет функцию, вызываемую обратным вызовом rl_startup_hook базовой библиотеки. Если указана function, она будет использоваться в качестве новой функции хука; если не указана или указана None, удаляется любая уже установленная функция. Хук вызывается без аргументов непосредственно перед тем, как readline напечатает первую подсказку.

readline.set_pre_input_hook([function])

Устанавливает или удаляет функцию, вызываемую обратным вызовом rl_pre_input_hook базовой библиотеки. Если указана function, она будет использоваться в качестве новой функции хука; если не указана или указана None, удаляется любая уже установленная функция. Хук вызывается без аргументов после вывода первой подсказки и непосредственно перед тем, как readline начнет считывать вводимые символы. Эта функция существует только в том случае, если Python был скомпилирован для версии библиотеки, которая ее поддерживает.

Завершение

Следующие функции относятся к реализации пользовательской функции завершения слов. Обычно она управляется клавишей Tab и может предлагать и автоматически завершать вводимое слово. По умолчанию Readline настроен на использование rlcompleter для завершения идентификаторов Python для интерактивного интерпретатора. Если модуль readline будет использоваться с пользовательским компилятором, необходимо установить другой набор разделителей слов.

readline.set_completer([function])

Установить или удалить функцию дополнения. Если указана function, то она будет использоваться в качестве новой функции-комплетера; если не указана или None, то любая уже установленная функция-комплетер будет удалена. Функция завершения вызывается как function(text, state), для state в 0, 1, 2, …, пока не вернет нестроковое значение. Она должна возвращать следующее возможное завершение, начиная с text.

Установленная функция-заполнитель вызывается обратным вызовом 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])

Установка или удаление функции отображения завершения. Если указана 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 в режиме interactive mode (см. Конфигурация 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)