readline.md
1> **Источник:** https://python-all.ru/3.15/library/readline.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `readline` – интерфейс GNU readline89---1011Модуль `readline` определяет ряд функций для упрощения дополнения и чтения/записи файлов истории из интерпретатора Python. Этот модуль можно использовать напрямую или через модуль [`rlcompleter`](https://python-all.ru/3.15/library/rlcompleter.html#module-rlcompleter), который поддерживает дополнение идентификаторов Python в интерактивной строке. Настройки, сделанные с помощью этого модуля, влияют на поведение как интерактивной строки интерпретатора, так и строк, предлагаемых встроенной функцией [`input()`](https://python-all.ru/3.15/library/functions.html#input).1213Привязки клавиш Readline можно настроить через файл инициализации, обычно `.inputrc` в вашем домашнем каталоге. Смотрите [Файл инициализации Readline](https://python-all.ru/3.15/library/readline.html) в руководстве GNU Readline для получения информации о формате и допустимых конструкциях этого файла, а также о возможностях библиотеки Readline в целом.1415[Доступность](https://python-all.ru/3.15/library/intro.html#availability): не Android, не iOS, не WASI.1617Этот модуль не поддерживается на [мобильных платформах](https://python-all.ru/3.15/library/intro.html#mobile-availability) или [платформах WebAssembly](https://python-all.ru/3.15/library/intro.html#wasm-availability).1819Это [опциональный модуль](https://python-all.ru/3.15/glossary.html#term-optional-module). Если его нет в вашей копии CPython, обратитесь к документации от вашего дистрибьютора (то есть того, кто предоставил вам Python). Если вы дистрибьютор, обратитесь к [требованиям к опциональным модулям](https://python-all.ru/3.15/using/configure.html#optional-module-requirements).2021[Доступность](https://python-all.ru/3.15/library/intro.html#availability): Unix.2223> **Примечание**24>25> API базовой библиотеки Readline может быть реализовано библиотекой `editline` (`libedit`) вместо GNU readline. В macOS модуль `readline` определяет, какая библиотека используется во время выполнения.26>27> Файл конфигурации для `editline` отличается от файла GNU readline. Если вы программно загружаете строки конфигурации, вы можете использовать [`backend`](https://python-all.ru/3.15/library/readline.html#readline.backend), чтобы определить, какая библиотека используется.28>29> Если вы используете эмуляцию readline `editline`/`libedit` в macOS, файл инициализации, расположенный в вашем домашнем каталоге, называется `.editrc`. Например, следующее содержимое в `~/.editrc` включит привязки клавиш *vi* и дополнение по TAB:30>31> ```python32> python:bind -v33> python:bind ^I rl_complete34> ```35>36> Также обратите внимание, что разные библиотеки могут использовать разные форматы файлов истории. При смене базовой библиотеки существующие файлы истории могут стать непригодными для использования.3738#### `readline.backend`3940Имя используемой базовой библиотеки Readline: либо `"readline"`, либо `"editline"`.4142Добавлено в версии 3.13.4344## Файл инициализации4546Следующие функции относятся к файлу инициализации и пользовательской конфигурации:4748#### `readline.parse_and_bind(string)`4950Выполняет строку инициализации, переданную в аргументе *string*. Это вызывает `rl_parse_and_bind()` в базовой библиотеке.5152#### `readline.read_init_file([filename])`5354Выполняет файл инициализации readline. По умолчанию используется имя файла, которое было использовано последним. Это вызывает `rl_read_init_file()` в базовой библиотеке. Оно возбуждает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `open` с именем файла, если оно задано, и `"<readline_init_file>"` в противном случае, независимо от того, какой файл разрешает библиотека.5556Изменено в версии 3.14: Добавлено событие аудита.5758## Буфер строки5960Следующие функции работают с буфером строки:6162#### `readline.get_line_buffer()`6364Возвращает текущее содержимое буфера строки (`rl_line_buffer` в базовой библиотеке).6566#### `readline.insert_text(string)`6768Вставляет текст в буфер строки в позиции курсора. Это вызывает `rl_insert_text()` в базовой библиотеке, но игнорирует возвращаемое значение.6970#### `readline.redisplay()`7172Изменяет отображаемое на экране, чтобы отразить текущее содержимое буфера строки. Это вызывает `rl_redisplay()` в базовой библиотеке.7374## Файл истории7576Следующие функции работают с файлом истории:7778#### `readline.read_history_file([filename])`7980Загружает файл истории readline и добавляет его в список истории. Имя файла по умолчанию – `~/.history`. Это вызывает `read_history()` в базовой библиотеке и возбуждает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `open` с именем файла, если оно задано, и `"~/.history"` в противном случае.8182Изменено в версии 3.14: Добавлено событие аудита.8384#### `readline.write_history_file([filename])`8586Сохраняет список истории в файл истории readline, перезаписывая любой существующий файл. Имя файла по умолчанию – `~/.history`. Это вызывает `write_history()` в базовой библиотеке и возбуждает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `open` с именем файла, если оно задано, и `"~/.history"` в противном случае.8788Изменено в версии 3.14: Добавлено событие аудита.8990#### `readline.append_history_file(nelements[, filename])`9192Добавляет последние *nelements* элементов истории в файл. Имя файла по умолчанию – `~/.history`. Файл должен уже существовать. Вызывает `append_history()` в нижележащей библиотеке. Эта функция существует только если Python был скомпилирован для версии библиотеки, которая её поддерживает. Она вызывает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `open` с именем файла, если оно задано, и `"~/.history"` в противном случае.9394Добавлено в версии 3.5.9596Изменено в версии 3.14: Добавлено событие аудита.9798#### `readline.get_history_length()`99100#### `readline.set_history_length(length)`101102Устанавливает или возвращает нужное количество строк для сохранения в файле истории. Функция [`write_history_file()`](https://python-all.ru/3.15/library/readline.html#readline.write_history_file) использует это значение для усечения файла истории, вызывая `history_truncate_file()` в нижележащей библиотеке. Отрицательные значения означают неограниченный размер файла истории.103104## Список истории105106Следующие функции работают с глобальным списком истории:107108#### `readline.clear_history()`109110Очищает текущую историю. Вызывает `clear_history()` в нижележащей библиотеке. Функция Python существует только если Python был скомпилирован для версии библиотеки, которая её поддерживает.111112#### `readline.get_current_history_length()`113114Возвращает количество элементов, находящихся в истории. (Отличается от [`get_history_length()`](https://python-all.ru/3.15/library/readline.html#readline.get_history_length), которая возвращает максимальное количество строк, которое будет записано в файл истории.)115116#### `readline.get_history_item(index)`117118Возвращает текущее содержимое элемента истории по *index*. Индекс элемента начинается с 1. Вызывает `history_get()` в нижележащей библиотеке.119120#### `readline.remove_history_item(pos)`121122Удаляет элемент истории, заданный по его позиции, из истории. Позиция начинается с 0. Вызывает `remove_history()` в нижележащей библиотеке.123124#### `readline.replace_history_item(pos, line)`125126Заменяет элемент истории, заданный по его позиции, на *line*. Позиция начинается с 0. Вызывает `replace_history_entry()` в нижележащей библиотеке.127128#### `readline.add_history(line)`129130Добавляет *line* в буфер истории, как если бы это была последняя введённая строка. Вызывает `add_history()` в нижележащей библиотеке.131132#### `readline.set_auto_history(enabled)`133134Включает или отключает автоматические вызовы `add_history()` при чтении ввода через readline. Аргумент *enabled* должен быть булевым значением: если true – включает авто-историю, если false – отключает авто-историю.135136Добавлено в версии 3.6.137138**Деталь реализации CPython:** Авто-история включена по умолчанию, и изменения не сохраняются между сеансами.139140## Хуки запуска141142#### `readline.set_startup_hook([function])`143144Устанавливает или удаляет функцию, вызываемую колбэком `rl_startup_hook` нижележащей библиотеки. Если указан *function*, он будет использоваться как новая функция-хук; если опущен или `None`, любая ранее установленная функция удаляется. Хук вызывается без аргументов непосредственно перед тем, как readline выведет первое приглашение.145146#### `readline.set_pre_input_hook([function])`147148Устанавливает или удаляет функцию, вызываемую колбэком `rl_pre_input_hook` нижележащей библиотеки. Если указан *function*, он будет использоваться как новая функция-хук; если опущен или `None`, любая ранее установленная функция удаляется. Хук вызывается без аргументов после вывода первого приглашения и непосредственно перед тем, как readline начнёт читать вводимые символы. Эта функция существует только если Python был скомпилирован для версии библиотеки, которая его поддерживает.149150#### `readline.get_pre_input_hook()`151152Возвращает текущую функцию pre-input hook, или `None`, если функция pre-input hook не была установлена. Эта функция существует только в том случае, если Python был скомпилирован для версии библиотеки, которая её поддерживает.153154Добавлено в версии 3.15.155156## Завершение157158Следующие функции относятся к реализации пользовательской функции завершения слов. Обычно она вызывается клавишей Tab и может предлагать и автоматически завершать вводимое слово. По умолчанию Readline настроен для использования [`rlcompleter`](https://python-all.ru/3.15/library/rlcompleter.html#module-rlcompleter) для завершения идентификаторов Python в интерактивном интерпретаторе. Если модуль `readline` должен использоваться с пользовательским комплитером, следует задать другой набор разделителей слов.159160#### `readline.set_completer([function])`161162Установить или удалить функцию дополнения. Если указана *function*, она будет использоваться как новая функция дополнения; если опущена или `None`, любая установленная ранее функция дополнения удаляется. Функция дополнения вызывается как `function(text, state)` для *state* в `0`, `1`, `2`, … пока не вернет нестроковое значение. Она должна возвращать следующее возможное дополнение, начинающееся с *text*.163164Установленная функция дополнения вызывается колбэком *entry\_func*, переданным в `rl_completion_matches()` в нижележащей библиотеке. Строка *text* берется из первого параметра колбэка `rl_attempted_completion_function` нижележащей библиотеки.165166#### `readline.get_completer()`167168Возвращает функцию дополнения или `None`, если функция дополнения не была установлена.169170#### `readline.get_completion_type()`171172Возвращает тип выполняемого дополнения. Возвращает переменную `rl_completion_type` из нижележащей библиотеки в виде целого числа.173174#### `readline.get_begidx()`175176#### `readline.get_endidx()`177178Возвращает начальный или конечный индекс области дополнения. Эти индексы – аргументы *start* и *end*, передаваемые в колбэк `rl_attempted_completion_function` нижележащей библиотеки. Значения могут различаться в одном и том же сценарии редактирования ввода в зависимости от реализации C readline. Например, libedit, как известно, ведет себя иначе, чем libreadline.179180#### `readline.set_completer_delims(string)`181182#### `readline.get_completer_delims()`183184Устанавливает или возвращает разделители слов для дополнения. Они определяют начало слова, для которого рассматривается дополнение (область дополнения). Эти функции обращаются к переменной `rl_completer_word_break_characters` в нижележащей библиотеке.185186#### `readline.set_completion_display_matches_hook([function])`187188Устанавливает или удаляет функцию отображения дополнений. Если указана *function*, она будет использоваться как новая функция отображения дополнений; если опущена или `None`, любая установленная ранее функция отображения дополнений удаляется. Эта функция устанавливает или очищает колбэк `rl_completion_display_matches_hook` в нижележащей библиотеке. Функция отображения дополнений вызывается как `function(substitution, [matches], longest_match_length)` каждый раз, когда нужно отобразить совпадения.189190## Пример191192Следующий пример демонстрирует, как использовать функции чтения и записи истории модуля `readline` для автоматической загрузки и сохранения файла истории с именем `.python_history` из домашнего каталога пользователя. Приведенный ниже код обычно выполняется автоматически во время интерактивных сессий из файла [`PYTHONSTARTUP`](https://python-all.ru/3.15/using/cmdline.html#envvar-PYTHONSTARTUP) пользователя.193194```python195import atexit196import os197import readline198199histfile = os.path.join(os.path.expanduser("~"), ".python_history")200try:201 readline.read_history_file(histfile)202 # длина истории по умолчанию равна -1 (бесконечность), что может привести к неконтролируемому росту203 readline.set_history_length(1000)204except FileNotFoundError:205 pass206207atexit.register(readline.write_history_file, histfile)208```209210Этот код фактически выполняется автоматически при запуске Python в [интерактивном режиме](https://python-all.ru/3.15/tutorial/interpreter.html#tut-interactive) (см. [Настройка Readline](https://python-all.ru/3.15/library/site.html#rlcompleter-config)).211212Следующий пример достигает той же цели, но поддерживает параллельные интерактивные сессии, добавляя только новую историю.213214```python215import atexit216import os217import readline218histfile = os.path.join(os.path.expanduser("~"), ".python_history")219220try:221 readline.read_history_file(histfile)222 h_len = readline.get_current_history_length()223except FileNotFoundError:224 open(histfile, 'wb').close()225 h_len = 0226227def save(prev_h_len, histfile):228 new_h_len = readline.get_current_history_length()229 readline.set_history_length(1000)230 readline.append_history_file(new_h_len - prev_h_len, histfile)231atexit.register(save, h_len, histfile)232```233234Следующий пример расширяет класс [`code.InteractiveConsole`](https://python-all.ru/3.15/library/code.html#code.InteractiveConsole) для поддержки сохранения и восстановления истории.235236```python237import atexit238import code239import os240import readline241242class HistoryConsole(code.InteractiveConsole):243 def __init__(self, locals=None, filename="<console>",244 histfile=os.path.expanduser("~/.console-history")):245 code.InteractiveConsole.__init__(self, locals, filename)246 self.init_history(histfile)247248 def init_history(self, histfile):249 readline.parse_and_bind("tab: complete")250 if hasattr(readline, "read_history_file"):251 try:252 readline.read_history_file(histfile)253 except FileNotFoundError:254 pass255 atexit.register(self.save_history, histfile)256257 def save_history(self, histfile):258 readline.set_history_length(1000)259 readline.write_history_file(histfile)260```261262> **Примечание**263>264> Новая [REPL](https://python-all.ru/3.15/glossary.html#term-REPL), представленная в версии 3.13, не поддерживает readline. Однако readline по-прежнему можно использовать, задав переменную окружения [`PYTHON_BASIC_REPL`](https://python-all.ru/3.15/using/cmdline.html#envvar-PYTHON_BASIC_REPL).265