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

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

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

readline.parse_and_bind(string)

Выполняет строку инициализации, переданную в аргументе 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)

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

readline.set_auto_history(enabled)

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

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

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

Перехватчики запуска

readline.set_startup_hook([function])

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

readline.set_pre_input_hook([function])

Устанавливает или удаляет функцию, вызываемую callback-функцией 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.

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

readline.get_completer()

Возвращает функцию автодополнения или None, если она не была установлена.

readline.get_completion_type()

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

readline.get_begidx()

readline.get_endidx()

Возвращает начальный или конечный индекс области автодополнения. Эти индексы соответствуют аргументам start и end, переданным callback-функции 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, установленная функция отображения удаляется. Устанавливает или сбрасывает callback-функцию 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)