beangulp-yapeal 0.1.0__tar.gz

beangulp_yapeal-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+site/
+.env
+.DS_Store
+.claude/settings.local.json

beangulp_yapeal-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: beangulp-yapeal
+Version: 0.1.0
+Summary: beangulp importer for Yapeal CSV bank statements: drafts transactions with stable bank references for idempotent re-imports
+Keywords: bank-statement,beancount,beangulp,csv,importer,yapeal
+Requires-Python: >=3.10
+Requires-Dist: beancount>=3.0
+Requires-Dist: beangulp>=0.2
+Description-Content-Type: text/markdown
+
+# beangulp-yapeal
+
+beangulp importer for Yapeal CSV bank statements.

beangulp_yapeal-0.1.0/README.md

@@ -0,0 +1,3 @@
+# beangulp-yapeal
+
+beangulp importer for Yapeal CSV bank statements.

beangulp_yapeal-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "beangulp-yapeal"
+version = "0.1.0"
+description = "beangulp importer for Yapeal CSV bank statements: drafts transactions with stable bank references for idempotent re-imports"
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["beancount", "beangulp", "importer", "csv", "bank-statement", "yapeal"]
+dependencies = [
+    "beancount>=3.0",
+    "beangulp>=0.2",
+]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/beangulp_yapeal"]

beangulp_yapeal-0.1.0/src/beangulp_yapeal/__init__.py

@@ -0,0 +1,172 @@
+"""beangulp importer for Yapeal CSV bank statements.
+
+Parses Yapeal CSV exports into beancount transaction drafts following the
+``csvbase`` pattern (see :mod:`beangulp.importers.csvbase` and
+``beangulp/examples/importers/csvbank.py``):
+
+- Every draft carries the bank's transaction ID as metadata (``bank_ref:`` by
+  default). ``extract()`` skips references already present anywhere in the
+  existing ledger, so re-running an import is always safe.
+- ``payee_rules`` — an iterable of ``(regex, account, flag)`` — draft the
+  counter leg when the payee/narration matches; anything unmatched is emitted
+  with the review flag and the cash leg only, for a human (or agent) to
+  complete.
+
+The importer is entity-agnostic: account names and rules are constructor
+parameters.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from decimal import Decimal, InvalidOperation
+
+from beancount.core import data, flags
+from beancount.core.amount import Amount
+from beangulp import mimetypes
+from beangulp.importers import csvbase
+
+__all__ = ["Importer"]
+
+_IDENTIFY_HEADER = "Transaktions-ID,Belastung oder Gutschrift,Buchungs-Datum"
+
+
+class _YapealAmount(csvbase.Column):
+    """Amount from either Gutschrift (credit), Belastung (debit), or Betrag+indicator."""
+
+    def parse(self, gutschrift: str, belastung: str, betrag: str, indicator: str) -> Decimal:  # type: ignore[override]
+        if gutschrift:
+            return Decimal(gutschrift)
+        if belastung:
+            return -Decimal(belastung)
+        if betrag:
+            amount = Decimal(betrag)
+            if indicator == "DEBIT":
+                amount = -amount
+            return amount
+        raise ValueError("no amount in row")
+
+
+class Importer(csvbase.Importer):
+    """Yapeal CSV statement importer for one bank account."""
+
+    ref = csvbase.Column("Transaktions-ID")
+    date = csvbase.Date("Transaktions-Datum", "%d.%m.%Y")  # type: ignore[assignment]
+    payee = csvbase.Column("Gegenpartei")
+    narration = csvbase.Column("Transaktions-Info")
+    amount = _YapealAmount(
+        "Gutschrift (CHF)", "Belastung (CHF)", "Betrag", "Belastung oder Gutschrift"
+    )
+
+    def __init__(
+        self,
+        account: str,
+        *,
+        iban: str | None = None,
+        currency: str = "CHF",
+        meta_key: str = "bank_ref",
+        payee_rules: Sequence[tuple[str, str, str]] = (),
+        review_flag: str = flags.FLAG_WARNING,
+    ):
+        super().__init__(account, currency, flag=review_flag)
+        self._iban = re.sub(r"\s", "", iban).upper() if iban else None
+        self._meta_key = meta_key
+        self._rules = [
+            (re.compile(pattern, re.IGNORECASE), acct, flag) for pattern, acct, flag in payee_rules
+        ]
+
+    def identify(self, filepath: str) -> bool:
+        try:
+            mimetype, _ = mimetypes.guess_type(filepath)
+            if mimetype != "text/csv":
+                return False
+            with open(filepath, encoding="utf-8") as f:
+                head = f.read(65536)
+            if _IDENTIFY_HEADER not in head:
+                return False
+            if self._iban:
+                return self._iban in re.sub(r"\s", "", head).upper()
+            return True
+        except (OSError, UnicodeError):
+            return False
+
+    def account(self, filepath: str) -> str:
+        return self.importer_account
+
+    def filename(self, filepath: str) -> str:
+        return "statement.csv"
+
+    def metadata(self, filepath: str, lineno: int, row: object) -> dict[str, object]:
+        meta = data.new_metadata(filepath, lineno)
+        ref = getattr(row, "ref", None)
+        if ref:
+            meta[self._meta_key] = ref
+        return meta
+
+    def extract(self, filepath: str, existing: data.Entries) -> data.Entries:
+        seen = _existing_references(existing, self._meta_key)
+        offset = int(self.skiplines) + int(self.names) + 1
+
+        entries: data.Entries = []
+        for lineno, row in enumerate(self.read(filepath), offset):
+            if not row:
+                continue
+
+            ref = getattr(row, "ref", None)
+            if not ref or ref in seen:
+                continue
+
+            try:
+                amount_val = row.amount  # type: ignore[attr-defined]
+            except (ValueError, InvalidOperation):
+                continue
+
+            meta = self.metadata(filepath, lineno, row)
+            payee = row.payee  # type: ignore[attr-defined]
+            narration = row.narration  # type: ignore[attr-defined]
+            date_val = row.date  # type: ignore[attr-defined]
+            units = Amount(amount_val, self.currency)
+            postings = [data.Posting(self.importer_account, units, None, None, None, None)]
+
+            flag = self.flag
+            haystack = f"{payee or ''}\n{narration or ''}"
+            for pattern, counter, rule_flag in self._rules:
+                if pattern.search(haystack):
+                    postings.append(
+                        data.Posting(
+                            counter, Amount(-amount_val, self.currency), None, None, None, None
+                        )
+                    )
+                    flag = rule_flag
+                    break
+
+            entries.append(
+                data.Transaction(
+                    meta,
+                    date_val,
+                    flag,
+                    payee,
+                    narration,
+                    data.EMPTY_SET,
+                    data.EMPTY_SET,
+                    postings,
+                )
+            )
+
+        entries.sort(key=lambda e: e.date)
+        return entries
+
+
+def _existing_references(existing: data.Entries, meta_key: str) -> set[str]:
+    refs: set[str] = set()
+    for entry in existing or []:
+        meta = getattr(entry, "meta", None) or {}
+        value = meta.get(meta_key)
+        if isinstance(value, str):
+            refs.add(value)
+        for posting in getattr(entry, "postings", ()) or ():
+            value = (posting.meta or {}).get(meta_key)
+            if isinstance(value, str):
+                refs.add(value)
+    return refs

beangulp_yapeal-0.1.0/tests/fixture.csv

@@ -0,0 +1,4 @@
+Transaktions-ID,Belastung oder Gutschrift,Buchungs-Datum,Transaktions-Datum,Transaktions-Info,Betrag,Belastung (CHF),Gutschrift (CHF),Kontowährung,Saldo (CHF),Gegenpartei,IBAN Gegenpartei,Original Transaktionsbetrag,Transaktionswährung,Devisenkurs,Gebühr,Zahlungstyp,Letzte 4 der Kartennummer,Karteninhaber,Status der Spesen,Zahlungsreferenz,Eigene Notiz,Zahlungs-Notiz,Zahlung erfasst am,Zahlung genehmigt von,Zahlung genehmigt am,Kategorie,Karten Programm,usedTags,mentions,ultimateCreditorName,ultimateDebitorName
+e9839ff4-e419-432a-b553-801e13c7e8f1,DEBIT,05.01.2026,05.01.2026,Debit card payment,25.50,25.50,,CHF,-25.50,ACME Hosting Inc,CH9300762011623852957,25.50,CHF,,,,,,,,Subject Test,,,,general,,,,,,,
+f68eb96a-1776-4c4d-b099-12ef65be3b63,CREDIT,10.01.2026,10.01.2026,Invoice payment,1000.00,,1000.00,CHF,1000.00,Client AG,CH9300762011623852957,1000.00,CHF,,,,,,,,Subject Test,,,,general,,,,,,,
+a1b2c3d4-5678-90ab-cdef-1234567890ab,DEBIT,15.01.2026,15.01.2026,Monthly subscription,45.00,45.00,,CHF,-45.00,Swisscom,CH9300762011623852957,45.00,CHF,,,,,,,,Subject Test,,,,general,,,,,,,

beangulp_yapeal-0.1.0/tests/test_yapeal_importer.py

@@ -0,0 +1,180 @@
+"""Tests for the Yapeal CSV beangulp importer."""
+
+from datetime import date as Date
+from decimal import Decimal
+from pathlib import Path
+
+from beancount.core import data
+
+from beangulp_yapeal import Importer
+
+FIXTURE = str(Path(__file__).parent / "fixture.csv")
+
+CASH = "Assets:Bank:Checking"
+RULES = ((r"client ag", "Assets:Receivable", "*"),)
+
+
+def _importer() -> Importer:
+    return Importer(CASH, payee_rules=RULES)
+
+
+def test_identify_accepts_yapeal_csv(tmp_path: Path) -> None:
+    assert _importer().identify(FIXTURE)
+    other = tmp_path / "not-a-statement.csv"
+    other.write_text("date,amount\n2026-01-01,1.00\n")
+    assert not _importer().identify(str(other))
+    other.write_text("Transaktions-ID,Betrag\n")
+    assert not _importer().identify(str(other))
+
+
+def test_identify_bails_on_binary(tmp_path: Path) -> None:
+    binary = tmp_path / "binary.dat"
+    binary.write_bytes(b"\x80\x81\x82")
+    assert not _importer().identify(str(binary))
+
+
+def test_identify_with_iban(tmp_path: Path) -> None:
+    importer = Importer(CASH, iban="CH9300762011623852957")
+    iban_csv = tmp_path / "with-iban.csv"
+    iban_csv.write_text(
+        "Transaktions-ID,Belastung oder Gutschrift,Buchungs-Datum,"
+        "Transaktions-Datum,Transaktions-Info,Betrag,Belastung (CHF),"
+        "Gutschrift (CHF),Kontowährung,Saldo (CHF),Gegenpartei,IBAN Gegenpartei,"
+        "Original Transaktionsbetrag,Transaktionswährung,Devisenkurs,Gebühr,"
+        "Zahlungstyp,Letzte 4 der Kartennummer,Karteninhaber,Status der Spesen,"
+        "Zahlungsreferenz,Eigene Notiz,Zahlungs-Notiz,Zahlung erfasst am,"
+        "Zahlung genehmigt von,Zahlung genehmigt am,Kategorie,Karten Programm,"
+        "usedTags,mentions,ultimateCreditorName,ultimateDebitorName\n"
+        "e9839ff4-e419-432a-b553-801e13c7e8f1,CREDIT,30.12.2025,"
+        "30.12.2025,John Kert,100.00,,100.00,CHF,100.00,John Kert,CH9300762011623852957,"
+        "100.00,CHF,,"
+        ",domestic_iban,,,,f68eb96a17764c4db09912ef65be3b63,,"
+        "Subject Test,,,,general,,"
+        ",,,\n"
+    )
+    assert importer.identify(str(iban_csv))
+
+    wrong_iban = Importer(CASH, iban="CH0000000000000000000")
+    assert not wrong_iban.identify(str(iban_csv))
+
+
+def test_identify_iban_matches_spaceless(tmp_path: Path) -> None:
+    importer = Importer(CASH, iban="CH9300762011623852957")
+    csv_file = tmp_path / "spaceless.csv"
+    csv_file.write_text(
+        "Transaktions-ID,Belastung oder Gutschrift,Buchungs-Datum,"
+        "Transaktions-Datum,Transaktions-Info,Betrag,Belastung (CHF),"
+        "Gutschrift (CHF),Kontowährung,Saldo (CHF),Gegenpartei,IBAN Gegenpartei,"
+        "Original Transaktionsbetrag,Transaktionswährung,Devisenkurs,Gebühr,"
+        "Zahlungstyp,Letzte 4 der Kartennummer,Karteninhaber,Status der Spesen,"
+        "Zahlungsreferenz,Eigene Notiz,Zahlungs-Notiz,Zahlung erfasst am,"
+        "Zahlung genehmigt von,Zahlung genehmigt am,Kategorie,Karten Programm,"
+        "usedTags,mentions,ultimateCreditorName,ultimateDebitorName\n"
+        "e9839ff4-e419-432a-b553-801e13c7e8f1,CREDIT,30.12.2025,"
+        "30.12.2025,John Kert,100.00,,100.00,CHF,100.00,John Kert,CH9300762011623852957,"
+        "100.00,CHF,,"
+        ",domestic_iban,,,,f68eb96a17764c4db09912ef65be3b63,,"
+        "Subject Test,,,,general,,"
+        ",,,\n"
+    )
+    assert importer.identify(str(csv_file))
+
+
+def test_identify_iban_ignored_when_none() -> None:
+    assert _importer().identify(FIXTURE)
+
+
+def test_account() -> None:
+    assert _importer().account("ignored") == CASH
+
+
+def test_filename() -> None:
+    assert _importer().filename("ignored") == "statement.csv"
+
+
+def test_extract_transactions() -> None:
+    entries = _importer().extract(FIXTURE, existing=[])
+    txns = [e for e in entries if isinstance(e, data.Transaction)]
+    assert len(txns) == 3
+
+    debit = txns[0]
+    assert debit.date == Date(2026, 1, 5)
+    assert debit.payee == "ACME Hosting Inc"
+    assert debit.narration == "Debit card payment"
+    assert debit.flag == "!"  # no rule matched
+    assert len(debit.postings) == 1
+    assert debit.postings[0].units is not None
+    assert debit.postings[0].units.number == Decimal("-25.50")
+    assert debit.meta["bank_ref"] == "e9839ff4-e419-432a-b553-801e13c7e8f1"
+
+    credit = txns[1]
+    assert credit.date == Date(2026, 1, 10)
+    assert credit.payee == "Client AG"
+    assert credit.flag == "*"  # rule matched
+    assert [p.account for p in credit.postings] == [CASH, "Assets:Receivable"]
+    assert credit.postings[1].units is not None
+    assert credit.postings[1].units.number == Decimal("-1000.00")
+
+    debit2 = txns[2]
+    assert debit2.date == Date(2026, 1, 15)
+    assert debit2.meta["bank_ref"] == "a1b2c3d4-5678-90ab-cdef-1234567890ab"
+
+
+def test_extract_dedup_by_reference() -> None:
+    meta = data.new_metadata("ledger.bean", 1)
+    meta["bank_ref"] = "e9839ff4-e419-432a-b553-801e13c7e8f1"
+    booked = data.Transaction(
+        meta,
+        Date(2026, 1, 5),
+        "*",
+        "ACME",
+        "already booked",
+        data.EMPTY_SET,
+        data.EMPTY_SET,
+        [],
+    )
+    entries = _importer().extract(FIXTURE, existing=[booked])
+    txns = [e for e in entries if isinstance(e, data.Transaction)]
+    assert [t.meta["bank_ref"] for t in txns] == [
+        "f68eb96a-1776-4c4d-b099-12ef65be3b63",
+        "a1b2c3d4-5678-90ab-cdef-1234567890ab",
+    ]
+
+
+def test_extract_empty_csv(tmp_path: Path) -> None:
+    empty = tmp_path / "empty.csv"
+    empty.write_text(
+        "Transaktions-ID,Belastung oder Gutschrift,Buchungs-Datum,"
+        "Transaktions-Datum,Gegenpartei,Transaktions-Info,"
+        "Gutschrift (CHF),Belastung (CHF),Betrag\n"
+    )
+    entries = _importer().extract(str(empty), existing=[])
+    assert not entries
+
+
+def test_betrag_fallback(tmp_path: Path) -> None:
+    csv = tmp_path / "betrag.csv"
+    csv.write_text(
+        "Transaktions-ID,Belastung oder Gutschrift,Buchungs-Datum,"
+        "Transaktions-Datum,Gegenpartei,Transaktions-Info,"
+        "Gutschrift (CHF),Belastung (CHF),Betrag\n"
+        "R1,DEBIT,01.02.2026,01.02.2026,Some Vendor,Payment,,,100.00\n"
+        "R2,CREDIT,02.02.2026,02.02.2026,Income,Salary,,,500.00\n"
+    )
+    entries = _importer().extract(str(csv), existing=[])
+    txns = [e for e in entries if isinstance(e, data.Transaction)]
+    assert len(txns) == 2
+    assert txns[0].postings[0].units is not None
+    assert txns[0].postings[0].units.number == Decimal("-100.00")
+    assert txns[1].postings[0].units is not None
+    assert txns[1].postings[0].units.number == Decimal("500.00")
+
+
+def test_payee_rules_draft_counter_leg() -> None:
+    importer = Importer(CASH, payee_rules=[(r"client", "Assets:Receivable", "*")])
+    entries = importer.extract(FIXTURE, existing=[])
+    txns = [e for e in entries if isinstance(e, data.Transaction)]
+    matched = [t for t in txns if len(t.postings) == 2]
+    assert len(matched) == 1
+    assert matched[0].payee == "Client AG"
+    assert matched[0].postings[1].account == "Assets:Receivable"