readline — GNU readline 接口

---

readline 模块定义了许多函数，用于方便从 Python 解释器完成和读/写历史文件。此模块可以直接使用，也可以通过 rlcompleter 模块使用，该模块支持在交互式提示符下完成 Python 标识符。使用此模块进行的设置会影响解释器的交互式提示符和内置 input() 函数提供的提示符的行为。

Readline 键绑定可以通过初始化文件进行配置，通常是您主目录中的 .inputrc 文件。有关该文件的格式和允许结构以及 Readline 库的总体功能的信息，请参阅 GNU Readline 手册中的 Readline 初始化文件。

注意

底层的 Readline 库 API 可以由 libedit 库而不是 GNU readline 实现。在 macOS 上，readline 模块会在运行时检测正在使用哪个库。

libedit 的配置文件与 GNU readline 的配置文件不同。如果您以编程方式加载配置字符串，则可以检查 readline.__doc__ 中的文本“libedit”，以区分 GNU readline 和 libedit。

如果您在 macOS 上使用 editline/libedit readline 仿真，则位于您主目录中的初始化文件名为 .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])

执行 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])

加载 readline 历史文件，并将其附加到历史列表中。默认文件名是 ~/.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* 的历史记录项的当前内容。项目索引从 1 开始。这将调用底层库中的 history_get()。

readline.remove_history_item(pos)

从历史记录中删除由其位置指定的项。位置从 0 开始。这将调用底层库中的 remove_history()。

readline.replace_history_item(pos, line)

将由其位置指定的项替换为 *line*。位置从 0 开始。这将调用底层库中的 replace_history_entry()。

readline.add_history(line)

将 *line* 追加到历史记录缓冲区，就好像它是最后输入的行一样。这将调用底层库中的 add_history()。

readline.set_auto_history(enabled)

启用或禁用通过 readline 读取输入时自动调用 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，则删除任何已安装的函数。在打印第一个提示符之后，以及 readline 开始读取输入字符之前，将不带参数地调用该钩子。仅当 Python 是为支持该功能的库版本编译时，此函数才存在。

自动完成

以下函数与实现自定义单词自动完成函数有关。这通常由 Tab 键操作，可以建议并自动完成正在键入的单词。默认情况下，Readline 设置为由 rlcompleter 使用，以完成交互式解释器的 Python 标识符。如果要将 readline 模块与自定义自动完成器一起使用，则应设置一组不同的单词分隔符。

readline.set_completer([function])

设置或删除自动完成函数。如果指定了 *function*，它将用作新的自动完成函数；如果省略或为 None，则删除任何已安装的自动完成函数。自动完成函数的调用方式为 function(text, state)，其中 *state* 为 0、1、2……，直到它返回一个非字符串值。它应该返回以 *text* 开头的下一个可能的自动完成。

已安装的自动完成函数由传递给底层库中的 rl_completion_matches() 的 *entry_func* 回调调用。*text* 字符串来自底层库的 rl_attempted_completion_function 回调的第一个参数。

readline.get_completer()

获取自动完成函数，如果未设置自动完成函数，则返回 None。

readline.get_completion_type()

获取正在尝试的自动完成类型。这将以整数形式返回底层库中的 rl_completion_type 变量。

readline.get_begidx()

readline.get_endidx()

获取补全范围的起始或结束索引。这些索引是传递给底层库的 rl_attempted_completion_function 回调函数的 *start* 和 *end* 参数。根据底层的 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])

设置或移除补全显示函数。如果指定了 *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)