splitkaro 0.1.0__py3-none-any.whl

splitkaro/ledger.py

@@ -0,0 +1,115 @@
+"""Who owes whom, and the fewest payments that settle everything."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+
+from splitkaro.models import Expense, Group, Transfer
+from splitkaro.money import ZERO, allocate
+
+
+@dataclass
+class ExpenseEffect:
+    """An expense converted to the group currency: what each member paid and owes."""
+
+    paid: dict[str, Decimal]
+    owed: dict[str, Decimal]
+
+
+def effect(group: Group, expense: Expense) -> ExpenseEffect:
+    total = group.to_group_currency(expense.amount, expense.currency)
+    payers = list(expense.paid_by)
+    # Converting each payer separately could drift by a paisa, so share the
+    # converted total among payers in proportion to what they paid instead.
+    paid_parts = allocate(total, [expense.paid_by[p] for p in payers])
+    return ExpenseEffect(
+        paid=dict(zip(payers, paid_parts)),
+        owed=expense.split.portions(total),
+    )
+
+
+def balances(group: Group) -> dict[str, Decimal]:
+    """Net position of every member in the group currency.
+
+    Positive: the group owes them money. Negative: they owe the group.
+    The balances always add up to exactly zero.
+    """
+    net = {m.name: ZERO for m in group.members}
+    for expense in group.expenses:
+        e = effect(group, expense)
+        for name, amount in e.paid.items():
+            net[name] += amount
+        for name, amount in e.owed.items():
+            net[name] -= amount
+    for t in group.transfers:
+        net[t.sender] += t.amount
+        net[t.receiver] -= t.amount
+    return net
+
+
+def settle(net: dict[str, Decimal]) -> list[Transfer]:
+    """Suggest payments that bring every balance to zero.
+
+    First, anyone who owes exactly what someone else is owed pays them
+    directly. The rest is settled greedily, always matching the largest
+    debtor with the largest creditor. This never needs more than n - 1
+    payments for n people with non-zero balances, and in everyday groups it
+    is usually the minimum. (Finding the true minimum is NP-hard.)
+    """
+    debtors = {name: -amount for name, amount in net.items() if amount < 0}
+    creditors = {name: amount for name, amount in net.items() if amount > 0}
+    plan: list[Transfer] = []
+
+    for debtor in sorted(debtors):
+        for creditor in sorted(creditors):
+            if creditors[creditor] == debtors[debtor] and creditors[creditor] > 0:
+                plan.append(Transfer(debtor, creditor, debtors[debtor]))
+                creditors[creditor] = debtors[debtor] = ZERO
+                break
+
+    while True:
+        debtor = _largest(debtors)
+        creditor = _largest(creditors)
+        if debtor is None or creditor is None:
+            break
+        amount = min(debtors[debtor], creditors[creditor])
+        plan.append(Transfer(debtor, creditor, amount))
+        debtors[debtor] -= amount
+        creditors[creditor] -= amount
+
+    return plan
+
+
+def _largest(amounts: dict[str, Decimal]) -> str | None:
+    # Sort by amount, then name, so the result is the same on every run.
+    candidates = [(-amount, name) for name, amount in amounts.items() if amount > 0]
+    return min(candidates)[1] if candidates else None
+
+
+@dataclass
+class StatementLine:
+    date: str
+    description: str
+    change: Decimal  # effect on the member's balance
+
+
+def statement(group: Group, name: str) -> list[StatementLine]:
+    """Every expense and payment that changed one member's balance, in date order."""
+    name = group.resolve(name)
+    lines: list[StatementLine] = []
+    for expense in sorted(group.expenses, key=lambda x: (x.date, x.id)):
+        e = effect(group, expense)
+        change = e.paid.get(name, ZERO) - e.owed.get(name, ZERO)
+        if name in e.paid or name in e.owed:
+            lines.append(
+                StatementLine(expense.date.isoformat(), f"#{expense.id} {expense.description}", change)
+            )
+    for t in group.transfers:
+        when = t.date.isoformat() if t.date else ""
+        if t.sender == name:
+            lines.append(StatementLine(when, f"paid {t.receiver}", t.amount))
+        elif t.receiver == name:
+            lines.append(StatementLine(when, f"received from {t.sender}", -t.amount))
+    # Undated payments go last; the sort is stable, so same-day entries keep their order.
+    return sorted(lines, key=lambda line: line.date or "9999-12-31")

splitkaro/models.py

@@ -0,0 +1,205 @@
+"""The data that makes up a group's splitkaro: members, expenses and payments."""
+
+from __future__ import annotations
+
+import datetime as dt
+import enum
+from dataclasses import dataclass, field
+from decimal import Decimal
+
+from splitkaro.money import ZERO, MoneyError, allocate, to_money
+
+HUNDRED = Decimal(100)
+
+
+class SplitKaroError(ValueError):
+    """A request that would leave the group's records inconsistent."""
+
+
+class SplitKind(str, enum.Enum):
+    EQUAL = "equal"  # everyone in `among` pays the same
+    EXACT = "exact"  # values are amounts and must add up to the total
+    PERCENT = "percent"  # values are percentages and must add up to 100
+    SHARES = "shares"  # values are weights, e.g. 2 shares for a couple
+
+
+@dataclass
+class Split:
+    kind: SplitKind
+    # Members taking part, in order. For EQUAL only this is used; for the other
+    # kinds it is the keys of `values`.
+    among: list[str]
+    values: dict[str, Decimal] = field(default_factory=dict)
+
+    @classmethod
+    def equal(cls, among: list[str]) -> Split:
+        return cls(SplitKind.EQUAL, list(among))
+
+    @classmethod
+    def weighted(cls, kind: SplitKind, values: dict[str, Decimal]) -> Split:
+        return cls(kind, list(values), dict(values))
+
+    def portions(self, total: Decimal) -> dict[str, Decimal]:
+        """How much of ``total`` each member owes. Always adds up exactly."""
+        if not self.among:
+            raise SplitKaroError("an expense must be split among at least one member")
+        if len(set(self.among)) != len(self.among):
+            raise SplitKaroError("a member appears twice in the split")
+
+        if self.kind is SplitKind.EQUAL:
+            weights = [Decimal(1)] * len(self.among)
+        elif self.kind is SplitKind.EXACT:
+            amounts = {name: to_money(v) for name, v in self.values.items()}
+            if any(v < ZERO for v in amounts.values()):
+                raise SplitKaroError("exact amounts cannot be negative")
+            if sum(amounts.values()) != total:
+                raise SplitKaroError(
+                    f"exact amounts add up to {sum(amounts.values())}, not the total {total}"
+                )
+            return amounts
+        elif self.kind is SplitKind.PERCENT:
+            if sum(self.values.values()) != HUNDRED:
+                raise SplitKaroError(f"percentages add up to {sum(self.values.values())}, not 100")
+            weights = [self.values[name] for name in self.among]
+        else:
+            weights = [self.values[name] for name in self.among]
+
+        try:
+            parts = allocate(total, weights)
+        except MoneyError as exc:
+            raise SplitKaroError(str(exc)) from None
+        return dict(zip(self.among, parts))
+
+
+@dataclass
+class Member:
+    name: str
+    upi: str | None = None  # e.g. "asha@okbank", used for payment links
+
+
+@dataclass
+class Expense:
+    id: int
+    description: str
+    amount: Decimal
+    # Who paid, and how much each. Usually one person paid everything.
+    paid_by: dict[str, Decimal]
+    split: Split
+    date: dt.date
+    currency: str
+    category: str = "general"
+    note: str = ""
+
+    def validate(self) -> None:
+        if self.amount <= ZERO:
+            raise SplitKaroError("an expense amount must be greater than zero")
+        if not self.paid_by:
+            raise SplitKaroError("an expense needs at least one payer")
+        if any(v <= ZERO for v in self.paid_by.values()):
+            raise SplitKaroError("each payer must have paid more than zero")
+        paid = sum(self.paid_by.values())
+        if paid != self.amount:
+            raise SplitKaroError(f"payers paid {paid} in total, but the expense is {self.amount}")
+        self.split.portions(self.amount)  # raises if the split is inconsistent
+
+
+@dataclass
+class Transfer:
+    """Money handed from one member to another to settle up."""
+
+    sender: str
+    receiver: str
+    amount: Decimal
+    date: dt.date | None = None
+    note: str = ""
+
+
+@dataclass
+class Group:
+    name: str
+    currency: str = "INR"
+    members: list[Member] = field(default_factory=list)
+    expenses: list[Expense] = field(default_factory=list)
+    transfers: list[Transfer] = field(default_factory=list)
+    # Value of one unit of a foreign currency in the group currency,
+    # e.g. {"USD": Decimal("83.20")} for a group that keeps accounts in INR.
+    rates: dict[str, Decimal] = field(default_factory=dict)
+    next_id: int = 1
+
+    # -- members -------------------------------------------------------
+
+    def member(self, name: str) -> Member:
+        for m in self.members:
+            if m.name.casefold() == name.casefold():
+                return m
+        known = ", ".join(m.name for m in self.members) or "nobody yet"
+        raise SplitKaroError(f"no member called {name!r} (members: {known})")
+
+    def resolve(self, name: str) -> str:
+        """Return the member's canonical spelling; names are case-insensitive."""
+        return self.member(name).name
+
+    def add_member(self, name: str, upi: str | None = None) -> Member:
+        name = name.strip()
+        if not name:
+            raise SplitKaroError("a member needs a name")
+        if any(m.name.casefold() == name.casefold() for m in self.members):
+            raise SplitKaroError(f"{name!r} is already a member")
+        member = Member(name, upi)
+        self.members.append(member)
+        return member
+
+    def remove_member(self, name: str) -> None:
+        name = self.resolve(name)
+        if self._mentions(name):
+            raise SplitKaroError(f"{name} appears in expenses or payments; settle up and delete those first")
+        self.members = [m for m in self.members if m.name != name]
+
+    def _mentions(self, name: str) -> bool:
+        for e in self.expenses:
+            if name in e.paid_by or name in e.split.among:
+                return True
+        return any(name in (t.sender, t.receiver) for t in self.transfers)
+
+    # -- expenses and payments ----------------------------------------
+
+    def add_expense(self, expense: Expense) -> Expense:
+        expense.amount = to_money(expense.amount)
+        expense.paid_by = {self.resolve(k): to_money(v) for k, v in expense.paid_by.items()}
+        expense.split.among = [self.resolve(n) for n in expense.split.among]
+        expense.split.values = {self.resolve(k): v for k, v in expense.split.values.items()}
+        if expense.currency != self.currency and expense.currency not in self.rates:
+            cur = expense.currency
+            raise SplitKaroError(f"no exchange rate for {cur}; set one with: splitkaro rate {cur} <value>")
+        expense.validate()
+        expense.id = self.next_id
+        self.next_id += 1
+        self.expenses.append(expense)
+        return expense
+
+    def expense(self, expense_id: int) -> Expense:
+        for e in self.expenses:
+            if e.id == expense_id:
+                return e
+        raise SplitKaroError(f"no expense with id {expense_id}")
+
+    def delete_expense(self, expense_id: int) -> Expense:
+        expense = self.expense(expense_id)
+        self.expenses.remove(expense)
+        return expense
+
+    def add_transfer(self, transfer: Transfer) -> Transfer:
+        transfer.sender = self.resolve(transfer.sender)
+        transfer.receiver = self.resolve(transfer.receiver)
+        transfer.amount = to_money(transfer.amount)
+        if transfer.sender == transfer.receiver:
+            raise SplitKaroError("a member cannot pay themselves")
+        if transfer.amount <= ZERO:
+            raise SplitKaroError("a payment must be greater than zero")
+        self.transfers.append(transfer)
+        return transfer
+
+    def to_group_currency(self, amount: Decimal, currency: str) -> Decimal:
+        if currency == self.currency:
+            return amount
+        return to_money(amount * self.rates[currency])

splitkaro/money.py

@@ -0,0 +1,96 @@
+"""Exact money arithmetic.
+
+Amounts are ``Decimal`` values rounded to two places (rupees and paise, or the
+equivalent minor unit). Floats are never used, so 0.1 + 0.2 is exactly 0.3.
+"""
+
+from __future__ import annotations
+
+from decimal import ROUND_HALF_UP, Decimal, InvalidOperation
+
+CENT = Decimal("0.01")
+ZERO = Decimal("0.00")
+
+
+class MoneyError(ValueError):
+    pass
+
+
+def to_money(value: object) -> Decimal:
+    """Parse ``value`` (str, int or Decimal) into an amount with two decimals."""
+    if isinstance(value, float):
+        # Floats cannot represent most amounts exactly; make callers be explicit.
+        value = repr(value)
+    try:
+        amount = Decimal(str(value).replace(",", "").strip())
+    except InvalidOperation:
+        raise MoneyError(f"not a valid amount: {value!r}") from None
+    if not amount.is_finite():
+        raise MoneyError(f"not a valid amount: {value!r}")
+    return amount.quantize(CENT, rounding=ROUND_HALF_UP)
+
+
+def to_decimal(value: object) -> Decimal:
+    """Parse a non-money number such as a share, a percentage or a rate."""
+    try:
+        number = Decimal(str(value).strip())
+    except InvalidOperation:
+        raise MoneyError(f"not a valid number: {value!r}") from None
+    if not number.is_finite():
+        raise MoneyError(f"not a valid number: {value!r}")
+    return number
+
+
+def allocate(total: Decimal, weights: list[Decimal]) -> list[Decimal]:
+    """Split ``total`` in proportion to ``weights`` so the parts add up exactly.
+
+    Uses the largest-remainder method on whole paise: every part is rounded
+    down, then the leftover paise go to the parts that lost the most to
+    rounding (earlier parts win ties). Splitting 100.00 three ways gives
+    33.34, 33.33, 33.33.
+    """
+    if not weights:
+        raise MoneyError("cannot split an amount among nobody")
+    if any(w < 0 for w in weights):
+        raise MoneyError("weights cannot be negative")
+    weight_sum = sum(weights)
+    if weight_sum == 0:
+        raise MoneyError("weights add up to zero")
+
+    sign = -1 if total < 0 else 1
+    paise = int((abs(total) / CENT).to_integral_value())
+    exact = [Decimal(paise) * w / weight_sum for w in weights]
+    parts = [int(x) for x in exact]  # floor, since every value is >= 0
+    leftover = paise - sum(parts)
+
+    by_remainder = sorted(range(len(weights)), key=lambda i: (-(exact[i] - parts[i]), i))
+    for i in by_remainder[:leftover]:
+        parts[i] += 1
+
+    return [sign * Decimal(p) * CENT for p in parts]
+
+
+def format_money(amount: Decimal, currency: str = "INR") -> str:
+    """Format for people: ``₹1,23,456.50``, ``$12.00``, or ``12.00 CHF``.
+
+    Rupees use Indian digit grouping (lakhs and crores).
+    """
+    symbols = {"INR": "₹", "USD": "$", "EUR": "€", "GBP": "£", "JPY": "¥"}
+    sign = "-" if amount < 0 else ""
+    body = _indian_grouping(abs(amount)) if currency == "INR" else f"{abs(amount):,.2f}"
+    if currency in symbols:
+        return f"{sign}{symbols[currency]}{body}"
+    return f"{sign}{body} {currency}"
+
+
+def _indian_grouping(amount: Decimal) -> str:
+    whole, fraction = f"{amount:.2f}".split(".")
+    if len(whole) > 3:
+        head, tail = whole[:-3], whole[-3:]
+        groups = []
+        while len(head) > 2:
+            groups.insert(0, head[-2:])
+            head = head[:-2]
+        groups.insert(0, head)
+        whole = ",".join(groups) + "," + tail
+    return f"{whole}.{fraction}"

splitkaro/report.py

@@ -0,0 +1,69 @@
+"""Summaries: where the money went, and who carried how much of it."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from decimal import Decimal
+
+from splitkaro.ledger import effect
+from splitkaro.models import Expense, Group
+from splitkaro.money import ZERO
+
+
+@dataclass
+class Report:
+    total: Decimal = ZERO
+    count: int = 0
+    by_category: dict[str, Decimal] = field(default_factory=dict)
+    by_month: dict[str, Decimal] = field(default_factory=dict)
+    paid_by_member: dict[str, Decimal] = field(default_factory=dict)
+    share_by_member: dict[str, Decimal] = field(default_factory=dict)
+
+
+def filter_expenses(
+    group: Group,
+    month: str | None = None,
+    category: str | None = None,
+    member: str | None = None,
+) -> list[Expense]:
+    """Expenses matching every filter given. ``month`` is ``YYYY-MM``."""
+    name = group.resolve(member) if member else None
+    result = []
+    for e in sorted(group.expenses, key=lambda x: (x.date, x.id)):
+        if month and e.date.strftime("%Y-%m") != month:
+            continue
+        if category and e.category.casefold() != category.casefold():
+            continue
+        if name and name not in e.paid_by and name not in e.split.among:
+            continue
+        result.append(e)
+    return result
+
+
+def build_report(group: Group, expenses: list[Expense]) -> Report:
+    by_category: dict[str, Decimal] = defaultdict(lambda: ZERO)
+    by_month: dict[str, Decimal] = defaultdict(lambda: ZERO)
+    paid: dict[str, Decimal] = {m.name: ZERO for m in group.members}
+    share: dict[str, Decimal] = {m.name: ZERO for m in group.members}
+    total = ZERO
+
+    for expense in expenses:
+        e = effect(group, expense)
+        amount = sum(e.paid.values())
+        total += amount
+        by_category[expense.category] += amount
+        by_month[expense.date.strftime("%Y-%m")] += amount
+        for name, value in e.paid.items():
+            paid[name] += value
+        for name, value in e.owed.items():
+            share[name] += value
+
+    return Report(
+        total=total,
+        count=len(expenses),
+        by_category=dict(sorted(by_category.items(), key=lambda kv: (-kv[1], kv[0]))),
+        by_month=dict(sorted(by_month.items())),
+        paid_by_member=paid,
+        share_by_member=share,
+    )

splitkaro/storage.py

@@ -0,0 +1,128 @@
+"""Save a group as a readable JSON file (splitkaro.json by default).
+
+Amounts are stored as strings ("1200.50") so no precision is ever lost, and
+the file is written atomically so a crash can never leave it half-written.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+import tempfile
+from decimal import Decimal
+from typing import Any
+
+from splitkaro.models import Expense, Group, Member, Split, SplitKaroError, SplitKind, Transfer
+from splitkaro.money import to_decimal, to_money
+
+DEFAULT_FILE = "splitkaro.json"
+SCHEMA_VERSION = 1
+
+
+def load(path: str) -> Group:
+    try:
+        with open(path, encoding="utf-8") as handle:
+            data = json.load(handle)
+    except FileNotFoundError:
+        raise SplitKaroError(f"{path} not found; create a group first with: splitkaro init <name>") from None
+    except json.JSONDecodeError as exc:
+        raise SplitKaroError(f"{path} is not valid JSON: {exc}") from None
+    return from_dict(data)
+
+
+def save(group: Group, path: str) -> None:
+    text = json.dumps(to_dict(group), indent=2, ensure_ascii=False) + "\n"
+    directory = os.path.dirname(os.path.abspath(path))
+    fd, tmp = tempfile.mkstemp(prefix=".splitkaro-", suffix=".json", dir=directory)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+
+
+def to_dict(group: Group) -> dict[str, Any]:
+    return {
+        "version": SCHEMA_VERSION,
+        "name": group.name,
+        "currency": group.currency,
+        "next_id": group.next_id,
+        "rates": {k: str(v) for k, v in group.rates.items()},
+        "members": [{"name": m.name, "upi": m.upi} for m in group.members],
+        "expenses": [_expense_to_dict(e) for e in group.expenses],
+        "transfers": [
+            {
+                "from": t.sender,
+                "to": t.receiver,
+                "amount": str(t.amount),
+                "date": t.date.isoformat() if t.date else None,
+                "note": t.note,
+            }
+            for t in group.transfers
+        ],
+    }
+
+
+def from_dict(data: dict[str, Any]) -> Group:
+    version = data.get("version")
+    if version != SCHEMA_VERSION:
+        raise SplitKaroError(f"unsupported file version {version!r}; expected {SCHEMA_VERSION}")
+    try:
+        return Group(
+            name=data["name"],
+            currency=data["currency"],
+            next_id=int(data["next_id"]),
+            rates={k: to_decimal(v) for k, v in data.get("rates", {}).items()},
+            members=[Member(m["name"], m.get("upi")) for m in data["members"]],
+            expenses=[_expense_from_dict(e) for e in data["expenses"]],
+            transfers=[
+                Transfer(
+                    t["from"],
+                    t["to"],
+                    to_money(t["amount"]),
+                    dt.date.fromisoformat(t["date"]) if t.get("date") else None,
+                    t.get("note", ""),
+                )
+                for t in data["transfers"]
+            ],
+        )
+    except (KeyError, TypeError, ValueError) as exc:
+        raise SplitKaroError(f"the file is damaged or incomplete ({exc})") from None
+
+
+def _expense_to_dict(e: Expense) -> dict[str, Any]:
+    return {
+        "id": e.id,
+        "date": e.date.isoformat(),
+        "description": e.description,
+        "amount": str(e.amount),
+        "currency": e.currency,
+        "category": e.category,
+        "paid_by": {k: str(v) for k, v in e.paid_by.items()},
+        "split": {
+            "kind": e.split.kind.value,
+            "among": e.split.among,
+            "values": {k: str(v) for k, v in e.split.values.items()},
+        },
+        "note": e.note,
+    }
+
+
+def _expense_from_dict(d: dict[str, Any]) -> Expense:
+    split = d["split"]
+    values: dict[str, Decimal] = {k: to_decimal(v) for k, v in split.get("values", {}).items()}
+    return Expense(
+        id=int(d["id"]),
+        description=d["description"],
+        amount=to_money(d["amount"]),
+        paid_by={k: to_money(v) for k, v in d["paid_by"].items()},
+        split=Split(SplitKind(split["kind"]), list(split["among"]), values),
+        date=dt.date.fromisoformat(d["date"]),
+        currency=d["currency"],
+        category=d.get("category", "general"),
+        note=d.get("note", ""),
+    )

splitkaro/upi.py

@@ -0,0 +1,33 @@
+"""UPI payment links, so a suggested settlement is one tap away.
+
+A link like ``upi://pay?pa=asha@okbank&pn=Asha&am=450.00&cu=INR&tn=Goa+trip``
+opens any UPI app (GPay, PhonePe, Paytm, BHIM...) with the payee and amount
+filled in. The payer still reviews and confirms the payment in their app.
+"""
+
+from __future__ import annotations
+
+import re
+from decimal import Decimal
+from urllib.parse import urlencode
+
+from splitkaro.models import SplitKaroError
+
+_VPA_RE = re.compile(r"^[A-Za-z0-9.\-_]{2,256}@[A-Za-z][A-Za-z0-9]{1,64}$")
+
+
+def is_valid_vpa(vpa: str) -> bool:
+    """Check the shape of a UPI ID (virtual payment address), e.g. ``name@bank``."""
+    return bool(_VPA_RE.match(vpa))
+
+
+def payment_link(vpa: str, name: str, amount: Decimal, note: str = "") -> str:
+    if not is_valid_vpa(vpa):
+        raise SplitKaroError(f"{vpa!r} does not look like a UPI ID (expected something like name@bank)")
+    if amount <= 0:
+        raise SplitKaroError("a UPI payment must be greater than zero")
+    params = {"pa": vpa, "pn": name, "am": f"{amount:.2f}", "cu": "INR"}
+    if note:
+        # Many UPI apps cut the note at about 50 characters.
+        params["tn"] = note[:50]
+    return "upi://pay?" + urlencode(params)