Beancount 插件体系详解：从 `__plugins__` 注册到自动化账务处理

Beancount 插件体系详解从__plugins__注册到自动化账务处理【免费下载链接】beancountBeancount: Double-Entry Accounting from Text Files.项目地址: https://gitcode.com/GitHub_Trending/be/beancountBeancount 是复式记账领域著名的纯文本记账工具其插件系统允许用户通过编写 Python 模块在账本解析流水线中过滤交易、强制约束、校验数据或自动化记账任务。本文以仓库 beancount/plugins/docs.md 为骨架结合源码深入解析插件的注册机制、标准签名、三大分类自动化生成、校验约束、元插件以及完整的编写与配置方法帮助你掌握如何在账本中启用、配置乃至自行实现 Beancount 插件。一、插件系统是什么Beancount 的插件是一组可选的 Python 模块它们在账本加载流水线中充当变换器transformer输入是已解析出的指令directive列表输出是修改后的指令列表以及新产生的错误列表。官方文档将其定位为三类示例Examples示范如何为 Beancount 编写插件实验Experiments测试新想法或新约束例如pedantic系列的严格校验实用工具Utilities提供核心之外的有用功能例如auto_accounts自动补全开户指令。在加载流程上插件由 beancount/loader.py 中的加载器负责调度加载器通过importlib.import_module动态导入插件模块逐一执行模块__plugins__中注册的回调函数并把每个回调返回的(entries, errors)合并进主流程最后统一用entry_sortkey重新排序确保插件对顺序不敏感。二、插件的识别与注册__plugins__一个模块要被 Beancount 识别为插件必须定义__plugins__变量——它是一个由函数名组成的元组登记该插件模块对外暴露的插件回调。例如 auto_accounts.py__plugins__ (auto_insert_open,)而在加载器端loader.py除了按字符串函数名查找外还支持直接把函数对象放进元组for function_name in module.__plugins__: if isinstance(function_name, str): callback getattr(module, function_name) # 按名称取函数 else: callback function_name # 直接使用函数对象三、标准插件函数签名每个插件回调遵循统一的标准签名见 docs.mddef plugin_function(entries, options_map): Args: entries: A list of directives (Transaction, Open, Close, etc.). options_map: A dictionary of parser options. Returns: A tuple (entries, errors), where: - entries: The modified list of directives. - errors: A list of new errors generated by the plugin. 三个要点entries已解析的指令列表类型包括Transaction、Open、Close、Balance、Price、Commodity等options_map解析选项字典可通过 beancount/parser/options.py 的get_account_types等工具提取账户类型等全局配置返回值必须返回(entries, errors)二元组。插件可以修改entries插入、删除、改写指令并通过errors返回错误对象通常是namedtuple含source、message、entry三个字段便于报错定位到原指令。此外部分插件回调支持第三个参数config_str插件配置字符串例如 check_average_cost.py 与 check_commodity.py 都接受它。加载器会按照 loader.py 的逻辑仅在提供了配置时追加该参数args () if plugin_config is None else (plugin_config,)。四、插件三大分类1. 自动化与生成类Automation Generation这类插件修改指令列表自动补充缺失信息或消除样板代码。auto_accounts自动插入Open指令auto_accounts.py 注册的回调auto_insert_open会自动为被使用但从未显式开户的账户在其首次出现的日期插入Open指令同时移除未被使用的开户指令。实现上先收集已有的opened_accounts再通过getters.get_accounts_use_map(entries)得到账户 → 首次使用日期映射为缺失账户用data.new_metadata(auto_accounts, index)生成元数据并构造data.Open指令最后用entry_sortkey重排。其用途正如源码注释所述适合演示场景或搭建初始账本时的过渡步骤。implicit_prices从交易合成Price指令implicit_prices.py 注册的回调add_implicit_prices会为两类 posting 合成Price指令posting 上显式写了价格即换算例如100 USD 1.10 CAD标记元数据__implicit_prices__ from_priceposting 带了成本cost但未匹配到已有持仓例如100 HOOL {564.20}标记__implicit_prices__ from_cost。实现上它会顺序遍历所有Transaction用inventory.Inventory维护各账户余额通过add_position判断是否命中既有持仓MatchResult.REDUCED则不重复生成价格。同时以(date, currency, amount.number, amount.currency)作为去重键同名同日不同价的多个价格会被保留源码注释说明这是为了兼容拆股等合法场景。其他辅助check_closing与check_drained的指令生成check_closing.py检测 posting 元数据closing: TRUE将其从 posting 元数据中删除并在交易日次日自动插入一条零余额检查指令Balance用于确认平仓交易后仓位归零2018-02-17 balance Assets:US:Brokerage:Main:Options 0 QQQ180216C160check_drained.py对所有带Close指令的资产负债表类账户Assets/Liabilities/Equity在关闭日次日为账户中出现过的每种货币自动插入0 数量的Balance检查确保关闭账户已清零若已存在同日期同货币的显式Balance则跳过且新指令复用Close指令的元数据以便报错定位。2. 校验与约束类Validation Constraints这类插件对账本数据强制执行特定规则不满足即产出错误。check_average_costNONE 记账法下的均价成本校验check_average_cost.py 注册的validate_average_cost面向使用NONE记账法的账户手动确保减少腿reducing leg的成本基数与账户库存均价一致——这是实现AVERAGE记账法的第一步近似。默认容差DEFAULT_TOLERANCE 0.01即允许均价上下 1% 浮动也可通过插件配置传入浮点数覆盖。它对负数量卖出且带 cost 的 posting比较posting.cost.number与库存均价balance.average().get_only_position().cost.number超出容差即报MatchBasisError。sellgains核对卖出收益与价格sellgains.py 注册的validate_sell_gains用于以给定价格卖出时校验收益/对价与行情价是否一致。当一笔交易中所有带成本lot的 posting 都显式给了价格时例如-81 ADSK {26.3125 USD} 26.4375 USD插件用价格乘数量累加出期望的卖出总额再与所有非Income账户Assets/Liabilities/Equity/Expenses上的对价 legs 求和比对误差超过容差即报SellGainsError。其收益在于即使你省略Income腿Beancount 会用平衡自动补全价格也提供了一层额外防打错字的校验。容差使用interpolate.infer_tolerances推导的容忍度再乘以EXTRA_TOLERANCE_MULTIPLIER 2。leafonly只允许叶子账户有流水leafonly.py 注册的validate_leaf_only借助realization.realize构建账户实现树对存在交易流水的非叶子账户有子账户的账户报LeafOnlyError。若某账户只有Open/Balance指令而无交易 posting则放行。nounused禁止开了不用的账户nounused.py 注册的validate_unused_accounts收集所有Open指令并比对被引用的账户集合从未被任何指令引用的账户报UnusedAccountError。值得注意的例外账户被打开后又被Close视为已使用。若确有开户但暂不使用的需求可用Balance余额断言、pad指令甚至一条note来消除告警。其他一致性检查check_commodity.py校验所有出现过的货币/商品都有对应的Commodity指令可配置忽略映射跳过某些账户×货币组合例如期权合约这种带有敲定价与到期日的动态符号SPX_121622P3300逐一声明不现实。check_drained.py见上文指令生成兼具校验关闭账户是否清零的作用。coherent_cost.py校验同一货币要么始终按成本cost记账、要么始终按市价记账禁止混用防止卖出仓位却漏写成本基数这类错误。目录下还有 noduplicates.py、onecommodity.py、unique_prices.py、currency_accounts.py、commodity_attr.py、close_tree.py 等更多约束类插件可逐一查阅 beancount/plugins/ 目录。3. 元插件Meta-Plugins元插件聚合其他插件便于一次性启用整套规则。pedantic严格记账风格全家桶pedantic.py 的源码只有短短十余行却通过loader.combine_plugins(...)一次性激活了check_commodity、coherent_cost、leafonly、noduplicates、nounused、onecommodity、sellgains、unique_prices、check_drained共 9 个校验插件强制一种严谨的记账风格。auto自动宽松模式与之相反auto.py 是pedantic的反面——它通过loader.combine_plugins(auto_accounts, implicit_prices)聚合自动开户与自动合成价格两个插件适合快速、粗略地搭建账本文档建议可以把它写进宏里复用。combine_plugins的实现见 loader.py它遍历各模块把每个模块__plugins__中注册的函数收集成一个新列表供聚合模块直接赋值给自己的__plugins__。五、在账本中启用插件插件在 Beancount 输入文件中通过plugin指令启用见 docs.md 的 Usage 部分plugin beancount.plugins.auto_accounts plugin beancount.plugins.pedantic启用后加载器会按指令顺序导入对应模块并执行其全部注册回调。常用验证命令为bean-check 你的账本.beancount若插件报错缺失的Commodity、非叶子账户流水、未使用账户、卖出价格与收益不符等bean-check会以错误列表形式输出source出错位置与message错误描述。仓库 beancount/scripts/check.py 是bean-check的入口实现。六、插件配置plugin指令的第二个参数部分插件支持通过plugin指令的第二个字符串参数传入配置例如plugin beancount.plugins.check_average_cost 0.02 plugin beancount.plugins.check_commodity {Assets:.*: SPX.*|QQQ.*}check_average_cost接受一个浮点字符串作为容差默认0.01即 1%见 check_average_cost.pycheck_commodity接受一个字典字符串键为账户正则、值为货币正则命中组合即忽略该校验见 check_commodity.py注意它用eval解析配置且要求结果必须是dict类型否则报ConfigError。加载器会将该配置字符串透传给回调的第三个参数config_strloader.py未提供时该参数为None。因此自定义插件时若要支持配置函数签名应写成def plugin(entries, options_map, config_strNone)。七、如何编写自己的插件综合上述机制编写一个插件只需四步建模块在beancount/plugins/下新建 Python 模块也可放在任意sys.path可达的位置定义回调实现plugin_function(entries, options_map, config_strNone)返回(entries, errors)注册在模块内定义__plugins__ (你的函数名,)启用在账本中写plugin 你的.模块路径。错误对象建议使用namedtuple(XxxError, source message entry)定义与仓库内所有插件的惯例保持一致便于bean-check统一渲染。修改entries后注意保持指令有序性——虽然加载器最终会强制entries.sort(keydata.entry_sortkey)loader.py但先排序仍是好习惯。仓库内每个插件都配有对应的_test.py测试文件例如 auto_accounts_test.py、check_average_cost_test.py、sellgains_test.py、pedantic_test.py这些测试用loader.load_docloader.py把 docstring 中的示例账本直接喂给插件断言结果是学习插件行为最直观的参考。八、小结Beancount 插件体系以__plugins__为注册契约、以(entries, errors)为统一数据流让过滤交易、强制约束、校验数据、自动化任务四类诉求都能以可插拔的 Python 模块实现。自动化侧有auto_accounts、implicit_prices、check_closing、check_drained替你补齐指令校验侧有check_average_cost、sellgains、leafonly、nounused、check_commodity、coherent_cost等守护账本一致性pedantic与auto两个元插件则分别代表严格全家桶与宽松自动档两种记账风格。理解这套机制后你既能熟练配置现成插件也能按同一契约扩展属于自己的账本自动化。【免费下载链接】beancountBeancount: Double-Entry Accounting from Text Files.项目地址: https://gitcode.com/GitHub_Trending/be/beancount创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考