多行编辑与历史记录

在 REPL 里连续试验时，你会不断重复前面的输入。Python 通过 readline 模块与历史文件提供了历史记录能力：可以按上下方向键翻回旧命令、用 Ctrl-R 反向搜索、把一次输入的多行代码作为整体重新调出。Python 3.13 的新 REPL 进一步强化了多行编辑与历史浏览体验。

前置知识

阅读本节前，建议先了解：Python 3.13 改进的 REPL

基础概念

历史记录功能由两层机制配合完成：

层	作用	体现
会话内历史	当前会话中已输入的内容保存在内存	方向键、Ctrl-R 搜索
持久化历史	会话结束时写入文件，下次启动读回	~/.python_history

在 3.13 之前，历史记录完全依赖 readline 模块；3.13 的新 REPL 不再以 readline 为后端，但仍然读取和写入同一个历史文件，因此升级不会丢失已有历史。

多行输入在历史中的存储方式值得注意：

• 旧 REPL：多行代码会被拆成多条历史条目，重新调出时需要逐行找。
• 新 REPL：一次输入的完整代码块作为一条历史条目，可整体重新编辑。

readline 模块提供的主要能力：

功能	默认键位
上一条/下一条	↑ / ↓
反向增量搜索	Ctrl-R
正向增量搜索	Ctrl-S
行首/行尾	Ctrl-A / Ctrl-E
光标左/右移一个词	Alt-B / Alt-F
删除到行尾	Ctrl-K
清屏	Ctrl-L
中断当前输入	Ctrl-C
发送 EOF / 退出	Ctrl-D

需要理解的是：Ctrl-S 在部分终端被「暂停输出」占用，可能需要先执行 stty -ixon 解除。这是终端层面的限制，与 Python 无关。

语法与用法

查看历史文件的默认位置与内容：

# 默认历史文件（由 readline 在会话结束时写入）
ls -l ~/.python_history

# 查看最近若干条历史
tail -n 20 ~/.python_history

# 在 REPL 中查看历史文件路径
python -c "import readline; print(readline.get_history_length())"

在会话中操作历史：

>>> x = 100
>>> y = 200
>>> x + y
300

# 按 ↑ 回到 'x + y'，再按 ↑ 回到 'y = 200'，继续按 ↑ 逐条回溯
# 按 Ctrl-R 后输入 'y'，会搜索最近包含 'y' 的历史条目

读取与写入历史（需要 readline 模块）：

import readline

# 读取默认长度上限（-1 表示不限制）
print(readline.get_history_length())

# 手动读取历史文件（通常在启动时由 site 自动完成）
readline.read_history_file("~/.python_history")

# 查看当前会话已有的历史条目数
print(readline.get_current_history_length())

新 REPL 中的历史浏览：

# 按 F2 打开历史浏览器
# - 只显示输入过的代码，跳过输出与 >>> / ... 提示符
# - 支持在条目间跳转与搜索
# - 按 q 或 Esc 退出

详细说明

历史文件的位置与格式

默认历史文件为 ~/.python_history（Windows 上为 %USERPROFILE%\.python_history），是纯文本，一行一条。site 模块在启动时自动读取它，在会话结束时写入。

历史文件遵循 PYTHON_HISTORY 环境变量：

# 自定义历史文件位置（Python 3.13+ 支持）
export PYTHON_HISTORY="$HOME/.cache/python/history"

# 想每次都是全新会话（不留历史）
export PYTHON_HISTORY=/dev/null

在多用户或容器环境中，把历史文件放到 /dev/null 可以避免历史互相污染。

PYTHONSTARTUP 与历史的配合

启动文件（PYTHONSTARTUP 指向的脚本）只在交互模式下执行，是配置历史行为的常见位置：

# ~/.pythonrc.py
import atexit
import os
import readline
from pathlib import Path

# 使用自定义历史文件
history_path = Path(os.environ.get("PYTHON_HISTORY", Path.home() / ".python_history"))

# 启动时读取已有历史
if history_path.exists():
    readline.read_history_file(history_path)

# 设置内存中最多保留的历史条数
readline.set_history_length(2000)

# 退出时写回历史文件
atexit.register(readline.write_history_file, history_path)

这段配置显式地完成了 site 默认做的事，好处是可以自定义路径、长度与时机。更完整地介绍见 启动文件与配置。

多行编辑的两种模式

多行输入的处理方式取决于使用的是哪套 REPL：

旧 REPL（3.12 及以前）：进入 ... 续行状态后，若发现前面某行写错，只能按 Ctrl-C 取消整个代码块重新输入。历史里这些行是分散的。

新 REPL（3.13+）：进入多行输入后，可以用方向键在已输入的多个行之间移动光标，直接修改任意一行；执行后，整个代码块作为一条历史保存。

>>> def process(items: list[int]) -> list[int]:
...     """把每个元素乘以 2。"""      # 可用方向键上移到这里修改
...     return [item * 2 for item in items]
...
>>> process([1, 2, 3])
[2, 4, 6]

这种「可回溯编辑」的能力，是 3.13 新 REPL 相较旧版最实用的改进之一。

交互式搜索：Ctrl-R

Ctrl-R 进入反向增量搜索，输入关键字后立刻定位到最近一条匹配的历史：

(reverse-i-search)`proce': process([1, 2, 3])

使用技巧：

• 再次按 Ctrl-R 跳到更早的匹配项；
• 按 Enter 或方向键接受并退出搜索；
• 按 Ctrl-C 或 Esc 取消搜索；
• 搜索基于子串匹配，因此输入关键字片段即可。

历史在文件中的保存策略与 HISTFILE

Python 的 readline 绑定遵循底层库的配置，但 Python 自身只依赖 ~/.python_history。需要注意：

• 历史文件默认没有防重：连续相同命令也会全部记下。
• 历史文件不会自动截断：readline.set_history_length() 只影响写入条数上限。
• 若历史文件权限过宽，可能泄露敏感输入（如 API Token）。建议 chmod 600。

# 保护历史文件权限
chmod 600 ~/.python_history

敏感信息的处理

REPL 历史会原样记录你输入的一切，包括密码、Token。几个缓解手段：

• 用环境变量或配置文件提供凭据，而不是在 REPL 输入；
• 输入敏感内容后立刻 readline.remove_history_item() 删除；
• 会话结束后手工清理对应行；
• 不要在共享服务器上保留个人历史。

import readline

# 删除最近一条历史（索引从 1 开始，最后一条为 get_current_history_length()）
index = readline.get_current_history_length()
if index > 0:
    readline.remove_history_item(index - 1)
print("已删除最近一条历史")

让多行代码整体可复用的技巧

REPL 中调出的多行历史可以整体编辑，但若想真正复用，仍应保存到文件。常见做法：

• 在 REPL 中试通后，复制到编辑器并整理成函数；
• 使用 python -i 加载已保存的模块，在会话中调用；
• 对经常重用的片段，封装成模块放进 PYTHONPATH。

历史文件与不同解释器的隔离

同一台机器上有多个 Python 版本时，它们默认共用同一个 ~/.python_history。若要隔离：

# 在 Shell 别名中为不同版本指定不同历史文件
alias py312='PYTHON_HISTORY=~/.python_history_312 python3.12'
alias py313='PYTHON_HISTORY=~/.python_history_313 python3.13'

这样既保留历史，又避免不同项目或版本的输入互相干扰。

实战示例

示例一：给历史文件做自动归档

长期使用后历史文件会变得很大且混杂。下面脚本按时间归档并去重，保留最近使用频次高的条目。

# tidy_history.py
from __future__ import annotations

from collections import Counter
from datetime import date
from pathlib import Path

HISTORY = Path.home() / ".python_history"


def load_entries(path: Path) -> list[str]:
    """读取历史文件，返回非空、去首尾空白的条目列表。"""
    if not path.exists():
        return []
    lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
    return [line.strip() for line in lines if line.strip()]


def backup(path: Path) -> Path:
    """把当前历史归档到带日期的备份文件。"""
    target = path.with_suffix(f".{date.today().isoformat()}.bak")
    target.write_text(path.read_text(encoding="utf-8", errors="replace"), encoding="utf-8")
    return target


def top_entries(entries: list[str], limit: int = 10) -> list[tuple[str, int]]:
    """统计出现频次最高的条目。"""
    return Counter(entries).most_common(limit)


if __name__ == "__main__":
    entries = load_entries(HISTORY)
    if not entries:
        print("没有可归档的历史")
    else:
        saved = backup(HISTORY)
        print(f"已备份到 {saved}，共 {len(entries)} 条")
        print("\n最常出现的命令：")
        for command, count in top_entries(entries):
            print(f"{count:>4}  {command}")

先备份再处理，是操作历史文件的安全前提——一旦写坏，至少还能恢复。

示例二：为 REPL 添加「历史去重」

readline 默认不防重，导致同一命令反复出现。可以在启动文件中开启去重。

# ~/.pythonrc.py（片段）
import readline


def _dedupe_history() -> None:
    """把当前会话的历史去重，保留每个条目的最后一次出现位置。"""
    length = readline.get_current_history_length()
    seen: dict[str, int] = {}
    for index in range(1, length + 1):
        item = readline.get_history_item(index)
        if item is not None:
            seen[item] = index
    # 删除重复项：从后往前删，避免索引错位
    keep = set(seen.values())
    for index in range(length, 0, -1):
        if index not in keep:
            readline.remove_history_item(index - 1)


print("提示：输入 dedupe() 可对当前历史去重")
dedupe = _dedupe_history

这样在长会话中历史列表会保持精简，Ctrl-R 搜索也更快。

示例三：用 python -i 配合历史做探索式调试

结合历史与 -i，可以让「加载数据 → 反复查询」的流程非常顺畅。

# explore.py
from __future__ import annotations

from dataclasses import dataclass


@dataclass
class Order:
    """订单记录。"""

    order_id: int
    amount: float
    status: str


def load_orders() -> list[Order]:
    """返回一批示例订单。"""
    return [
        Order(1, 99.5, "paid"),
        Order(2, 0.0, "cancelled"),
        Order(3, 240.0, "paid"),
        Order(4, 15.0, "refunded"),
    ]


orders = load_orders()
print(f"已加载 {len(orders)} 条订单，可在 REPL 中查询变量 orders")

$ python -i explore.py
已加载 4 条订单，可在 REPL 中查询变量 orders

>>> [o for o in orders if o.status == "paid"]
[Order(order_id=1, amount=99.5, status='paid'), Order(order_id=3, amount=240.0, status='paid')]

>>> sum(o.amount for o in orders if o.status == "paid")
339.5

# 按 ↑ 可快速调出上一条并微调条件
>>> sum(o.amount for o in orders if o.status != "paid")
15.0

命令都留在历史中，稍后按 ↑ 或 Ctrl-R 即可再次使用，无需重新键入。

示例四：跨设备同步历史（可选）

若希望在多台机器间共享探索历史，可把历史文件放到同步目录：

# 在 Shell 配置中指定统一的历史位置
export PYTHON_HISTORY="$HOME/Dropbox/dotfiles/python_history"

需要注意：

• 同步过程中若两个会话同时写入，可能产生冲突；
• 历史中可能包含敏感信息，同步前应评估风险；
• 更稳妥的做法是同步一份自定义启动文件，由它决定历史策略。

注意事项

• 历史默认记录一切：包括误输入的密码与 Token，共享机器上尤须谨慎。
• 历史文件权限应为 600：避免其他用户读取。
• Ctrl-S 可能被终端占用：可用 stty -ixon 解除，否则正向搜索无法使用。
• 旧 REPL 的多行历史是分散的：调出时需逐行拼接，建议升级到 3.13+ 或用 IPython。
• 历史文件不会自动去重：长期使用会积累大量重复条目。
• readline 在部分环境不可用：极简容器或未链接 readline 的解释器上，历史功能受限。
• ~ 在 readline.read_history_file 中不展开：应使用 Path.home() 拼出绝对路径，或先 os.path.expanduser()。
• 历史文件被并发写入可能损坏：多标签页同时运行 Python 时，最后退出者会覆盖文件。

常见问题

Q：为什么按 ↑ 没有历史？ 可能是当前解释器未链接 readline；可执行 python -c "import readline" 检查，若报 ModuleNotFoundError 说明缺失。

Q：历史文件在哪？ 默认 ~/.python_history。3.13+ 可通过 PYTHON_HISTORY 环境变量自定义。

Q：如何彻底关闭历史？ 设 PYTHON_HISTORY=/dev/null，或在 PYTHONSTARTUP 脚本中不注册写入函数。

Q：多行代码历史调出后能整体执行吗？ 可以。新 REPL 把代码块作为一条历史，调出后按回车即可整体执行；旧 REPL 需逐行调出。

Q：历史会包含 help() 的翻页内容吗？ 不会。历史只记录你输入的代码行，不记录输出内容。

Q：F2 历史和 Ctrl-R 有什么区别？ F2 是可视化的条目列表，适合浏览；Ctrl-R 是关键字增量搜索，适合快速定位。

最佳实践

1. 定期备份并归档 ~/.python_history，避免文件无限膨胀。
2. 把历史文件权限设为 600，不敏感的历史与凭据严格分开。
3. 用 PYTHON_HISTORY 为不同 Python 版本或项目隔离历史。
4. 在启动文件中设置 readline.set_history_length()，限制内存占用。
5. 优先使用 3.13+，享受整块多行历史带来的复用便利。
6. 养成用 Ctrl-R 而非反复按方向键的习惯，能显著减少重复输入。
7. 敏感操作后立即用 readline.remove_history_item() 清理对应条目。

下一节

继续学习：颜色高亮与自动补全

参考链接

• Python 官方文档：readline 模块
• Python 官方文档：atexit 模块
• PEP 762 – REPL-acing the default REPL
• GNU Readline 官方手册