02 · number.py：Decimal、统一入口 D() 与 MISSING 哨兵

以下是本篇的技术版记录，对照源码查阅用。行号均以 commit 97472138 为准。

结构一览

D() 的类型契约

类型注解（:41）未列出 int/float，但 :64-65 接受它们（bool 作为 int 子类一并放行）。其它类型走 :66-67 的 assert strord is None，AssertionError 连同 InvalidOperation 被 :68-71 包成 ValueError——这个"只捕一种异常"的契约在 python -O 下失效（assert 被剥离，静默返回 None）。测试 number_test.py:33-41 (test_D) 覆盖 Decimal 透传、逗号、"- 122.34"（负号后带空格，靠删空格正则通过）、空串、None，没有 float 用例，也没有非法字符串用例。

账本文件里的金额/价格/成本不经过 D()（option 指令里的数字仍走 D()）：beancount/parser/lexer.l:282 的 NUMBER 正则先决定哪些字符串能成为数字 token，beancount/parser/tokens.c:55-67 (pydecimal_from_cstring) 再用 validate_decimal_number（:9-53）校验千分位分组，最后经 beancount/parser/decimal.h:26 (PyDec_FromCString) 调用 Decimal(str)。正负号是独立 token（lexer.l:220-221），由 grammar.y:338-346 (number_expr) 作一元运算处理，所以账本里 - 122.34 合法而 1e3 不合法。

D() 与账本词法层的完整对照

tokens.c 不是一个可以照抄的校验器：:28-31 只有 isdigit 才把字符拷进输出缓冲，没有 else 分支，未知字符被静默跳过——单独拿它校验 "1e3" 会得到 "13"、"-1.5" 会得到 "1.5"。它能工作是因为 lexer 正则已经在前面把关。

常量的实际消费者

ZERO 在非测试代码里有几十处引用（判零、初始化累加器）；ONE 有两类消费者——ONE.scaleb(expo) * multiplier 生成容差（beancount/core/interpolate.py:188、beancount/ops/balance.py:41），以及取汇率倒数 ONE / rate（beancount/core/prices.py:112,131,240，:333,372 用 ONE 作同币种汇率）；TEN**exponent 只用于 auto_quantize（number.py:144）；HALF 在非测试代码里零调用。

MISSING 的产生点与判定点

MISSING 是类对象，isinstance(MISSING, type) 为 True，因此能通过 beancount/core/amount.py:49 的 valid_types_number = (Decimal, type, type(None))。产生点在 C 语法层：beancount/parser/grammar.y:446-450（INDENT optflag account eol，无金额 posting 的 units 直接传 MISSING_OBJ）、:636-642 (maybe_number) 与 :644-650 (maybe_currency) 的 %empty 分支；Python 侧 beancount/parser/grammar.py:518-519 在 cost_comp_list 为空时直接返回 CostSpec(MISSING, None, MISSING, None, None, False)，这是裸 {} 的路径；:583-587 处理的是 cost_comp_list 非空但没有 CompoundAmount 的成本说明（只写了日期或标签），同样填入 MISSING 数字与币种。

auto_quantize 一族

给由 float 转来、带垃圾尾数的 Decimal（如 20.899999618530273）反推小数位并量化：number.py:98-120 (auto_quantized_exponent)、:123-148 (auto_quantize)、:162-184 (infer_quantum_from_list)。非测试代码零调用，只有 number_test.py:68-156 在用；docstring :174-175 说接受 float，实际传裸 float 在 :107 的 number.normalize() 处抛 AttributeError。

num_fractional_digits（:151-159）返回 -number.as_tuple().exponent；display_context.py 没有调用它，而是内联同一算式（display_context.py:204-205）。

设计决策与理由

坑与边界

Decimal 语义实测

验证环境 Python 3.14.6，默认 getcontext().prec == 28。

(a) 构造精度只由输入决定，context.prec 只影响运算。

>>> with localcontext() as c:
...     c.prec = 2
...     print(Decimal("0.1122334455"), Decimal("0.1122334455") + 0)
...
0.1122334455 0.11

beancount 测试 number_test.py:16-26 (test_formatting) 引用了官方文档同一句话。

(b) 0.10 == 0.1 为 True，但 exponent 不同；normalize() 会丢掉它。

>>> Decimal("0.10") == Decimal("0.1"), Decimal("0.10").as_tuple().exponent, Decimal("0.1").as_tuple().exponent
(True, -2, -1)
>>> Decimal("100.00").normalize()
Decimal('1E+2')

exponent 的消费点：interpolate.py:185-188（交易容差 = ONE.scaleb(expo) * tolerance_multiplier，multiplier 默认 0.5，:130-131）、ops/balance.py:34-41（Balance 容差）、display_context.py:204-205（显示精度众数统计）。

(c) quantize 超出 prec 抛 InvalidOperation，不是截断。

>>> with localcontext() as c:
...     c.prec = 4
...     Decimal("12345.678").quantize(Decimal("0.01"))
...
decimal.InvalidOperation: [<class 'decimal.InvalidOperation'>]

beancount 唯一的防御是 display_context.py:321-331 的 localcontext；interpolate.py:383-391 只在注释里引用了这条规则，其 guard 防不住。

(d) 默认舍入 ROUND_HALF_EVEN；beancount 从未改动；str.format 不接受 rounding 参数。

>>> getcontext().rounding, Decimal("2.345").quantize(Decimal("0.01")), Decimal("0.125").quantize(Decimal("0.01")), "{:.2f}".format(Decimal("2.345"))
('ROUND_HALF_EVEN', Decimal('2.34'), Decimal('0.12'), '2.34')
>>> Decimal("2.345").quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
Decimal('2.35')
>>> "{:.2f}".format(Decimal("2.345"), rounding=ROUND_HALF_UP)   # 关键字被静默忽略
'2.34'
>>> with localcontext(rounding=ROUND_HALF_UP): "{:.2f}".format(Decimal("2.345"))
'2.35'

(e) Decimal(float) 原样保留二进制展开，且 '{:.2f}' 会把它藏起来。

>>> Decimal(3.30)
Decimal('3.29999999999999982236431605997495353221893310546875')
>>> Decimal(3.30).as_tuple().exponent, Decimal(3.30) == Decimal("3.30"), "{:.2f}".format(Decimal(3.30))
(-50, False, '3.30')
>>> Decimal(str(3.30)), Decimal(True)
(Decimal('3.3'), Decimal('1'))

exponent 为 -50 意味着按 (b) 推断出的容差是 ONE.scaleb(-50) * 0.5 = 5E-51，等价于无容差。

(f) D("") 在 beancount 返回新对象，与 ZERO 相等但不同一。

>>> D("") == ZERO, D("") is ZERO
(True, False)

(g) Decimal 与 float 可以比较（按精确值），但不能做算术。

>>> Decimal("0.1") < 0.1, Decimal("0.5") == 0.5, Decimal("0.1") == 0.1
(True, True, False)
>>> Decimal("0.1") + 0.1
TypeError: unsupported operand type(s) for +: 'decimal.Decimal' and 'float'

beancount 依赖前者：number.py:111-114 (auto_quantized_exponent) 直接拿 float 阈值与 Decimal 比较。

(h) 除法吃满 prec，并受舍入模式影响。

>>> Decimal("10.00") / Decimal("3"), (Decimal("10.00") / Decimal("3")).as_tuple().exponent
(Decimal('3.333333333333333333333333333'), -27)

对应 grammar.py:918-919（@@ 总价折单价）、position.py:368。

(i) 负零：乘负数与舍入都会产生，加零可消除，== 看不出。

>>> Decimal("-1") * Decimal("0.00"), Decimal("-0.001").quantize(Decimal("0.01")), -Decimal("0.00")
(Decimal('-0.00'), Decimal('-0.00'), Decimal('0.00'))
>>> Decimal("-0.00") == 0, Decimal("-0.00").is_signed(), Decimal("-0.00").copy_abs(), Decimal("-0.00") + 0
(True, True, Decimal('0.00'), Decimal('0.00'))

(j) str() 在 adjusted exponent < -6 时切科学计数法，format(…, "f") 不会。

>>> str(Decimal("0.00000001")), format(Decimal("0.00000001"), "f"), str(Decimal("0E-8"))
('1E-8', '0.00000001', '0E-8')

(k) Python Decimal() 默认接受的写法，以及 \d 的全角陷阱。

>>> Decimal("1_000"), Decimal("１２３.４５"), Decimal(".5"), Decimal("5."), Decimal(" 5 ")
(Decimal('1000'), Decimal('123.45'), Decimal('0.5'), Decimal('5'), Decimal('5'))
>>> bool(re.match(r"\d", "１")), bool(re.match(r"[0-9]", "１"))
(True, False)

MISSING / None / ZERO 三态

parser.py:1-108 的 docstring 共 12 组 INPUT 例子，第 27-28 行明确 "MISSING should never appear in completed, loaded transaction postings"。两条不变量支撑这套三态：完成态不得残留 MISSING，以及判缺失只用 is MISSING、不用真值判断或 == None（因为 None 在同一个字段上有另一个含义，MISSING 又不是假值）。

测试锁定了什么

number_test.py 160 行、3 个类共 11 个测试，其中 6 个属于 TestInferQuantization：

setUp（:69-72）用 random.uniform 造 100 个随机数，所以 test_infer_quantization_one/_normal 每次跑的输入都不同。

没有测试覆盖的行为：D(float)、D(True)、D(object())（含 python -O 下静默返回 None）、任何非法字符串、D(int)；常量只测了 ZERO；MISSING、NUMBER_RE、num_fractional_digits、auto_quantized_exponent 在本测试文件里完全没有出现。

演变史

模块 docstring 里"从 beancount.core.amount 导入 Decimal"这条建议是 D() 迁移前的遗留，092a099d 之后已无实际约束力。

与其他模块的关系

• 上游：无。只 import re 与 decimal（number.py:18-19）。
• D() 的非测试调用点：amount.py:151 (Amount.from_string)、position.py:342,363-364 (from_string)、data.py:557,589,591、interpolate.py:30、parser/options.py:70,89,538,553、plugins/check_average_cost.py:58-59、projects/export.py、scripts/example.py。集中在"工具代码 + option 值 + 测试用迷你解析器"，不在账本主路径上。
• 绕过 D() 直接构造 Decimal 的地方：账本数字走 C 层（lexer.l:282 → tokens.c:55-67 → decimal.h:26）；核心代码里还有裸调 display_context.py:319、inventory.py:381（后者写的是 Decimal("Infinity")）。
• MISSING 的流转链：产生于 grammar.y:446-450,636-650 与 grammar.py:519,587 → 经 amount.py:49,59 的宽松构造断言携带 → 在 booking.py:73-75,210-216、booking_full.py:348-366,509-521,730,830-852、convert.py:100-101 被 is MISSING 判定；实际回填发生在 booking_full.py:798-853 与 :1012-1020，币种缺口由 replace_currencies (booking_full.py:489-538) 处理 → 完成态不得残留（parser.py:25-28）。
• exponent（小数位）的消费者：interpolate.py:185-188 与 ops/balance.py:34-41 拿它算容差，display_context.py:204-205 拿它统计显示精度。beancount 从不对存储值做 normalize()，原因就在这里。

参考索引

commit：基线 97472138（2026-08-22）；4c1e87bb（2020-11-25，Fixed #584）；c9132bba（2025-12-21，改为 +12 并加 NOTE）。

beancount/core/number.py：1-11 模块 docstring；5-6 漂移句；8-9 Prefer D()；19 from decimal import Decimal；22-25 常量；28-32 MISSING；36 NUMBER_RE；38 _CLEAN_NUMBER_RE；41-71 D()；44 importer 用途；46 "never use floating-point"；58-65 各分支；66-67 assert 分支；68-71 ValueError 包装；74-83 round_to；86-95 same_sign；98-120 auto_quantized_exponent；107 normalize()；111-114 float 阈值与 Decimal 比较；123-148 auto_quantize；144 TEN**exponent；151-159 num_fractional_digits；162-184 infer_quantum_from_list；174-175 float 声明。

beancount/core/number_test.py：16-26 test_formatting；30-31 test_ZERO；33-41 test_D；43-52 test_round_to；54-65 test_same_sign；68-156 TestInferQuantization。

beancount/core/amount.py：16 import；40 Optional[Decimal]；49 valid_types_number；59 构造 assert；71-76 to_string；135-151 from_string。

beancount/core/interpolate.py：30 MAXIMUM_TOLERANCE；35 MAX_TOLERANCE_DIGITS；46-58 is_tolerance_user_specified；97 infer_tolerances；130-131 multiplier 默认 0.5；185-188 exponent → 容差；364-394 quantize_with_tolerance。

beancount/core/display_context.py：201-205 小数位统计；298-331 quantize；319 裸 Decimal(1)；321-331 localcontext；330 prec + 12；372、403、405、451 格式串。

beancount/parser/lexer.l：220-221 PLUS/MINUS；282 NUMBER 正则。tokens.c：9-53 validate_decimal_number；19-26 逗号规则；28-31 仅 isdigit 拷贝；55-67 pydecimal_from_cstring。decimal.h：26 PyDec_FromCString。grammar.y：338-346 number_expr；446-450 无金额 posting；636-642 maybe_number；644-650 maybe_currency。

beancount/parser/parser.py：1-108 docstring；3-8 'NA' 漂移；25-28 MISSING 不变量。grammar.py：177 _dcupdate；519、587 CostSpec(MISSING, …)；918-919 总价折单价除法。options.py：70、89、538、553。

其它：convert.py:100-101；prices.py:112,131,240,333,372；position.py:117-123,342-364,368；ops/balance.py:20-41；plugins/check_average_cost.py:35,58-59；inventory.py:186-198,381,402-437；scripts/example.py:836,842,1039,1584；data.py:557,589,591；projects/export.py:162。