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

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

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

Примечание

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

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

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

python:bind -v
python:bind ^I rl_complete

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

Следующие функции относятся к файлу 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 был скомпилирован для версии библиотеки, которая ее поддерживает.

Добавлено в версии 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 отключает автоматическую историю.

Добавлено в версии 3.6.

CPython implementation detail: Auto history is enabled by default, and changes to this do not persist across multiple sessions.

Пусковые крючки

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)
stringprep — Подготовка интернет-строки
rlcompleter — Функция завершения для GNU readline
Вернуться на верх