# `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.

Availability: not Android, not iOS, not WASI.

This module is not supported on mobile platforms or WebAssembly platforms.

Примітка

The underlying Readline library API may be implemented by the `editline` (`libedit`) library instead of GNU readline. On macOS the `readline` module detects which library is being used at run time.

The configuration file for `editline` is different from that of GNU readline. If you programmatically load configuration strings you can use `backend` to determine which library is being used.

If you use `editline`/`libedit` readline emulation on macOS, the initialization file located in your home directory is named `.editrc`. For example, the following content in `~/.editrc` will turn ON vi keybindings and TAB completion:

    python:bind -v
    python:bind ^I rl_complete

Also note that different libraries may use different history file formats. When switching the underlying library, existing history files may become unusable.

readline.backend

  The name of the underlying Readline library being used, either `"readline"` or `"editline"`.

  Added in version 3.13.

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

Наступні функції стосуються файлу ініціалізації та конфігурації користувача:

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)