beancount-helper 0.1.0__tar.gz

beancount_helper-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# test data
+*.xls
+*.xlsx
+
+# python things
+*.pyc
+*.pyo
+*.pyd
+__pycache__/
+
+.pytest_cache/
+.venv/

beancount_helper-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

beancount_helper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FishCat233
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

beancount_helper-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: beancount-helper
+Version: 0.1.0
+Summary: Convert bank statement Excel files to Beancount format with a rule-based account matching engine.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: xlrd>=2.0.2
+Description-Content-Type: text/markdown
+
+# beancount-helper
+
+Convert bank statement Excel files into [Beancount](https://beancount.github.io/) transactions with a rule-based account matching engine.
+
+```
+2025-01-15 * "Coffee Shop" "Latte"
+  Expenses:Food:Coffee  25.00 CNY
+  Assets:CCB
+```
+
+## Supported banks
+
+| Parser | Source |
+|--------|--------|
+| `ccb` | China Construction Bank (建设银行) statement `.xls` |
+| `wechat` | WeChat Pay (微信支付) statement `.xlsx` |
+
+## Installation
+
+```bash
+pip install beancount-helper
+```
+
+For development:
+
+```bash
+git clone https://github.com/your-org/beancount-helper.git
+cd beancount-helper
+uv sync
+```
+
+## Quick start
+
+**Step 1** — Export your statement from the bank app and save it locally.
+
+**Step 2** — (Optional) Create a rules file:
+
+```
+# rules.txt
+p=opposite:eq:Coffee Shop;;direct=out=>Expenses:Food:Coffee
+direct=in=>Income:Misc
+```
+
+**Step 3** — Run:
+
+```bash
+beancount-helper ccb.xls -p ccb -r rules.txt -o ledger.beancount
+```
+
+That's it. Every record falls into a Beancount account — either matched by your rules, or placed in `Equity:Opening-Balances` as a fallback.
+
+## CLI reference
+
+```
+beancount-helper INPUT -p PARSER [-r RULES] [-o OUTPUT] [--asset ASSET] [--default-account ACCOUNT]
+```
+
+| Argument | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `INPUT` | yes | — | Path to the bank statement file (`.xls` / `.xlsx`). |
+| `-p`, `--parser` | yes | — | `ccb` or `wechat`. |
+| `-r`, `--rules` | no | — | Path to a rules file. Without it, all records use the default account. |
+| `-o`, `--output` | no | `output.beancount` | Output file path. |
+| `--asset` | no | `Assets:CCB` / `Assets:WeChat` | Asset account for the source of funds. |
+| `--default-account` | no | `Equity:Opening-Balances` | Fallback account when no rule matches. |
+
+### Examples
+
+```bash
+# Bare minimum — everything goes to Equity:Opening-Balances
+beancount-helper ccb.xls -p ccb
+
+# With rules
+beancount-helper wechat.xlsx -p wechat -r rules.txt
+
+# Custom accounts
+beancount-helper ccb.xls -p ccb -r rules.txt \
+  --asset Assets:CCB:Savings \
+  --default-account Expenses:Pending
+```
+
+## Rule system
+
+Rules tell the tool which Beancount account a bill should be posted to. Each rule has this shape:
+
+```
+condition1;;condition2;;...=>TargetAccount
+```
+
+Conditions are AND-ed: a bill must satisfy **all** of them for the rule to fire. Rules are tried in order; the first match wins.
+
+### Condition reference
+
+#### Direction (`direct` / `direction`)
+
+Matches whether money flows in or out.
+
+```
+direct=in       # income
+direct=out      # expense
+```
+
+#### Property (`p` / `property`)
+
+Matches a field on the bill record.
+
+| Method | Syntax | Example |
+|--------|--------|---------|
+| exact | `p=field:eq:value` | `p=opposite:eq:Coffee Shop` |
+| contains | `p=field:in:substring` | `p=note:in:lunch` |
+| regex | `p=field:re:pattern` | `p=product:re:^ATMS$` |
+
+Available fields: `opposite`, `note`, `product` (wechat only).
+
+#### Amount comparisons
+
+| Operator | Meaning |
+|----------|---------|
+| `lt=N` | amount < N |
+| `le=N` | amount ≤ N |
+| `gt=N` | amount > N |
+| `ge=N` | amount ≥ N |
+| `eq=N` | amount = N |
+
+Negative amounts are expenses, positive are income (from the bank's perspective).
+
+### Combining conditions
+
+Separate conditions with `;;`:
+
+```
+# Small lunch expenses from a specific vendor
+direct=out;;p=opposite:in:Restaurant;;lt=50.0=>Expenses:Food:Lunch
+
+# Any income
+direct=in=>Income:Misc
+```
+
+### Rule file format
+
+One rule per line. Blank lines and `#`-comments are ignored.
+
+```
+# Food & drinks
+p=opposite:eq:Starbucks=>Expenses:Food:Coffee
+p=opposite:in:Pizza;;lt=80.0=>Expenses:Food:Takeout
+
+# Transport
+p=opposite:eq:DiDi=>Expenses:Transport:Ride
+p=note:re:metro|subway=>Expenses:Transport:Transit
+
+# Income
+direct=in;;gt=5000.0=>Income:Salary
+direct=in=>Income:Misc
+```
+
+## How it works
+
+```
+Bank Excel (.xls/.xlsx)
+        │
+        ▼
+  bill_resolver       ← parses bank-specific formats into Bill objects
+        │
+        ▼
+  transformer.rule    ← matches each Bill against the rule set
+        │
+        ▼
+  beancount.core      ← assembles BeanCount transactions, dumps to text
+        │
+        ▼
+  output.beancount
+```
+
+## Project structure
+
+```
+beancount-helper/
+├── main.py                    CLI entry point
+├── rules.example.txt          Sample rule set
+├── src/
+│   ├── beancount/core.py      BeanCount model + serialization
+│   ├── bill_resolver/
+│   │   ├── ccb.py             CCB Excel parser
+│   │   └── wechat.py          WeChat Excel parser
+│   └── transformer/rule.py    Rule matching engine
+└── test/
+    ├── test_beancount_core.py
+    └── rule_matcher.py
+```
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check .
+```
+
+## License
+
+MIT

beancount_helper-0.1.0/README.md

@@ -0,0 +1,207 @@
+# beancount-helper
+
+Convert bank statement Excel files into [Beancount](https://beancount.github.io/) transactions with a rule-based account matching engine.
+
+```
+2025-01-15 * "Coffee Shop" "Latte"
+  Expenses:Food:Coffee  25.00 CNY
+  Assets:CCB
+```
+
+## Supported banks
+
+| Parser | Source |
+|--------|--------|
+| `ccb` | China Construction Bank (建设银行) statement `.xls` |
+| `wechat` | WeChat Pay (微信支付) statement `.xlsx` |
+
+## Installation
+
+```bash
+pip install beancount-helper
+```
+
+For development:
+
+```bash
+git clone https://github.com/your-org/beancount-helper.git
+cd beancount-helper
+uv sync
+```
+
+## Quick start
+
+**Step 1** — Export your statement from the bank app and save it locally.
+
+**Step 2** — (Optional) Create a rules file:
+
+```
+# rules.txt
+p=opposite:eq:Coffee Shop;;direct=out=>Expenses:Food:Coffee
+direct=in=>Income:Misc
+```
+
+**Step 3** — Run:
+
+```bash
+beancount-helper ccb.xls -p ccb -r rules.txt -o ledger.beancount
+```
+
+That's it. Every record falls into a Beancount account — either matched by your rules, or placed in `Equity:Opening-Balances` as a fallback.
+
+## CLI reference
+
+```
+beancount-helper INPUT -p PARSER [-r RULES] [-o OUTPUT] [--asset ASSET] [--default-account ACCOUNT]
+```
+
+| Argument | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `INPUT` | yes | — | Path to the bank statement file (`.xls` / `.xlsx`). |
+| `-p`, `--parser` | yes | — | `ccb` or `wechat`. |
+| `-r`, `--rules` | no | — | Path to a rules file. Without it, all records use the default account. |
+| `-o`, `--output` | no | `output.beancount` | Output file path. |
+| `--asset` | no | `Assets:CCB` / `Assets:WeChat` | Asset account for the source of funds. |
+| `--default-account` | no | `Equity:Opening-Balances` | Fallback account when no rule matches. |
+
+### Examples
+
+```bash
+# Bare minimum — everything goes to Equity:Opening-Balances
+beancount-helper ccb.xls -p ccb
+
+# With rules
+beancount-helper wechat.xlsx -p wechat -r rules.txt
+
+# Custom accounts
+beancount-helper ccb.xls -p ccb -r rules.txt \
+  --asset Assets:CCB:Savings \
+  --default-account Expenses:Pending
+```
+
+## Rule system
+
+Rules tell the tool which Beancount account a bill should be posted to. Each rule has this shape:
+
+```
+condition1;;condition2;;...=>TargetAccount
+```
+
+Conditions are AND-ed: a bill must satisfy **all** of them for the rule to fire. Rules are tried in order; the first match wins.
+
+### Condition reference
+
+#### Direction (`direct` / `direction`)
+
+Matches whether money flows in or out.
+
+```
+direct=in       # income
+direct=out      # expense
+```
+
+#### Property (`p` / `property`)
+
+Matches a field on the bill record.
+
+| Method | Syntax | Example |
+|--------|--------|---------|
+| exact | `p=field:eq:value` | `p=opposite:eq:Coffee Shop` |
+| contains | `p=field:in:substring` | `p=note:in:lunch` |
+| regex | `p=field:re:pattern` | `p=product:re:^ATMS$` |
+
+Available fields: `opposite`, `note`, `product` (wechat only).
+
+#### Amount comparisons
+
+| Operator | Meaning |
+|----------|---------|
+| `lt=N` | amount < N |
+| `le=N` | amount ≤ N |
+| `gt=N` | amount > N |
+| `ge=N` | amount ≥ N |
+| `eq=N` | amount = N |
+
+Negative amounts are expenses, positive are income (from the bank's perspective).
+
+### Combining conditions
+
+Separate conditions with `;;`:
+
+```
+# Small lunch expenses from a specific vendor
+direct=out;;p=opposite:in:Restaurant;;lt=50.0=>Expenses:Food:Lunch
+
+# Any income
+direct=in=>Income:Misc
+```
+
+### Rule file format
+
+One rule per line. Blank lines and `#`-comments are ignored.
+
+```
+# Food & drinks
+p=opposite:eq:Starbucks=>Expenses:Food:Coffee
+p=opposite:in:Pizza;;lt=80.0=>Expenses:Food:Takeout
+
+# Transport
+p=opposite:eq:DiDi=>Expenses:Transport:Ride
+p=note:re:metro|subway=>Expenses:Transport:Transit
+
+# Income
+direct=in;;gt=5000.0=>Income:Salary
+direct=in=>Income:Misc
+```
+
+## How it works
+
+```
+Bank Excel (.xls/.xlsx)
+        │
+        ▼
+  bill_resolver       ← parses bank-specific formats into Bill objects
+        │
+        ▼
+  transformer.rule    ← matches each Bill against the rule set
+        │
+        ▼
+  beancount.core      ← assembles BeanCount transactions, dumps to text
+        │
+        ▼
+  output.beancount
+```
+
+## Project structure
+
+```
+beancount-helper/
+├── main.py                    CLI entry point
+├── rules.example.txt          Sample rule set
+├── src/
+│   ├── beancount/core.py      BeanCount model + serialization
+│   ├── bill_resolver/
+│   │   ├── ccb.py             CCB Excel parser
+│   │   └── wechat.py          WeChat Excel parser
+│   └── transformer/rule.py    Rule matching engine
+└── test/
+    ├── test_beancount_core.py
+    └── rule_matcher.py
+```
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check .
+```
+
+## License
+
+MIT

beancount_helper-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "beancount-helper"
+version = "0.1.0"
+description = "Convert bank statement Excel files to Beancount format with a rule-based account matching engine."
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["openpyxl>=3.1.5", "pandas>=3.0.3", "xlrd>=2.0.2"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/beancount", "src/bill_resolver", "src/transformer", "src/beancount_helper"]
+
+[project.scripts]
+beancount-helper = "beancount_helper.cli:main"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[dependency-groups]
+dev = ["coverage>=7.15.2", "pytest>=9.1.1", "ruff>=0.15.22"]

beancount_helper-0.1.0/rules.example.txt

@@ -0,0 +1,19 @@
+# beancount-helper 规则集
+# 格式: 条件段1;;条件段2;;...=>目标账户
+# 条件类型:
+#   direct=in|out         收支方向
+#   p=字段:eq|in|re:值    属性匹配（精确/包含/正则）
+#   lt|le|gt|ge|eq=数值   金额比较
+#
+# 示例:
+#   p=opposite:eq:一车一人=>Expenses:Trip:共享车:一车一人
+#   p=opposite:in:餐饮;;lt=50.0=>Expenses:Life:餐饮
+#   direct=in=>Income:Salary
+
+p=opposite:eq:一车一人=>Expenses:Trip:共享车:一车一人
+p=opposite:eq:享坐车出行=>Expenses:Trip:共享车:摆渡车
+p=opposite:eq:灵川夜不将就餐饮店（个体工商户）=>Expenses:Life:餐饮
+p=opposite:eq:灵川县这些年小炒店=>Expenses:Life:餐饮
+p=opposite:eq:灵川县张兰食苑餐馆=>Expenses:Life:餐饮
+p=opposite:eq:家乐轩餐厅丨灵川县=>Expenses:Life:餐饮
+p=opposite:in:甘晋宇;;lt=20.0;;direct=in=>Expenses:Life:餐饮

beancount_helper-0.1.0/src/beancount/core.py

@@ -0,0 +1,88 @@
+import re
+from datetime import datetime
+
+_HEADER_PATTERN = re.compile(r'^(\d{4}-\d{2}-\d{2}) \* "(.*?)" "(.*?)"$')
+
+
+def resolve_beancounts(string: str) -> list["BeanCount"]:
+    # 去除空行
+    string = "\n".join([line.rstrip() for line in string.split("\n")])
+
+    blocks = [b.strip() for b in string.strip().split("\n\n") if b.strip()]
+    results: list["BeanCount"] = []
+
+    for block in blocks:
+        results.append(resolve_beancount(block))
+
+    return results
+
+
+def resolve_beancount(string: str) -> "BeanCount":
+    lines = [line.strip() for line in string.split("\n") if line.strip()]
+    if len(lines) < 3:
+        raise ValueError(
+            f"Beancount transaction block must be 3 lines for resolving, but {len(lines)} lines got from: {string}"
+        )
+
+    # resolve header
+    match = _HEADER_PATTERN.match(lines[0])
+    if not match:
+        raise ValueError(f"Can't resolve beancount block: {string}")
+
+    date, receiver, digest = match.groups()
+    date = datetime.strptime(date, "%Y-%m-%d")
+
+    # resolve information
+    in_account, amount, currency_type = lines[1].split(" ")
+    out_account = lines[2]
+
+    return BeanCount(
+        datetime=date,
+        receiver=receiver,
+        digest=digest,
+        in_account=in_account,
+        out_account=out_account,
+        amount=float(amount),
+        currency_type=currency_type,
+    )
+
+
+def dump_beancount(beancount: "BeanCount") -> str:
+    return beancount.to_str()
+
+
+def dump_beancounts(beancounts: list["BeanCount"]) -> str:
+    return "\n\n".join([b.to_str() for b in beancounts])
+
+
+class BeanCount:
+    def __init__(
+        self,
+        datetime: datetime,
+        receiver: str,
+        digest: str,
+        in_account: str,
+        out_account: str,
+        amount: float,
+        currency_type: str,
+    ):
+        self.datetime = datetime
+        self.receiver = receiver
+        self.digest = digest
+        self.in_account = in_account
+        self.out_account = out_account
+        self.amount = amount
+        self.currency_type = currency_type
+
+    def __str__(self) -> str:
+        date_str = self.datetime.strftime("%Y-%m-%d")
+        return (
+            f'{date_str} * "{self.receiver}" "{self.digest}"\n'
+            f"  {self.in_account} {self.amount} {self.currency_type}\n"
+            f"  {self.out_account}"
+        )
+
+    def __repr__(self) -> str:
+        return f'BeanCount(date={self.datetime.strftime("%Y-%m-%d")}, {self.in_account}->{self.out_account}({self.amount}), receiver: {self.receiver}({self.digest}))'
+
+    to_str = __str__