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

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

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

1. Файл инициализации

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

readline.parse_and_bind(string)

Выполнить строку инициализации, предоставленную в аргументе string. Это вызывает rl_parse_and_bind() в базовой библиотеке.

readline.read_init_file([filename])

Выполнить файл инициализации readline. Имя файла по умолчанию — последнее использованное имя файла. Это вызывает rl_read_init_file() в базовой библиотеке.

2. Буфер строки

Следующие функции работают с буфером строки:

readline.get_line_buffer()

Возвращает текущее содержимое буфера строки (rl_line_buffer в базовой библиотеке).

readline.insert_text(string)

Вставить текст в буфер строки в позиции курсора. Это вызывает rl_insert_text() в базовой библиотеке, но игнорирует возвращаемое значение.

readline.redisplay()

Изменить отображаемое на экране содержимое, чтобы оно отражало текущее содержимое буфера строки. Это вызывает rl_redisplay() в базовой библиотеке.

3. Файл истории

Следующие функции работают с файлом истории:

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() в базовой библиотеке. Отрицательные значения означают неограниченный размер файла истории.

4. Список истории

Следующие функции работают со глобальным списком истории:

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)

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

5. Хакеры запуска

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 был скомпилирован для версии библиотеки, которая её поддерживает.

6. Автодополнение

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

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) один раз каждый раз, когда необходимо отобразить результаты.

7. Пример

Следующий пример демонстрирует, как использовать функции чтения и записи истории модуля 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_history_length()
except FileNotFoundError:
    open(histfile, 'wb').close()
    h_len = 0

def save(prev_h_len, histfile):
    new_h_len = readline.get_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)