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

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

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

readline.parse_and_bind(string)

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

readline.read_init_file([filename])

Выполняет файл инициализации readline. По умолчанию используется имя последнего использованного файла. Вызывает rl_read_init_file() в базовой библиотеке. Генерирует событие аудита open с именем файла, если оно задано, и "<readline_init_file>" в противном случае, независимо от того, какой файл открывает библиотека.

Изменено в версии 3.14: Добавлено событие аудита.

Буфер строки

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

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() в базовой библиотеке и генерирует событие аудита open с именем файла, если оно задано, и "~/.history" в противном случае.

Изменено в версии 3.14: Добавлено событие аудита.

readline.write_history_file([filename])

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

Изменено в версии 3.14: Добавлено событие аудита.

readline.append_history_file(nelements[, filename])

Добавляет в файл последние nelements элементов истории. По умолчанию используется имя файла ~/.history. Файл должен уже существовать. Вызывает append_history() в базовой библиотеке. Эта функция существует только в том случае, если Python был собран с версией библиотеки, которая её поддерживает. Генерирует событие аудита open с именем файла, если оно задано, и "~/.history" в противном случае.

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

Изменено в версии 3.14: Добавлено событие аудита.

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)

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

readline.set_auto_history(enabled)

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

Добавлено в версии 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 базовой библиотеки. Значения могут различаться в одной и той же ситуации редактирования ввода в зависимости от базовой реализации readline на C. Например, известно, что 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 в интерактивном режиме (см. раздел Настройка 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)