目录

• 13 · loader.py：加载流水线与插件执行顺序
  • 1. 模块解决什么问题
  • 2. 结构一览
  • 3. 三个入口
  • 4. pickle 磁盘缓存
  • 5. _parse_recursive：include 展开与选项合并
  • 6. _load：四阶段流水线
  • 7. run_transformations：插件顺序与异常隔离
  • 8. 设计决策与理由
  • 9. 行为细节与边界
  • 10. 测试锁定了什么
  • 11. 演变史
  • 12. 与其他模块的关系
  • 13. 参考索引

13 · loader.py：加载流水线与插件执行顺序

核对基线 · 范围 · 依赖

核对基线：beancount 仓库 commit 97472138（2026-08-22）。路径相对仓库根目录，引用格式 文件:起-止行 (名称)，行号已逐条核对。 本篇范围：beancount/loader.py（847 行）与 beancount/loader_test.py（740 行）。 上游依赖：beancount/parser/parser.py（parse_file/parse_string）、beancount/parser/booking.py（book）、beancount/ops/validation.py（validate）、beancount/parser/options.py（OPTIONS_DEFAULTS）、beancount/utils/encryption.py、beancount/parser/printer.py（print_errors）、beancount/core/data.py（entry_sortkey、new_metadata）、beancount/utils/misc_utils.py（log_time、uniquify）。 下游使用者：包内 9 个非测试文件引用本模块。beancount/api.py:77-79 再导出 load_doc/load_encrypted_file/load_file；beancount/scripts/check.py:72、beancount/scripts/doctor.py:135 等是实际调用点；beancount/parser/parser.py:136 与 beancount/ops/summarize.py:41 只在 TYPE_CHECKING 下取 OptionsMap 别名。

1. 模块解决什么问题

parser.parse_file 只负责一个文件的文本：产出的指令里还留着待推算的数字，pad、balance 这类要看到全局余额才能兑现的指令还是原样，include 只是记在 options 里的一串文件名。loader.py 是把这些补齐的唯一入口，对外只做一件事——给一个顶层文件名或一段字符串，拿回 (entries, errors, options_map)。它决定四件别处决定不了的事：阶段顺序（解析 → booking → 插件 → 校验）、内置插件相对用户插件的前后位置、多份文件的选项如何并成一份、能否复用上次的加载结果。

2. 结构一览

3. 三个入口

3.1 load_file：路径归一化后二选一

filename = path.expandvars(path.expanduser(filename))
if not path.isabs(filename):
    filename = path.normpath(path.join(os.getcwd(), filename))

if encryption.is_encrypted_file(filename):
    # Note: Caching is not supported for encrypted files.
    entries, errors, options_map = load_encrypted_file(
        filename, log_timings, log_errors, extra_validations, False, encoding
    )
else:
    entries, errors, options_map = _load_file(
        filename, log_timings, extra_validations, encoding
    )
    _log_errors(errors, log_errors)

beancount/loader.py:114-127。环境变量与 ~ 展开来自 commit 8fb6af0d；转绝对路径是 _parse_recursive 里 assert path.isabs(source)（beancount/loader.py:432）的前提。加密文件走单独分支且明确不进缓存。非加密分支调的是模块级名字 _load_file，由 initialize 绑定（第 4 节），这层间接使缓存可开关、可替换。两个分支打印错误的位置不同：加密分支由它转交的 load_string 调 _log_errors。

3.2 load_string 与 load_encrypted_file

load_string（beancount/loader.py:341-373）可选先 textwrap.dedent（供 load_doc 用缩进的 docstring），再调 _load([(string, False)], ...)，元组第二位 False 表示这是内容而非文件名。load_encrypted_file（beancount/loader.py:131-161）解密后把明文交给 load_string，丢掉了 filename 上下文；自身的 dedent 参数未转给这次 load_string 调用（beancount/loader.py:154-161），传什么值都无效。这与被 include 的加密文件不同——后者在 _parse_recursive 里仍把 source_filename 传给 parse_string（见 5.3），只有顶层加密文件丢失文件名上下文。两者均不经 _load_file，与缓存无关。

4. pickle 磁盘缓存

4.1 缓存位置与命中条件

def needs_refresh(options_map: OptionsMap) -> bool:
    if options_map is None:
        return True
    input_hash = compute_input_hash(options_map["include"])
    return "input_hash" not in options_map or input_hash != options_map["input_hash"]

beancount/loader.py:309-320。缓存路径由 get_cache_filename（beancount/loader.py:180-195）算出：模板是绝对路径就直接用，否则拼到顶层文件目录下，{filename} 填 basename，默认落在账本旁成为 .apples.beancount.picklecache。compute_input_hash（beancount/loader.py:323-338）对排序后的文件名逐个喂 md5：文件名本身，以及 struct.pack("dd", stat.st_mtime_ns, stat.st_size)；文件不存在时只喂名字，不读文件内容——路径、mtime_ns、大小三项不变而内容被改，缓存不会失效（CHANGES:2829-2833 加入 mtime+size 哈希时称"paves the way for hashing the contents"，此后未实现）。options_map["include"] 在解析末尾被覆写成本次真正读过的全部绝对路径（beancount/loader.py:525），已记录在案的文件——包括深层 include——都参与这份指纹，input_hash 在流水线末尾算出存进 options（beancount/loader.py:634），二者一起被 pickle 进缓存。beancount/loader_test.py:593-625 只覆盖顶层文件被移动后 needs_refresh 返回真，深层 include 的元数据变化无对应测试。大小与 mtime 一起哈希是为绕开只有一秒精度的文件系统（CHANGES:2829-2832）。

4.2 写入门槛与三处失败容忍

pickle_cache_function（beancount/loader.py:198-277）的包装按序做：读缓存 → 反序列化 → needs_refresh 判定 → 命中即 return result。三处容错都不抛异常：反序列化 except Exception 全兜（注释说损坏或过期的 pickle 会以各种异常类型冒出来）后 logging.error 重算（beancount/loader.py:231-241），删旧缓存失败与写缓存失败各只 warning（beancount/loader.py:250-259、beancount/loader.py:266-274）。写盘还有门槛：耗时 >= PICKLE_CACHE_THRESHOLD（1.0 秒）才落盘（beancount/loader.py:264-273）。delete_cache_function（beancount/loader.py:280-301，缓存关闭时启用）同样调 os.remove，但无 try 包裹（beancount/loader.py:295-296）：删除失败直接抛出，与 pickle_cache_function 对 os.remove 的容错（beancount/loader.py:252-258）不同。

4.3 initialize：缓存开关与两个环境变量

cache_pattern = (
    cache_filename or os.getenv("BEANCOUNT_LOAD_CACHE_FILENAME") or PICKLE_CACHE_FILENAME
)
cache_getter = functools.partial(get_cache_filename, cache_pattern)
if use_cache:
    _load_file = pickle_cache_function(cache_getter, PICKLE_CACHE_THRESHOLD, _uncached_load_file)
else:
    ...
    _load_file = delete_cache_function(cache_getter, _uncached_load_file)

beancount/loader.py:826-843（有省略）。模块末尾 initialize(os.getenv("BEANCOUNT_DISABLE_LOAD_CACHE") is None)（beancount/loader.py:847）在导入时执行一次：默认开缓存，设了该环境变量就关。关掉时绑的不是"直接调用"而是 delete_cache_function（beancount/loader.py:280-301），先删已有缓存再计算；理由见 commit d9a70473：用 --no-cache 调试插件后再启用缓存，会用回旧缓存，令人困惑。bean-check 的 --no-cache/--cache-filename 靠再调一次 initialize 覆盖（beancount/scripts/check.py:65-67）；use_cache=False 却给了文件名时打 warning 说该参数被忽略（beancount/loader.py:838-842）。

5. _parse_recursive：include 展开与选项合并

5.1 队列驱动，广度优先

source_stack = list(sources)
filenames_seen = set()
while source_stack:
    source, is_file = source_stack.pop(0)
    is_top_level = options_map is None

beancount/loader.py:406-415。变量叫 stack，实际 pop(0) 配末尾 append（beancount/loader.py:518）是 FIFO 队列，include 广度优先展开。"是否顶层"用 options_map is None 判断，只有最先处理的源的 options 被采纳。

5.2 去重、缺失、glob

文件源在这里被断言为绝对路径（assert path.isabs(source)，beancount/loader.py:432），normpath 归一后查 filenames_seen：命中就追加 Duplicate filename parsed 并跳过（beancount/loader.py:435-445），这是防 include 成环的唯一手段；文件不存在则追加 File "..." does not exist 并跳过（beancount/loader.py:447-455）。include 项先做 glob 展开（beancount/loader.py:492-509）：相对模式拼到当前文件目录下，glob.glob(..., recursive=True) 支持 **，匹配不到报 File glob "..." does not match any files。相对基准分两种：文件源用自身所在目录（beancount/loader.py:419、beancount/loader.py:459），字符串源用进程工作目录（beancount/loader.py:427）。commit 793d8be9 之前用 chdir() 包住 glob.glob，改显式拼路径为线程安全。

5.3 加密 include 的特殊路径

if is_file:
    cwd = path.dirname(source)
    source_filename = source
    if encryption.is_encrypted_file(source):
        source = encryption.read_encrypted_file(source)
        is_file = False

beancount/loader.py:417-423。被 include 的加密文件就地解密并降级成字符串源，随后走 parse_string(source, source_filename)（beancount/loader.py:474-477）——文件名仍传给解析器用作 metadata，但 is_file 已是 False，它不进 filenames_seen，因此既不参与重复检测也不出现在 options_map["include"] 里。cwd 在降级前已按文件目录设好，其中的相对 include 仍相对它自己解析（commit 957001b8，#325）。

5.4 选项：顶层独占，三项聚合

顶层文件的 options_map 被整份采用，其余收进 other_options_map（beancount/loader.py:487-490），注释写明 "No merging of options should occur"。若无一个源解析成功，退回 options.OPTIONS_DEFAULTS.copy()（beancount/loader.py:521-522）；随后 options_map["include"] = sorted(filenames_seen)（beancount/loader.py:525）覆写原始 include 声明。aggregate_options_map（beancount/loader.py:532-560）只聚合三样：operating_currency 去重合并、dcontext 用 update_from 把各文件的显示精度并进顶层那一份（beancount/loader.py:548-551）、由开了 insert_pythonpath 的文件所在目录生成 pythonpath 列表（beancount/loader.py:553-558）。pythonpath 不是用户可写选项，是这里合成的中间值。

6. _load：四阶段流水线

with misc_utils.log_time("parse", log_timings, indent=1):
    entries, parse_errors, options_map = _parse_recursive(sources, log_timings, encoding)
    entries.sort(key=data.entry_sortkey)
with misc_utils.log_time("booking", log_timings, indent=1):
    entries, balance_errors = booking.book(entries, options_map)
    parse_errors.extend(balance_errors)
with misc_utils.log_time("run_transformations", log_timings, indent=1):
    saved_pythonpath = list(sys.path)
    try:
        if "pythonpath" in options_map:
            sys.path[0:0] = options_map["pythonpath"]
        entries, errors = run_transformations(entries, parse_errors, options_map, log_timings)
    finally:
        sys.path[:] = saved_pythonpath
with misc_utils.log_time("beancount.ops.validate", log_timings, indent=1):
    valid_errors = validation.validate(entries, options_map, log_timings, extra_validations)
    errors.extend(valid_errors)
options_map["input_hash"] = compute_input_hash(options_map["include"])

beancount/loader.py:598-634。各阶段产物：解析给出仍带未完成金额的指令，按 entry_sortkey（日期、类型序、行号）排一次——提前到 booking 之前是 commit 51226691（#84）的修正，因跨文件指令顺序影响库存匹配；booking.book 补齐仓位与推算数字并顺带跑 validate_missing_eliminated（beancount/parser/booking.py:26-54），返回 (entries, errors) 二元组；run_transformations 执行全部插件，同样返回二元组；validation.validate 运行标准校验加调用方传入的 extra_validations 并收集错误，只返回错误列表（beancount/ops/validation.py:410-436），bean-check 传 HARDCORE_VALIDATIONS。四段接口不统一，_load 逐段拆包、显式汇总，末尾才组装成三元组返回（beancount/loader.py:634）；booking 调用本就在插件之前，commit 0e46c762 把 booking.interpolate 换成 booking.book()，并入 inventory-booking validation。标准校验按只读用途编写，但接口和调用方都不强制校验函数保持 entries 不变——loader 注释提到可比较前后哈希确认，"目前没做"（beancount/loader.py:629-631）。sys.path 改动包在 try/finally，只在插件阶段生效（commit bb87d7e5 从 grammar 层移来）；末行把输入指纹写进 options 供缓存判定。

7. run_transformations：插件顺序与异常隔离

7.1 三段拼接与两种模式

if options_map["plugin_processing_mode"] == "raw":
    plugins_iter = options_map["plugin"]
elif options_map["plugin_processing_mode"] == "default":
    plugins_iter = itertools.chain(
        PLUGINS_PRE, options_map["plugin"], PLUGINS_AUTO, PLUGINS_POST
    )

beancount/loader.py:662-667。默认顺序是 documents → 用户插件 → --auto 插件 → pad → balance。raw 模式内置插件全不跑，选项文档说其用途是让用户完全掌控顺序（beancount/parser/options.py:616-621）。分前后两组的理由在两端各自职责：documents（注册于 beancount/ops/documents.py:17,35-36）生成 Document 指令，放前面让用户插件看得到产物；pad 与 balance（注册于 beancount/ops/pad.py:18,29-34、beancount/ops/balance.py:17,48-60）依据全部交易算余额、补齐、校验，任何插件增改交易都会改变结果，所以放最后，且 pad 先于 balance。pad 原本在 PLUGINS_PRE，commit 60f1c40f（#742）移到 PLUGINS_POST：插件生成的交易此前不被 pad 计入，与"padding 让随后的 balance 断言成立"的语义不符，同一提交在 beancount/ops/pad_test.py 补了回归测试。PLUGINS_AUTO 默认空，只有 bean-check --auto 临时 extend 进 DEFAULT_PLUGINS_AUTO 并在 finally 还原（beancount/scripts/check.py:53-85）。

7.2 导入与执行的异常边界

导入阶段只吞 ImportError，转成一条 Error importing "..." 并继续下一个插件；其它 import 期异常按注释是有意让整次运行失败（beancount/loader.py:683-700）。没有 __plugins__ 的模块被静默跳过。执行阶段每个回调单独包 try，捕获 Exception 转成带完整 traceback 的 Error applying plugin "..."（beancount/loader.py:717-736）。__plugins__ 的元素可以是函数名字符串，也可以是函数对象（beancount/loader.py:705-711），后者是 commit 312a6e88 为 beancount.plugins.auto 这类元插件加的，combine_plugins（beancount/loader.py:745-757）把若干模块的函数对象拼成一个列表。配置为 None 时回调只收两参数，否则三个（beancount/loader.py:713-715，TODO 称 v3 想统一）。每个插件模块跑完（不是每个函数跑完）重排一次 entries，注释是 "Don't trust the plugins themselves"（beancount/loader.py:738-740）。回调抛异常时外层赋值 entries, plugin_errors = callback(...) 不会执行，但若回调抛错前已对 entries 做过原地修改，那部分改动仍留在后续流程——这里没有快照或回滚（beancount/loader.py:717-724）。

8. 设计决策与理由

9. 行为细节与边界

10. 测试锁定了什么

loader_test.py 共 32 个测试方法，分五个类。

覆盖方式两点：缓存类的 setUp（beancount/loader_test.py:524-535）用 mock.patch 把 _load_file 换成阈值为 0 的 pickle_cache_function 并包一层计数器，是否命中缓存靠 self.num_calls 断言；test_load_cache_read_only_fs 的两个 mock 形参名与实际相反（装饰器自下而上，第一个形参对应 logging.warning），被断言调用一次的 warn_mock 其实是 os.remove，它锁定的是失效时尝试删除一次且不崩溃。

本文件未覆盖：load_encrypted_file 本身及 load_file 对顶层加密文件的分派，无测试直接调用（加密 include 路径由 beancount/utils/encryption_test.py:179-211 覆盖，但顶层文件本身未加密）、raw 模式的插件序列（beancount/parser/grammar_test.py:711-731 只测选项解析，raw 的效果散见于用它做隔离手段的 beancount/ops/documents_test.py）、combine_plugins、dcontext 聚合、内置插件相对顺序（回归测试在 beancount/ops/pad_test.py）、插件配置参数传递、缓存损坏分支。

11. 演变史

2017-04-30 commit 859f341e 之前本文件路径是 src/python/beancount/loader.py，下表中更早的提交需按旧路径检索。

12. 与其他模块的关系

• 上游：parser.parse_file/parse_string 给出单文件的指令、错误与 options；booking.book 补齐仓位与推算数字（07 篇 interpolate 是其中一环）；validation.validate 做只读检查；options.OPTIONS_DEFAULTS 兜底；encryption 判定与解密；printer.print_errors 输出错误；misc_utils.log_time 分阶段计时。
• DisplayContext：解析器为每个文件统计一份 dcontext（06 篇），loader 用 update_from 并进顶层那一份，渲染精度因而是全账本合并的结果（beancount/loader.py:550）。
• 插件契约：__plugins__ 的元素可以是函数名字符串，也可以是函数对象（beancount/loader.py:705-711）；签名 (entries, options_map[, config]) -> (entries, errors)（beancount/parser/options.py:273-297，该处 docstring 仍只提"函数名"，未随 commit 312a6e88 加入的函数对象支持同步更新）；内置三个插件用同一契约。
• 下游：bean-check 是仓库内唯一暴露 --no-cache/--cache-filename/--auto 命令行选项的脚本（beancount/scripts/check.py:53-67）；缓存另可经 loader.initialize() 与两个环境变量控制（见 4.3 节），不止 bean-check 一途。bean-doctor 多处调 load_file；load_doc 被全仓库测试当作"docstring 即账本"的装饰器。

13. 参考索引

beancount/loader.py：45-50 LoadError；53-68 三个插件常量；71 RENAMED_MODULES；74-79 缓存常量；81-85 _load_file 声明；89-128 load_file；114-127 入口分支；131-161 load_encrypted_file；164-177 _log_errors；180-195 get_cache_filename；198-277 pickle_cache_function；231-241 损坏缓存；243-259 删除失败；264-273 写入门槛；280-301 delete_cache_function；304-306 _uncached_load_file；309-320 needs_refresh；323-338 compute_input_hash；341-373 load_string；376-529 _parse_recursive；404-415 队列与去重集合；417-423 加密降级；430-455 去重与缺失；457-477 两种解析调用；484-490 options 采纳；492-518 glob 与入队；521-527 收尾；532-560 aggregate_options_map；563-636 _load；598-634 四阶段；639-742 run_transformations；662-673 模式与拼接；683-700 导入异常；702-716 回调解析与参数；717-736 执行异常；738-740 重排；745-757 combine_plugins；760-808 load_doc；811-844 initialize；847 模块级装配。

beancount/loader_test.py：57-164 TestLoader；167-212 TestLoadDoc；216-518 TestLoadIncludes；523-711 TestLoadCache（524-535 setUp 的 mock 装配）；714-737 TestOptionsAggregation。

其它：beancount/parser/options.py:24-36 模式校验器、beancount/parser/options.py:233-247 include、beancount/parser/options.py:248-258 input_hash、beancount/parser/options.py:259-266 dcontext、beancount/parser/options.py:273-297 plugin、beancount/parser/options.py:614-631 plugin_processing_mode、beancount/parser/options.py:718-724 insert_pythonpath、beancount/parser/options.py:741 只读选项；beancount/parser/booking.py:26-54；beancount/ops/validation.py:410-436；beancount/ops/documents.py:17；beancount/ops/pad.py:18；beancount/ops/balance.py:17；beancount/plugins/auto.py:17；beancount/scripts/check.py:53-85；beancount/api.py:77-79；beancount/parser/grammar_test.py:711-731；CHANGES:266-277,2829-2832,2965-2975。

commit：0e46c762（2015-07-26）、2d68cf72（2015-11-09）、661bfbea（2015-11-29）、51226691（2015-12-01）、794a7b54（2015-12-06）、4f87d1a3（2015-12-07）、eba4a664（2015-12-12）、22340365（2015-12-12）、2f4ff797（2015-12-13）、6c3434d7（2015-12-16）、8fb6af0d（2015-12-21）、f7f0d5ce（2016-01-09）、4e1aaccd（2016-03-05）、845e9caa（2016-04-17）、be478072（2016-04-18）、859f341e（2017-04-30）、312a6e88（2017-05-24）、c16864f4（2018-03-23）、44dfdd3d（2018-03-27）、957001b8（2018-08-23）、5fa98017（2020-05-25）、d9a70473（2020-06-02）、628acbfa（2020-12-14）、c46eaacd（2021-05-15）、bb87d7e5（2021-09-26）、cb3526a1（2021-12-05）、60f1c40f（2024-01-06）、793d8be9（2024-11-28）、0265c999（2024-12-04）、955876a9（2024-12-16，合入序在 85950542 之后）、85950542（2024-12-22）。