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

---

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

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

Примечание

Основной API библиотеки Readline может быть реализован библиотекой libedit вместо GNU readline. На macOS модуль readline обнаруживает, какая библиотека - используемый во время, которым управляют.

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

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

python:bind -v
python:bind ^I rl_complete

Init файл

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

readline.parse_and_bind(string)

Выполнить init строку, обеспеченную в аргументе 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])

Загрузите файл истории прочтения и добавить его в список истории. Имя файла по умолчанию - ~/.history. Вызывается read_history() в основной библиотеке.

readline.write_history_file([filename])

Сохранить список истории в файле истории строк чтения, перезаписав любой существующий файл. Имя файла по умолчанию - ~/.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() при чтении входных данных через линию чтения. Аргумент 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, любая функция, уже установленная, удалена. хук вызывается без аргументов после печати первого запроса и непосредственно перед началом чтения входных символов. Эта функция только существует, если Python был собран для версии библиотеки, которая поддерживает его.

Завершение

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

readline.set_completer([function])

Установить или удалить функцию завершения. Если function будет определен, то это будет используемый как новая функция завершения; если пропущено или None, любая функция завершения, уже установленная, удалена. Функция completer вызвана как function(text, state), для state в 0, 1, 2…, до него возвращает non-строка значение. Это должно возвращает следующее возможное завершение, начинающееся с 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) один раз при каждом отображении совпадений.

Пример

В следующем примере показано, как использовать функции чтения и записи истории модуля 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)
    # по умолчанию история len равна -1 (бесконечная), которая может стать неуправляемой
    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)