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

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

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

Примечание

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

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

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

python:bind -v
python:bind ^I rl_complete

Инициализирующий файл

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

readline.parse_and_bind(string)

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

readline.read_init_file([filename])

Запустите файл инициализации строки чтения. Имя файла по умолчанию - это последнее используемое имя файла. При этом в базовой библиотеке вызывается 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])

Загрузите файл истории чтения и добавьте его в список истории. Имя файла по умолчанию - ~/.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)

Включите или отключите автоматические вызовы:c:func: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])

Установите или удалите функцию complete. Если указано значение function, оно будет использоваться в качестве новой функции complete; если оно опущено или None, все уже установленные функции complete будут удалены. Завершающая функция вызывается как function(text, state), для state in 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])

Установите или удалите функцию отображения завершения. Если указана функция *, она будет использоваться в качестве новой функции отображения завершения; если она опущена или 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 (см. Конфигурация строки чтения).

Следующий пример достигает той же цели, но поддерживает параллельные интерактивные сеансы, только добавляя новую историю.

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
Вернуться на верх