`readline` — GNU readline interface¶

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

Readline keybindings may be configured via an initialization file, typically .inputrc in your home directory. See Readline Init File in the GNU Readline manual for information about the format and allowable constructs of that file, and the capabilities of the Readline library in general.

Примітка

Базовий API бібліотеки Readline може бути реалізований бібліотекою libedit замість GNU readline. У macOS модуль readline визначає, яка бібліотека використовується під час виконання.

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

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

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])¶: Збережіть список історії у файл історії рядка читання, перезаписавши будь-який існуючий файл. Назва файлу за замовчуванням ~/.history. Це викликає write_history() у базовій бібліотеці.

readline.append_history_file(nelements[, filename])¶: Додайте останні elements елементи історії до файлу. Назва файлу за замовчуванням ~/.history. Файл уже має існувати. Це викликає append_history() у базовій бібліотеці. Ця функція існує, лише якщо Python було скомпільовано для версії бібліотеки, яка її підтримує.

Added in version 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)¶: Замінити елемент історії, визначений його позицією, на рядок. Позиція відраховується з нуля. Це викликає replace_history_entry() у базовій бібліотеці.

readline.add_history(line)¶: Додайте рядок до буфера історії, ніби це був останній введений рядок. Це викликає add_history() у базовій бібліотеці.

readline.set_auto_history(enabled)¶: Увімкнути або вимкнути автоматичні виклики add_history() під час читання введених даних через рядок читання. Аргумент enabled має бути логічним значенням, яке, коли істина, вмикає автоматичну історію, а коли хибна, вимикає автоматичну історію.

Added in version 3.6.

Деталі реалізації CPython: Auto history is enabled by default, and changes to this do not persist across multiple sessions.

Хуки для запуску¶

readline.set_startup_hook([function])¶: Установіть або видаліть функцію, викликану зворотним викликом rl_startup_hook основної бібліотеки. Якщо вказано функцію, її буде використано як нову функцію підключення; якщо опущено або None, усі вже встановлені функції буде видалено. Хук викликається без аргументів безпосередньо перед тим, як readline надрукує перший запит.

readline.set_pre_input_hook([function])¶: Установіть або видаліть функцію, викликану зворотним викликом rl_pre_input_hook основної бібліотеки. Якщо вказано функцію, її буде використано як нову функцію підключення; якщо опущено або None, усі вже встановлені функції буде видалено. Хук викликається без аргументів після того, як перше запрошення буде надруковано та безпосередньо перед тим, як readline почне читати введені символи. Ця функція існує, лише якщо Python було скомпільовано для версії бібліотеки, яка її підтримує.

Завершення¶

Наступні функції стосуються реалізації спеціальної функції доповнення слів. Зазвичай це працює за допомогою клавіші Tab і може пропонувати та автоматично завершувати введене слово. За замовчуванням Readline налаштовано на використання rlcompleter для заповнення ідентифікаторів Python для інтерактивного інтерпретатора. Якщо модуль readline використовуватиметься з настроюваним доповнювачем, слід встановити інший набір розділювачів слів.

readline.set_completer([function])¶

Встановити або видалити функцію завершення. Якщо вказано функцію, вона використовуватиметься як нова функція завершення; якщо опущено або None, усі вже встановлені завершальні функції видаляються. Функція завершення викликається як function(text, state) для state в 0, 1, 2, …, доки вона не поверне не- значення рядка. Він має повернути наступне можливе завершення, починаючи з тексту.

Встановлена функція завершувача викликається зворотним викликом 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 запускається в інтерактивному режимі (див. Конфігурація 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)

`readline` — GNU readline interface¶

Ініціальний файл¶

Лінійний буфер¶

Файл історії¶

Список історії¶

Хуки для запуску¶

Завершення¶

приклад¶

Table of Contents

Попередній розділ

Наступна тема

Ця сторінка

readline — GNU readline interface¶

Ініціальний файл¶

Лінійний буфер¶

Файл історії¶

Список історії¶

Хуки для запуску¶

Завершення¶

приклад¶

`readline` — GNU readline interface¶