将外部数据半自动导入beancount。
beancount-import的Python项目详细描述
beancount导入是一个半自动从 外部数据源进入beancount 记账系统,以及合并和调节 彼此之间以及现有交易。
示例目录。
数据源
通过实现 beancount_import.source模块。
数据源提供了一种导入和协调已下载数据的方法。 要自动检索财务数据,可以使用 财务软件包。你也可以用任何 其他机制,包括从财务部门手动下载数据 机构的网站,前提是其格式符合数据要求 来源:
当前支持的数据源集是:
- beancount_import.source.ofx:最通用的 数据源,支持支票、储蓄、信用卡、投资和 退休帐户。
- beancount_import.source.mint:支持所有 mint.com支持的现金账户类型
- beancount_import.source.venmo
- beancount_import.source.amazon:支持 常规和数字订单发票。
- beancount_import.source.healthEquity: 支持healthEquity.comhsa帐户,包括 现金和投资交易。
- beancount_import.source.google_purchases: 从google中导入的购买内容从gmail中试探性地提取出来 消息 < Le> = HeRF="BeaNoNtjION/Objest/PayPal.Py"Re="NoFoLoLy"> BeNeNoTuj.Ipp.Posial.PayPal < /A> 导入PayPal交易。
- beancount_import.source.waveapps: 从免费收据扫描wave导入收据 网站/移动应用程序。
- beancount_import.source.stockplanconnect: 进口放行/贸易交易 摩根士丹利股票计划连接
- beancount_import.source.ultipro_google: 导入谷歌员工Ultipro工资表。
有关配置的详细信息,请参阅各个数据源文档。
用法
要运行beancount导入,请创建一个python脚本,该脚本调用
beancount_import.webserver.main
函数。参考示例
刷新和
手动输入
错误
来自beancount本身或其中一个数据源的任何错误都显示在
错误
选项卡。通常明智的做法是手动重新解决任何错误
在继续之前,使用内置编辑器或外部编辑器
错误可能导致不正确的行为。然而,平衡误差通常是
可以忽略。
查看候选人
选择候选项
选项卡,查看当前待导入的条目
与现有和其他挂起事务的所有建议匹配。这个
原始的不匹配条目总是列在最后,并且建议
首先列出最匹配的帖子。带复选框的列表位于
顶部指示在每个
建议的匹配;当前挂起的事务始终列在第一位。如果许多
找到不正确的匹配项,可以取消选中复选框以筛选
火柴。< /P>
您可以单击其中一个建议条目,或使用 上/下箭头键。要按原样接受建议的条目,可以按enter或 双击它。这会立即修改日志以反映更改, 并在"日记账"选项卡中显示日记账的相关部分,因此 您可以轻松地进行手动编辑。
指定未知帐户
如果提议的分录包含未知帐户,则会用 独特的背景色并用组号标记。显示的帐户 是自动预测的,还是自动预测的 预测是不可能的(例如,由于缺乏训练数据)。有 纠正任何错误预测帐户的几种方法:
- 要更改个人帐户,可以按住shift键并单击它,键入新帐户
帐户名,然后按回车键。如果在键入
帐户名,帐户将保持不变。一种模糊匹配算法
用于自动完成:例如,如果键入"ex:co",它将匹配
有两个组件的子序列的任何帐户,其中
第一个以"ex"开头(不区分大小写),第二个以"co"开头,
例如
费用:饮料:咖啡
帐户。 - 更改共享同一组的拟议分录中的所有帐户 号码,您可以在不按住shift键的情况下单击其中一个帐户,或按 与组号相对应的数字键。一旦你输入一个帐户 然后按回车键,指定的帐户将被替换为所有过帐 在小组中。
- 要更改建议分录中的所有帐户,可以单击
更改帐户
按钮或按A
键。输入帐户并按 输入,指定的帐户将替换中的所有未知帐户 当前条目。 - 如果要推迟指定正确的帐户,可以单击
稍后修复
按钮或按f
键。这将代替原来的 当前项中所有未知帐户的未知帐户名。如果你 然后接受这个条目,包括这些fixme帐户的事务将 被添加到日志中,下次启动beancount导入时 交易将被视为待处理项。
查看关联的源数据
数据源可能指示附加的源数据与
特定候选项,通常基于元数据字段和/或
事务中包含的链接。例如,
beancount_import.source.amazon
数据源关联订单发票html
页面显示交易记录和beancount@import.source.google@purchases
数据源关联"采购详细信息"HTML页。其他可能的来源
数据类型包括PDF报表和收据图像。
您可以通过以下方式查看当前选定候选人的任何关联源数据
选择源数据
选项卡。
更改旁白、收款人、链接或标记
要修改条目的旁白,可以单击它,单击旁白
按钮,或按n
键。这实际上允许你修改收款人,链接,
还有标签。如果在
事务,文本框将以红色突出显示,焦点将保持到
您要么更正它,要么按escape,它将还原
交易回到原来的价值。
检查未清理的过帐
未清除的
选项卡显示有帐户的过帐列表
一个权威的消息来源,而且还没有被澄清。通常,发帖是
通过添加适当的源特定元数据字段将其标记为清除
将它与外部数据表示相关联,例如x_fitid的字段
对于ofx源。
此列表可能有助于查找需要手动更正的差异。 未清理过账的典型原因包括:
- 发布的源数据尚未下载。
- 该事务是日记帐中已存在的另一事务的副本, 需要手动合并/删除。
- 过帐时间早于源数据的最早日期 已导入,没有可用的早期数据。这样的帖子可以被忽略 在前面添加一个清除的元数据字段:<;date>;到 帐户或其祖先帐户之一。
- 源数据丢失或无法导入,但发布是
手动验证。添加
清除:true可忽略此类过帐 它们的元数据字段。
跳过并忽略导入的条目
如果出现不希望导入的挂起条目,则 有几个选项:
您可以跳过它,方法是在
挂起中选择不同的事务 选项卡,或通过单击标记为
或按
]
键。在当前会话中跳过它,但是 保留为挂起的条目,如果重新启动,将再次包含该条目 导入beancount。您可以稍后单击标有
fixme的按钮或按
f
键 重置所有未知帐户,然后接受候选人。这将添加 事务处理到日记账,但未知帐户保留为费用:固定费用
。这对于您不知道的事务很有用 如何分配帐户,或您希望与其他交易匹配的帐户 这将由尚未下载的数据生成。任何 日记账中包含费用:固定金额
账户的交易记录 在下一次启动时挂起的条目列表的末尾 导入beancount。
您可以单击标有
ignore
的按钮,或按i
键添加 选定的候选人到特殊的"忽略"日志文件。这对 错误的事务,如实际重复的事务。条目是 如果重新启动beancount导入,将不会再次显示"忽略"。 但是,如果从"忽略"日志文件中手动删除它们,则 将作为待处理条目返回。
与现有的beancount日志一起使用
如果开始对现有的beancount日志使用beancount导入 包含在提供的外部数据中也被引用的事务 对于一个数据源,数据源不知道要跳过那些事务, 因为它们将没有指示关联的必要元数据。 因此,它们都将作为新的待导入项呈现给您 交易。
然而,匹配机制很可能已经确定了正确的 匹配现有事务,该事务将作为默认选项显示。 接受这些匹配只会产生插入相关 元数据到J中因此,交易被视为"已清算"和 下次运行beancount import时将不再导入。应该是 即使对于大量的交易,也可以相对快速地完成此操作。
开发
要开发此包,请确保使用
pip install-e.
命令,而不是pip install.
命令。如果你
以前在没有-e
选项的情况下运行pip install
命令,您可以简单地
重新运行pip install-e.
命令。
测试
您可以使用pytest
命令运行测试。
许多测试都是"黄金"测试,通过创建文本
表示某一状态并将其与某一特定状态的内容进行比较
文件位于testdata/目录中。如果你改变其中一个测试
或者添加一个新的,您可以让测试通过
设置环境变量beancount_import_generate_golden_testdata=1
,
例如:
BEANCOUNT_IMPORT_GENERATE_GOLDEN_TESTDATA=1 pytest
确保至少将对相关的
testdata
使用此环境变量集运行测试之前的文件。
这样您就可以手动验证现有输出和
使用git diff的新输出
Web前端
web前端源代码位于frontend/目录中。参考 到那里的readme.md文件,了解如何在生成 变化:
基本工作流程
Mint.com数据源中的简单费用交易
假设用户于2016-08-09在星巴克购买了一杯咖啡, 信用卡,并已建立mint.com来检索此交易的数据 信用卡。
给定以下csv条目:
"Date","Description","Original Description","Amount","Transaction Type","Category","Account Name","Labels","Notes" "8/10/2016","Starbucks","STARBUCKS STORE 12345","2.45","debit","Coffee Shops","My Credit Card","",""
以及以下开户指令:
1900-01-01 open Liabilities:Credit-Card USD
mint_id: "My Credit Card"
Mint数据源将生成以下挂起的事务:
2016-08-10 * "STARBUCKS STORE 12345"
Liabilities:Credit-Card -2.45 USD
date: 2016-08-10
source_desc: "STARBUCKS STORE 12345"
Expenses:FIXME 2.45 USD
用户可以手动指定未知帐户为expenses:coffee
。
然后,Web界面将显示更新的变更集:
+2016-08-10 * "STARBUCKS STORE 12345"
+ Liabilities:Credit-Card -2.45 USD
+ date: 2016-08-10
+ source_desc: "STARBUCKS STORE 12345"
+ Expenses:Coffee 2.45 USD
如果expenses:coffee
帐户不存在,则beancount import将
另外,在变更集中包含open
指令:
+2016-08-10 * "STARBUCKS STORE 12345"
+ Liabilities:Credit-Card -2.45 USD
+ date: 2016-08-10
+ source_desc: "STARBUCKS STORE 12345"
+ Expenses:Coffee 2.45 USD
+ 2016-08-10 open Expenses:Coffee USD
用户接受此更改后,更改集将应用于日志。这个
存在的日期
和源代码
元数据字段向mint指示
清除负债:信用卡
过帐的数据源。这个
源代码帐户中的单词组合
负债:信用卡,以及
费用:咖啡的目标帐户
作为分类器的训练示例。与
一个包含星巴克的"源代码"字段很可能是
自动分类为
费用:咖啡
。注意,在这种情况下
叙述与source\u desc
字段匹配,叙述对
自动预测。用户不得删除或修改这些元数据字段,
但可能会添加其他元数据字段。
mint.com有自己的启发式方法来计算描述
和类别
金融机构提供的原始说明中的字段。
但是,mint数据源忽略了它们,因为它们不稳定(可以
如果数据被重新下载,则会发生更改),而且不太可靠。
与手动输入的事务匹配
考虑到前面示例中所示的相同事务,假设 用户在运行导入之前已手动输入事务:
pip install beancount-import0
当运行beancount import时,用户将看到two候选人:
pip install beancount-import1
用户应该选择第一个;选择第二个将产生
重复事务(但以后可能会被诊断为未清理
交易)。第二个候选人的费用:固定账户
一般实际上是一些其他的,可能不正确的,预测的帐户,但是
是可以更改的预测。
通常情况下,手动输入交易的日期(可能 交易实际发生的日期)与 银行提供的日期。为了处理这个差异,beancount import 允许在相隔5天的帖子之间进行匹配。日期 元数据字段允许过帐与相应的 CSV文件中的条目,即使整个交易日期不同。
请注意,即使此事务是手动输入的,但一旦匹配
对于挂起的事务和source\u desc
和date
元数据字段
它的功能与
上一个示例。
信用卡支付交易
假设用户使用银行账户支付信用卡余额,并且 mint.com的建立是为了从银行账户和 信用卡。
给定以下csv条目:
pip install beancount-import2
以及以下开户指令:
pip install beancount-import3
mint数据源将生成两个挂起的事务,对于第一个事务 将呈现两位候选人:
pip install beancount-import4
注意,第二个事务中的expenses:fixme
帐户实际上
无论哪个帐户是自动预测的。如果之前有过
类似的交易,它很可能被正确地预测为资产:检查
用户应该接受第一个同时导入两个事务的候选项。 在这种情况下,两个过帐都被视为已清除,新交易将 生成两个自动预测的训练示例,分别对应于 源代码、源帐户和目标帐户的两种组合。
但是,如果用户接受第二个候选(可能是因为
交易尚未过帐到支票帐户和挂起
从支票账户数据派生的交易尚不可用),以及
将帐户保留为expenses:fixme
,手动指定
资产:检查,或依赖于自动预测来选择
资产:检查,然后在从检查导入事务时
帐户,用户将看到以下候选人
另一个接受比赛的机会:
pip install beancount-import5
许可证
版权所有(c)2014-2018 Jeremy Maitin Shepard.
在GNU通用公共许可下发布,仅限2.0版。 有关详细信息,请参见许可证文件。