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

Модуль readline определяет ряд функций для облегчения автозаполнения и чтения/записи файлов истории из интерпретатора Python. Этот модуль можно использовать непосредственно или через модуль rlcompleter, который поддерживает автозаполнение идентификаторов Python в интерактивном приглашении. Настройки, сделанные с помощью этого модуля, влияют на поведение как интерактивного приглашения интерпретатора, так и приглашений, предлагаемых встроенными функциями raw_input() и 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.get_history_length()

readline.set_history_length(length)

Установить или получить желаемое количество строк для сохранения в файле истории. Функция write_history_file() использует это значение для обрезки файла истории, вызывая history_truncate_file() в базовой библиотеке. Отрицательные значения означают неограниченный размер файла истории.

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

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

readline.clear_history()

Очистить текущую историю. Это вызывает clear_history() в базовой библиотеке. Функция Python существует только если Python был скомпилирован для версии библиотеки, которая ее поддерживает.

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

readline.get_current_history_length()

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

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

readline.get_history_item(index)

Возвращает текущее содержимое элемента истории по индексу. Индекс элемента — с единицы. Это вызывает history_get() в базовой библиотеке.

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

readline.remove_history_item(pos)

Удалить элемент истории, указанный его позицией, из истории. Позиция — нулевая. Это вызывает remove_history() в базовой библиотеке.

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

readline.replace_history_item(pos, line)

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

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

readline.add_history(line)

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

5. Запускаемые крючки

readline.set_startup_hook([function])

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

readline.set_pre_input_hook([function])

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

6. Автозаполнение

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

readline.set_completer([function])

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

Установленная функция автозаполнения вызывается обратным вызовом entry_func, переданным в rl_completion_matches() в базовой библиотеке. Строка text поступает из первого параметра обратного вызова rl_attempted_completion_function базовой библиотеки.

readline.get_completer()

Получить функцию автозаполнения или None, если функция автозаполнения не была установлена.

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

readline.get_completion_type()

Получить тип выполняемого автозаполнения. Это возвращает переменную rl_completion_type в базовой библиотеке как целое число.

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

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])

Установить или удалить функцию отображения завершения. Если указана функция, она будет использоваться как новая функция отображения завершения; если опущена или None, любая установленная ранее функция отображения завершения будет удалена. Это устанавливает или очищает обратный вызов rl_completion_display_matches_hook в библиотеке. Функция отображения завершения вызывается как function(substitution, [matches], longest_match_length) каждый раз, когда необходимо отобразить совпадения.

Введено в версии 2.6.

7. Пример

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

import os
import readline
histfile = os.path.join(os.path.expanduser("~"), ".pyhist")
try:
    readline.read_history_file(histfile)
    # default history len is -1 (infinite), which may grow unruly
    readline.set_history_length(1000)
except IOError:
    pass
import atexit
atexit.register(readline.write_history_file, histfile)
del os, histfile

Следующий пример расширяет класс code.InteractiveConsole для поддержки сохранения и восстановления истории.

import code
import readline
import atexit
import os

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 IOError:
                pass
            atexit.register(self.save_history, histfile)

    def save_history(self, histfile):
        readline.set_history_length(1000)
        readline.write_history_file(histfile)