目录

• 17 · getters.py：从指令流提取账户、币种与时间信息
  • 1. 模块解决什么问题
  • 2. 结构一览
  • 3. 账户提取：GetAccounts
  • 4. 其余提取函数
  • 5. 设计决策与理由
  • 6. 行为细节与边界
  • 7. 测试锁定了什么
  • 8. 演变史
  • 9. 与其他模块的关系
  • 10. 参考索引

17 · getters.py：从指令流提取账户、币种与时间信息

核对基线 · 范围 · 依赖

核对基线：beancount 仓库 commit 97472138（2026-08-22）。路径相对仓库根目录，引用格式 文件:起-止行 (名称)，行号已逐条核对。 本篇范围：beancount/core/getters.py（382 行）与 beancount/core/getters_test.py（270 行）。 上游依赖：beancount/core/data.py（运行时只导入 Close、Commodity、Open、Transaction 四个指令类，getters.py:15-18）、beancount/core/account.py（split）。其余类型名放在 TYPE_CHECKING 块里（:20-34）。 下游使用者：15 个非测试文件导入本模块；beancount/api.py:60-61 只把 get_account_open_close 与 get_accounts 两个名字重新导出。

1. 模块解决什么问题

账本加载完是一条按日期排好序的指令列表（Directives = list[Directive]，data.py:504）。很多操作要的不是逐条指令，而是从整条流里横切出来的汇总视图：这本账出现过哪些账户、每个账户第一次和最后一次被用到是哪天、哪些账户有 Open/Close 指令、有哪些标签链接收款人、声明过哪些 Commodity、账本跨了哪几年。getters.py 把这些一次性遍历写成十几个彼此独立的顶层函数：多数以 entries 为输入，另有 get_leveln_parent_accounts、get_dict_accounts 接收账户名集合，get_values_meta 接收名字到指令的映射（:228-263,356-382）。共同点是不改输入、不留状态；在标准类型契约内不返回 Beancount 错误列表，但不合契约的输入会直接抛出 Python 异常——get_active_years 对非连续重复的年份 assert，未知指令类型走到分发处触发 AttributeError（:52,70），get_min_max_dates 传入生成器而非序列时 reversed() 触发 TypeError（:289）。

模块 docstring 把自己定位成 "Getter functions that operate on lists of entries to return various lists of things that they reference"（getters.py:1-3）。

2. 结构一览

3. 账户提取：GetAccounts

3.1 按类名 getattr 分发

for entry in entries:
    method = getattr(self, entry.__class__.__name__)
    for account_ in method(entry):

getters.py:51-53。分发不是 isinstance 链，也不是显式字典，而是用指令类的 __name__ 去类实例上取同名属性。可取的属性由类体末尾两行赋值造出：

# Associate all the possible directives with their respective handlers.
Open = Close = Balance = Note = Document = _one
Commodity = Event = Query = Price = Custom = _zero

getters.py:114-116。加上单独定义的 Transaction（:73-82）和 Pad（:84-92），十种经别名绑到 _one/_zero，加 Transaction、Pad 共四个实现，恰好覆盖 data.ALL_DIRECTIVES 里的 12 个类型（data.py:452-465）。四个实现的语义是：Transaction 逐条 posting 产出账户；Pad 返回 (entry.account, entry.source_account) 两个账户；_one 返回单元素元组 (entry.account,)；_zero 返回空元组。四者返回值都是可迭代对象，调用方一律 for ... in method(entry)，不区分生成器与元组。

方法的第一个参数名写作 _ 而不是 self（:73,84,94,104），表示不依赖实例状态；实例 _GetAccounts 建成模块级单例（:119-120），三个顶层包装函数转发到它（:123-158）。

这套写法带一条作者注释：

Note: This should get replaced by a method on each directive eventually,
that would be the clean way to do this.

getters.py:62-63（get_entry_accounts 方法的 docstring），同一段话在顶层包装 get_entry_accounts 的 docstring 里重复了一遍（:150-151）。作者把"账户提取表"集中在一个外部类里标记为临时方案，认为归位的做法是让每个指令类自己提供方法。这条注释自 2014-06-21 commit ba76130a 引入 get_entry_accounts 时就写在那里，至今未变。

分发靠属性名字符串，代价是没有类型检查兜底：传入 ALL_DIRECTIVES 之外的对象（例如 data.TxnPosting）时 getattr 抛 AttributeError，而不是被忽略或报错误对象。getters_test.py:47-50 (test_methods_coverage) 用 hasattr(dispatcher, klass.__name__) 遍历 data.ALL_DIRECTIVES 锁定"每种指令都有对应方法"，是新增指令类型时的唯一防线。

3.2 三个账户提取入口

get_accounts_use_map 是基础实现，边遍历边填两张 dict：

for entry in entries:
    method = getattr(self, entry.__class__.__name__)
    for account_ in method(entry):
        if account_ not in accounts_first:
            accounts_first[account_] = entry.date
        accounts_last[account_] = entry.date

getters.py:51-56。accounts_first 只在键不存在时写入，accounts_last 每次覆盖——"第一次"和"最后一次"都由遍历顺序决定，函数本身不比较日期。docstring（:41-48）没有声明输入需已排序；正确性完全依赖调用方传入的是加载器排好序的流。

get_accounts 从 accounts_last 取键成集合（:143-144），docstring 注明两张表的键相同（:129-130）。get_entry_accounts 走 set(method(entry))（:70-71），每次返回新集合，调用方可以直接改；interpolate.py:337-339 就是拿到后 update(additional_accounts)。

Open 和 Close 都走 _one，所以一个只被 open 声明、从未记过账的账户仍会出现在 get_accounts 的结果里，accounts_last 也会被 Close 指令的日期刷新。getters_test.py:52-74 锁定了这两点：五个账户的 accounts_first 全是 open 那天 2012-02-01，Assets:US:Cash 的 accounts_last 是 close 那天 2014-02-01，而没有 close 的 Expenses:Grocery 停在最后一次交易 2012-05-18。

3.3 get_account_open_close：重复指令只留最早的一条

open_close_map = defaultdict(lambda: [None, None])
for entry in entries:
    if not isinstance(entry, (Open, Close)):
        continue
    open_close = open_close_map[entry.account]
    index = 0 if isinstance(entry, Open) else 1
    previous_entry = open_close[index]
    if previous_entry is not None:
        if previous_entry.date <= entry.date:
            entry = previous_entry
    open_close[index] = entry

return dict(open_close_map)

getters.py:330-342。docstring 明说规则："If an open or close entry happens to be duplicated, accept the earliest entry (chronologically)"（:320-321）。写法是保留槽位里已有的那条，仅当新条目更早时才替换；日期相等时 <= 让先出现的那条胜出。重复的 Open/Close 本身由 ops/validation.py 报成错误，这里只保证下游拿到的映射是确定的一条。这段防御来自 2014-06-21 commit ba76130a，与之前的写法（直接 open_closes_map[entry.account][index] = entry，后者覆盖前者）相反。

值是长度 2 的可变 list 而非元组，构造期需要按下标改写。返回时套一层 dict()（:342）：2017-05-08 commit 4489fcb2 做的改动，CHANGES 记为 "Made the open/close map return by the getters not a defaultdict by default, so that accidentally looking up elements won't mutate it."（CHANGES:1360-1362）。同一个 commit 把 plugins/leafonly.py 改成 try/except KeyError（现为 leafonly.py:48-51），因为查一个不存在的账户不再静默插入 [None, None]。

未出现在任何 Open/Close 指令里的账户根本不进这张表，所以 account not in open_close_map 表示"从未声明过"，scripts/doctor.py:530-531 用这个条件生成缺失的 Open 指令。

3.4 对"输入已排序"的两处假设

get_min_max_dates 不做 min/max，直接取首尾：

for entry in entries:
    if types and not isinstance(entry, types):
        continue
    date_first = entry.date
    break

for entry in reversed(entries):
    ...

getters.py:283-293。两个循环各自 break，成本是 O(1)（带 types 过滤时是 O(k)），前提是 entries 已按日期升序。reversed() 还要求入参是序列，传生成器抛 TypeError。空列表或 types 过滤后无匹配时两个变量保持初值 None，返回 (None, None)（:281,295）。

get_active_years 把同样的假设写成断言：

seen = set()
prev_year = None
for entry in entries:
    year = entry.date.year
    if year != prev_year:
        prev_year = year
        assert year not in seen
        seen.add(year)
        yield year

getters.py:306-314。只在年份切换时产出，seen 集合的作用是让同一年份在被其他年份隔开后再次出现时立即 AssertionError——它不能验证输入整体是否按日期或年份升序：降序输入（如 2020、2019）不触发断言，正常产出 [2020, 2019]；只有 2020、2019、2020 这种非连续重复的年份才会被拦下。这三行是 2013-07-05 commit 3c568161 加进去的，比 get_min_max_dates 的首尾取法更早地把"已排序"这个前提显式化。函数是生成器，断言在消费时才触发；python -O 下断言被剥离，非连续重复的年份会被重复产出而不报错。

两处对排序的依赖能够成立，靠的是加载器的保障而非 getter 自身校验：标准加载路径在 booking 前对全部指令排序，并在每个插件执行完后重新排序，防止插件打乱顺序（loader.py:596-602,738-740）。

4. 其余提取函数

三个 get_all_* 都跳过非 Transaction 指令（:187-188,204-205,221-222），所以只挂在 Note/Document 上的 tags/links（data.py:309-310,423-424）不会被收进来。get_all_payees 与另外两个不同，先把 None 一起塞进集合再 discard，省掉循环里的判空；返回值带 # type: ignore[arg-type] 注释（:208），因为静态类型看不出 discard 之后集合里不再有 None。三者返回排序好的 list（docstring 仍写 set，见第 6 节）：get_all_tags、get_all_payees 从返回 set 改为排序 list 来自 2015-01-04 commit b2e4e387；get_all_links 由 2018-03-27 commit 4e5b638f 新增，实现之初就是 sorted(all_links)，不存在"从 set 改造"的历史。

4.1 get_dict_accounts：既是叶子又是前缀的账户

leveldict = OrderedDict()
for account_name in account_names:
    nested_dict = leveldict
    for component in account.split(account_name):
        nested_dict = nested_dict.setdefault(component, OrderedDict())
    nested_dict[get_dict_accounts.ACCOUNT_LABEL] = True
return leveldict

get_dict_accounts.ACCOUNT_LABEL = "__root__"

getters.py:257-266。每个账户名逐层 setdefault 下钻，走到底后在最内层字典里插一个 "__root__": True 标记。这个标记回答的问题是："这个节点本身是一个账户名，还是仅仅是别的账户名的中间层？"Expenses:Grocery 与 Expenses:Grocery:Bean 同时存在时，Grocery 节点的字典里既有 "__root__": True 又有子键 "Bean"——它既是叶子又是前缀。标记名不会与真实组件名冲突：账户组件的正则要求首字符是大写字母或数字（account.py:37-38），下划线开头的名字进不了合法账户名。

标记挂在函数对象上而不是模块级常量（:266），带 # type: ignore[attr-defined]；调用方通过 getters.get_dict_accounts.ACCOUNT_LABEL 取用，getters_test.py:142 就是这么写的。

用 OrderedDict 而不是普通 dict，意味着键的顺序参与相等比较，而顺序由输入的账户名顺序决定：__root__ 与子键谁先出现，取决于 Expenses:Grocery 和 Expenses:Grocery:Bean 哪个先被处理。getters_test.py:170 那行 ("Bean", root), # Wrong order here 标记的正是这一点（详见第 7 节）。

5. 设计决策与理由

6. 行为细节与边界

7. 测试锁定了什么

getters_test.py 一个类 TestGetters（:46），17 个 test_ 方法，大部分共用同一段 TEST_INPUT（:12-43）：5 条 open、2 条 commodity、3 笔交易、2 条 close。

test_get_dict_accounts（:132-188）的形态特殊。输入里 Expenses:Grocery 排在 Expenses:Grocery:Bean 前面，所以实际结果中 Grocery 节点是 {"__root__": True, "Bean": {...}}；测试把期望值写成相反的顺序并标注 # Wrong order here（:170），断言用的是 assertNotEqual（:182），演示的是"OrderedDict 的相等比较看顺序"。随后 :183-188 把 account_dict["Expenses"]["Grocery"] 改成正确顺序，但函数到此结束，没有再做 assertEqual——修正后的期望值没有被任何断言使用。这个形态从 2018-03-11 commit 6e97fe97 引入起就是如此：该 commit 把原先针对普通 dict 的 assertEqual 改成了 OrderedDict 版本的 assertNotEqual。

getters_test.py 未直接覆盖的行为：GetAccounts 对 Pad 指令的提取（TEST_INPUT 里没有 Pad）；get_min_max_dates 的 types 参数与空输入；get_active_years 的 assert 触发路径；get_leveln_parent_accounts 的 nrepeats > 0 与负数 level；get_values_meta 传入值为 None 的表以及不传 meta_keys；分发到不存在方法时的 AttributeError。test_methods_coverage（:47-50）只验证 GetAccounts 上存在同名属性，不验证指令是否分配到正确处理器。

全仓库层面：TestValidateActiveAccounts（validation_test.py:135-201）经 get_entry_accounts 断言含 Note、Pad、关闭后 Document 的错误；TestValidateDuplicateCommodities（:117-132）断言重复 Commodity 错误；但均未锁定 getters.py 内部语义——Pad 双账户返回、各指令到处理器映射、get_commodity_directives 的"后者覆盖前者"，全仓库无测试直接断言。

8. 演变史

主线 2017-04-30 移除 src/python/ 前缀（CHANGES:1364-1369），但历史分支提交仍可能显示旧路径：晚于该日期的 4e5b638f（2018-03-27）diff 仍是 src/python/beancount/core/getters.py，不可仅按日期推断路径。

9. 与其他模块的关系

• 上游：只依赖 data.py 的四个指令类和 account.split。Balance、Note、Document、Pad 等名字只在类型注解里用到，放在 TYPE_CHECKING 块（getters.py:20-32）；类型别名 AccountsUseMap 也定义在那里（:34）。
• 账户集合的消费者：ops/balance.py:83 用 get_accounts 预建 realization 节点；ops/documents.py:55 与 scripts/directories.py:65 用它对照文件系统目录；scripts/example.py:1665 生成示例账本时用它。
• 单条指令账户的消费者：ops/validation.py:226 检查指令引用的账户是否处于开启状态；core/interpolate.py:337 计算某条指令的余额上下文；parser/context.py:105 打印上下文；plugins/nounused.py:45 统计被引用过的账户。
• use_map 的消费者：plugins/auto_accounts.py:32-36 按首次使用日期补建 Open 指令；scripts/doctor.py:526-531 做同样的事并输出到文件。
• open/close 映射的消费者：ops/balance.py:90、ops/summarize.py:721-722、plugins/leafonly.py:47、plugins/check_average_cost.py:62、projects/export.py:85、scripts/doctor.py:527。
• Commodity 映射的消费者：projects/export.py:76 取 get_commodity_directives 的结果后，用该文件本地的 get_metamap_table（:60-71）与一个内联 lambda（:78）读取每个币种的元数据；get_values_meta 当前在仓库内没有非测试调用点，只被 getters_test.py 调用。
• 与 realization 的分工：get_dict_accounts 把账户名折成仅含名称与 __root__ 标记的轻量嵌套 OrderedDict（:248-263，标签 :266）；core/realization.py 独立建 RealAccount 树——realize() 调 postings_by_account()（:278-315）分组，再用 get_or_create() 建节点并挂 TxnPosting、非 Transaction 指令与 Inventory 余额（:45-66,211-267）——不依赖 get_dict_accounts（无非测试调用点，见第 6 节），二者对 Custom 账户值的识别规则也不一致。

10. 参考索引

beancount/core/getters.py：1-3 模块 docstring；10-18 导入；20-34 TYPE_CHECKING 与 AccountsUseMap；37-38 类定义；40-57 get_accounts_use_map 方法；51-56 遍历主体；59-71 get_entry_accounts 方法；62-63 作者注释；73-82 Transaction；84-92 Pad；94-102 _one；104-112 _zero；114-116 分发表；119-120 单例；123-132 顶层 get_accounts_use_map；135-144 get_accounts；147-158 顶层 get_entry_accounts；161-174 get_account_components；177-191 get_all_tags；194-208 get_all_payees；211-225 get_all_links；228-245 get_leveln_parent_accounts；248-263 get_dict_accounts；266 ACCOUNT_LABEL；269-295 get_min_max_dates；298-314 get_active_years；317-342 get_account_open_close；345-353 get_commodity_directives；356-382 get_values_meta。

beancount/core/getters_test.py：12-43 TEST_INPUT；46 测试类；47-50、52-74、76-88、90-97、99-102、104-107、109-112、114-130、132-188（170 "Wrong order here"、182 assertNotEqual）、190-194、196-199、201-214、216-229、231-244、246-252、254-258、260-266。

其它：beancount/core/data.py:452-465 ALL_DIRECTIVES、:504 Directives、:309-310,423-424 Note/Document 的 tags/links、:445-448 Custom.values；beancount/core/account.py:29 sep、:37-38 组件正则、:44-46 TYPE 哑对象、:98-106 split；beancount/api.py:60-61,148,153；beancount/core/interpolate.py:337-339；beancount/loader.py:596-602,738-740 排序保障；beancount/ops/validation.py:160-191 validate_duplicate_commodities、:226；beancount/ops/balance.py:83,90；beancount/ops/summarize.py:721-722；beancount/ops/documents.py:55；beancount/core/realization.py:45-66 RealAccount、:211-267 realize/树构建、:278-315,309-313 postings_by_account 对 Custom 的处理；beancount/plugins/auto_accounts.py:32-36；beancount/plugins/leafonly.py:47-51；beancount/plugins/nounused.py:45；beancount/plugins/check_average_cost.py:62；beancount/projects/export.py:60-71,74-80,85；beancount/parser/context.py:105；beancount/scripts/doctor.py:526-531；beancount/scripts/directories.py:65；beancount/scripts/example.py:1665；CHANGES:1360-1362,4086-4094,4096-4099。

commit：3c568161（2013-07-05）、ba76130a（2014-06-21）、ade7e62a（2014-08-31）、b2e4e387（2015-01-04）、96e6bb13（2015-01-17）、a3c06172（2015-11-28）、376a3ccc（2016-02-28）、4489fcb2（2017-05-08）、b66f8bee（2018-03-10）、6e97fe97（2018-03-11）、4e5b638f（2018-03-27）、bd6cad6f（2020-07-02）、22ab3984 与 25f43f2b（2020-10-29）、a9fd82def（2024-11-09）、955876a9（2024-12-16）、0f879811（2024-12-23，先）、8108c924（2024-12-23，后，0f879811 的子孙提交）。