rustfava 0.1.0__py3-none-any.whl

rustfava/beans/create.py

@@ -0,0 +1,377 @@
+"""Helpers to create entries."""
+
+from __future__ import annotations
+
+import re
+from decimal import Decimal
+from typing import overload
+from typing import TYPE_CHECKING
+
+from rustfava.rustledger.types import FrozenDict
+from rustfava.rustledger.types import RLAmount
+from rustfava.rustledger.types import RLBalance
+from rustfava.rustledger.types import RLClose
+from rustfava.rustledger.types import RLCost
+from rustfava.rustledger.types import RLDocument
+from rustfava.rustledger.types import RLNote
+from rustfava.rustledger.types import RLOpen
+from rustfava.rustledger.types import RLPosting
+from rustfava.rustledger.types import RLPosition
+from rustfava.rustledger.types import RLTransaction
+
+if TYPE_CHECKING:  # pragma: no cover
+    import datetime
+
+    from rustfava.beans.abc import Balance
+    from rustfava.beans.abc import Close
+    from rustfava.beans.abc import Document
+    from rustfava.beans.abc import Meta
+    from rustfava.beans.abc import Note
+    from rustfava.beans.abc import Open
+    from rustfava.beans.abc import Position
+    from rustfava.beans.abc import Posting
+    from rustfava.beans.abc import Transaction
+    from rustfava.beans.flags import Flag
+    from rustfava.beans.protocols import Amount
+    from rustfava.beans.protocols import Cost
+
+
+# Pattern to match amount strings like "100 USD", "-10.50 EUR", "1,000.00 CHF"
+_AMOUNT_RE = re.compile(r"^\s*([-+]?\s*[\d,]+(?:\.\d*)?)\s+([A-Z][A-Z0-9'._-]*[A-Z0-9]?)\s*$")
+
+
+def _parse_amount_string(amt_str: str) -> RLAmount:
+    """Parse an amount string like '100 USD' into an RLAmount."""
+    match = _AMOUNT_RE.match(amt_str)
+    if not match:
+        msg = f"Invalid amount string: {amt_str}"
+        raise ValueError(msg)
+    number_str, currency = match.groups()
+    # Remove commas and spaces from number
+    number_str = number_str.replace(",", "").replace(" ", "")
+    return RLAmount(number=Decimal(number_str), currency=currency)
+
+
+@overload
+def amount(amt: Amount) -> Amount: ...  # pragma: no cover
+
+
+@overload
+def amount(amt: str) -> Amount: ...  # pragma: no cover
+
+
+@overload
+def amount(amt: Decimal, currency: str) -> Amount: ...  # pragma: no cover
+
+
+def amount(amt: Amount | Decimal | str, currency: str | None = None) -> Amount:
+    """Amount from a string or tuple."""
+    if isinstance(amt, str):
+        return _parse_amount_string(amt)
+    if hasattr(amt, "number") and hasattr(amt, "currency"):
+        return amt  # Already an Amount-like object
+    if not isinstance(currency, str):  # pragma: no cover
+        raise TypeError
+    return RLAmount(amt, currency)
+
+
+_amount = amount
+
+
+def cost(
+    number: Decimal,
+    currency: str,
+    date: datetime.date,
+    label: str | None = None,
+) -> Cost:
+    """Create a Cost."""
+    return RLCost(number, currency, date, label)  # type: ignore[return-value]
+
+
+def position(units: Amount, cost: Cost | None) -> Position:
+    """Create a Position."""
+    # Convert units to RLAmount if needed
+    if isinstance(units, str):
+        units = _parse_amount_string(units)
+    elif not isinstance(units, RLAmount):
+        units = RLAmount(units.number, units.currency)
+
+    # Convert cost to RLCost if needed
+    rl_cost: RLCost | None = None
+    if cost is not None:
+        if isinstance(cost, RLCost):
+            rl_cost = cost
+        else:
+            rl_cost = RLCost(
+                number=cost.number,
+                currency=cost.currency,
+                date=cost.date,
+                label=cost.label,
+            )
+
+    return RLPosition(units=units, cost=rl_cost)  # type: ignore[return-value]
+
+
+def posting(
+    account: str,
+    units: Amount | str,
+    cost: Cost | None = None,
+    price: Amount | str | None = None,
+    flag: str | None = None,
+    meta: Meta | None = None,
+) -> Posting:
+    """Create a Posting."""
+    # Convert units
+    rl_units: RLAmount | None = None
+    if units is not None:
+        if isinstance(units, str):
+            rl_units = _parse_amount_string(units)
+        elif isinstance(units, RLAmount):
+            rl_units = units
+        else:
+            rl_units = RLAmount(units.number, units.currency)
+
+    # Convert cost
+    rl_cost: RLCost | None = None
+    if cost is not None:
+        if isinstance(cost, RLCost):
+            rl_cost = cost
+        elif hasattr(cost, "number_per"):
+            # CostSpec - convert to RLCost
+            number = getattr(cost, "number_per", None)
+            currency = getattr(cost, "currency", None)
+            date = getattr(cost, "date", None)
+            label = getattr(cost, "label", None)
+            # Handle MISSING sentinels - MISSING is a class used as a value
+            if number is not None and isinstance(number, type) and number.__name__ == "MISSING":
+                number = None
+            if currency is not None and isinstance(currency, type) and currency.__name__ == "MISSING":
+                currency = None
+            # Only create cost if we have a valid currency
+            if currency is not None:
+                rl_cost = RLCost(
+                    number=number,
+                    currency=currency,
+                    date=date,
+                    label=label,
+                )
+            # If both number and currency are MISSING, we still want to represent
+            # an empty cost spec as "{}" in output - set cost to a sentinel
+            elif number is None:
+                # CostSpec with all MISSING - will be rendered as "{}"
+                rl_cost = None  # Empty cost will be handled specially
+        else:
+            rl_cost = RLCost(
+                number=cost.number,
+                currency=cost.currency,
+                date=cost.date,
+                label=cost.label,
+            )
+
+    # Convert price
+    rl_price: RLAmount | None = None
+    if price is not None:
+        if isinstance(price, str):
+            rl_price = _parse_amount_string(price)
+        elif isinstance(price, RLAmount):
+            rl_price = price
+        else:
+            rl_price = RLAmount(price.number, price.currency)
+
+    # Convert meta
+    rl_meta: FrozenDict | None = None
+    if meta is not None:
+        rl_meta = FrozenDict(dict(meta))
+
+    return RLPosting(  # type: ignore[return-value]
+        account=account,
+        units=rl_units,
+        cost=rl_cost,
+        price=rl_price,
+        flag=flag,
+        meta=rl_meta,
+    )
+
+
+_EMPTY_SET: frozenset[str] = frozenset()
+
+
+def _make_meta(meta: Meta) -> FrozenDict:
+    """Convert meta dict to FrozenDict."""
+    return FrozenDict(dict(meta))
+
+
+def transaction(
+    meta: Meta,
+    date: datetime.date,
+    flag: Flag,
+    payee: str | None,
+    narration: str,
+    tags: frozenset[str] | None = None,
+    links: frozenset[str] | None = None,
+    postings: list[Posting] | None = None,
+) -> Transaction:
+    """Create a Transaction."""
+    # Convert postings to RLPosting if needed
+    rl_postings: tuple[RLPosting, ...] = ()
+    if postings:
+        converted = []
+        for p in postings:
+            if isinstance(p, RLPosting):
+                converted.append(p)
+            else:
+                # Convert from other posting type
+                rl_units: RLAmount | None = None
+                if p.units is not None:
+                    if isinstance(p.units, RLAmount):
+                        rl_units = p.units
+                    else:
+                        rl_units = RLAmount(p.units.number, p.units.currency)
+
+                rl_cost: RLCost | None = None
+                if p.cost is not None:
+                    if isinstance(p.cost, RLCost):
+                        rl_cost = p.cost
+                    else:
+                        rl_cost = RLCost(
+                            number=p.cost.number,
+                            currency=p.cost.currency,
+                            date=p.cost.date,
+                            label=p.cost.label,
+                        )
+
+                rl_price: RLAmount | None = None
+                if p.price is not None:
+                    if isinstance(p.price, RLAmount):
+                        rl_price = p.price
+                    else:
+                        rl_price = RLAmount(p.price.number, p.price.currency)
+
+                rl_meta: FrozenDict | None = None
+                if p.meta:
+                    rl_meta = FrozenDict(dict(p.meta))
+
+                converted.append(RLPosting(
+                    account=p.account,
+                    units=rl_units,
+                    cost=rl_cost,
+                    price=rl_price,
+                    flag=p.flag,
+                    meta=rl_meta,
+                ))
+        rl_postings = tuple(converted)
+
+    return RLTransaction(  # type: ignore[return-value]
+        meta=_make_meta(meta),
+        date=date,
+        flag=flag or "*",
+        payee=payee,
+        narration=narration,
+        tags=tags if tags is not None else _EMPTY_SET,
+        links=links if links is not None else _EMPTY_SET,
+        postings=rl_postings,
+    )
+
+
+def balance(
+    meta: Meta,
+    date: datetime.date,
+    account: str,
+    amount: Amount | str,
+    tolerance: Decimal | None = None,
+    diff_amount: Amount | None = None,
+) -> Balance:
+    """Create a Balance."""
+    # Convert amount
+    rl_amount: RLAmount
+    if isinstance(amount, str):
+        rl_amount = _parse_amount_string(amount)
+    elif isinstance(amount, RLAmount):
+        rl_amount = amount
+    else:
+        rl_amount = RLAmount(amount.number, amount.currency)
+
+    # Convert diff_amount
+    rl_diff: RLAmount | None = None
+    if diff_amount is not None:
+        if isinstance(diff_amount, RLAmount):
+            rl_diff = diff_amount
+        else:
+            rl_diff = RLAmount(diff_amount.number, diff_amount.currency)
+
+    return RLBalance(  # type: ignore[return-value]
+        meta=_make_meta(meta),
+        date=date,
+        account=account,
+        amount=rl_amount,
+        tolerance=tolerance,
+        diff_amount=rl_diff,
+    )
+
+
+def close(
+    meta: Meta,
+    date: datetime.date,
+    account: str,
+) -> Close:
+    """Create a Close."""
+    return RLClose(  # type: ignore[return-value]
+        meta=_make_meta(meta),
+        date=date,
+        account=account,
+    )
+
+
+def document(
+    meta: Meta,
+    date: datetime.date,
+    account: str,
+    filename: str,
+    tags: frozenset[str] | None = None,
+    links: frozenset[str] | None = None,
+) -> Document:
+    """Create a Document."""
+    return RLDocument(  # type: ignore[return-value]
+        meta=_make_meta(meta),
+        date=date,
+        account=account,
+        filename=filename,
+        tags=tags if tags is not None else _EMPTY_SET,
+        links=links if links is not None else _EMPTY_SET,
+    )
+
+
+def note(
+    meta: Meta,
+    date: datetime.date,
+    account: str,
+    comment: str,
+    tags: frozenset[str] | None = None,
+    links: frozenset[str] | None = None,
+) -> Note:
+    """Create a Note."""
+    return RLNote(  # type: ignore[return-value]
+        meta=_make_meta(meta),
+        date=date,
+        account=account,
+        comment=comment,
+        tags=tags if tags is not None else _EMPTY_SET,
+        links=links if links is not None else _EMPTY_SET,
+    )
+
+
+def open(  # noqa: A001
+    meta: Meta,
+    date: datetime.date,
+    account: str,
+    currencies: list[str],
+    booking: str | None = None,
+) -> Open:
+    """Create an Open."""
+    return RLOpen(  # type: ignore[return-value]
+        meta=_make_meta(meta),
+        date=date,
+        account=account,
+        currencies=tuple(currencies),
+        booking=booking,
+    )

rustfava/beans/flags.py

@@ -0,0 +1,20 @@
+"""Beancount entry flags."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from typing import TypeAlias
+
+    Flag: TypeAlias = str
+
+FLAG_CONVERSIONS = "C"
+FLAG_MERGING = "M"
+FLAG_OKAY = "*"
+FLAG_PADDING = "P"
+FLAG_RETURNS = "R"
+FLAG_SUMMARIZE = "S"
+FLAG_TRANSFER = "T"
+FLAG_UNREALIZED = "U"
+FLAG_WARNING = "!"

rustfava/beans/funcs.py

@@ -0,0 +1,38 @@
+"""Various functions to deal with Beancount data."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from rustfava.beans.abc import Directive
+
+
+def hash_entry(entry: Directive) -> str:
+    """Hash an entry."""
+    # Rustledger provides pre-computed hash in meta
+    meta = getattr(entry, "meta", None)
+    if meta and isinstance(meta, dict) and "hash" in meta:
+        return str(meta["hash"])
+    # Rustledger dataclass (for plugin-generated entries without hash)
+    if hasattr(entry, "__dataclass_fields__"):
+        content = f"{type(entry).__name__}|{entry.date}|{getattr(entry, 'account', '')}"
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+    # Beancount namedtuple (for entries created by create module)
+    if hasattr(entry, "_fields"):
+        content = f"{type(entry).__name__}|{entry.date}|{getattr(entry, 'narration', '')}"
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+    # Fallback for other types
+    return hashlib.sha256(str(entry).encode()).hexdigest()[:16]
+
+
+def get_position(entry: Directive) -> tuple[str, int]:
+    """Get the filename and position from the entry metadata."""
+    meta = entry.meta
+    filename = meta["filename"]
+    lineno = meta["lineno"]
+    if isinstance(filename, str) and isinstance(lineno, int):
+        return (filename, lineno)
+    msg = "Invalid filename or lineno in entry metadata."
+    raise ValueError(msg)

rustfava/beans/helpers.py

@@ -0,0 +1,52 @@
+"""Helpers for Beancount entries."""
+
+from __future__ import annotations
+
+from bisect import bisect_left
+from dataclasses import replace as dataclass_replace
+from operator import attrgetter
+from typing import Any
+from typing import TYPE_CHECKING
+from typing import TypeVar
+
+if TYPE_CHECKING:  # pragma: no cover
+    import datetime
+    from collections.abc import Sequence
+
+    from rustfava.beans.abc import Directive
+    from rustfava.beans.abc import Posting
+
+    T = TypeVar("T", bound=Directive | Posting)
+
+
+def replace(entry: T, **kwargs: Any) -> T:
+    """Create a copy of the given directive, replacing some arguments."""
+    # Beancount namedtuple
+    if hasattr(entry, "_replace"):
+        return entry._replace(**kwargs)  # type: ignore[no-any-return]
+    # Rustledger dataclass
+    if hasattr(entry, "__dataclass_fields__"):
+        return dataclass_replace(entry, **kwargs)  # type: ignore[type-var]
+    msg = f"Could not replace attribute in type {type(entry)}"
+    raise TypeError(msg)
+
+
+_get_date = attrgetter("date")
+
+
+def slice_entry_dates(
+    entries: Sequence[T], begin: datetime.date, end: datetime.date
+) -> Sequence[T]:
+    """Get slice of entries in a date window.
+
+    Args:
+        entries: A date-sorted list of dated directives.
+        begin: The first date to include.
+        end: One day beyond the last date.
+
+    Returns:
+        The slice between the given dates.
+    """
+    index_begin = bisect_left(entries, begin, key=_get_date)
+    index_end = bisect_left(entries, end, key=_get_date)
+    return entries[index_begin:index_end]

rustfava/beans/ingest.py

@@ -0,0 +1,75 @@
+"""Types for Beancount importers."""
+
+from __future__ import annotations
+
+from typing import Protocol
+from typing import runtime_checkable
+from typing import TYPE_CHECKING
+from typing import TypeVar
+
+if TYPE_CHECKING:  # pragma: no cover
+    import datetime
+    from collections.abc import Callable
+    from collections.abc import Sequence
+
+    from rustfava.beans.abc import Directive
+
+
+T = TypeVar("T")
+
+
+class FileMemo(Protocol):
+    """The file with caching support that is passed to importers."""
+
+    name: str
+
+    def convert(self, converter_func: Callable[[str], T]) -> T:
+        """Run a conversion function for the file."""
+
+    def mimetype(self) -> str:
+        """Get the mimetype of the file."""
+
+    def contents(self) -> str:
+        """Get the file contents."""
+
+
+@runtime_checkable
+class BeanImporterProtocol(Protocol):
+    """Interface for Beancount importers.
+
+    typing.Protocol version of beancount.ingest.importer.ImporterProtocol
+
+    Importers can subclass from this one instead of the Beancount one to
+    get type checking for the methods.
+    """
+
+    def name(self) -> str:
+        """Return a unique id/name for this importer."""
+        cls = self.__class__
+        return f"{cls.__module__}.{cls.__name__}"
+
+    def identify(self, file: FileMemo) -> bool:
+        """Return true if this importer matches the given file."""
+
+    def extract(
+        self,
+        file: FileMemo,  # noqa: ARG002
+        *,
+        existing_entries: Sequence[Directive] | None = None,  # noqa: ARG002
+    ) -> list[Directive] | None:  # pragma: no cover
+        """Extract transactions from a file."""
+        return None
+
+    def file_account(self, file: FileMemo) -> str:
+        """Return an account associated with the given file."""
+
+    def file_name(self, file: FileMemo) -> str | None:  # noqa: ARG002
+        """A filter that optionally renames a file before filing."""
+        return None
+
+    def file_date(
+        self,
+        file: FileMemo,  # noqa: ARG002
+    ) -> datetime.date | None:
+        """Attempt to obtain a date that corresponds to the given file."""
+        return None

rustfava/beans/load.py

@@ -0,0 +1,31 @@
+"""Load Beancount files and strings."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rustfava.rustledger.loader import load_string as rl_load_string
+from rustfava.rustledger.loader import load_uncached as rl_load_uncached
+
+if TYPE_CHECKING:  # pragma: no cover
+    from rustfava.beans.types import LoaderResult
+
+
+def load_string(value: str) -> LoaderResult:
+    """Load a Beancount string."""
+    return rl_load_string(value)
+
+
+def load_uncached(
+    beancount_file_path: str,
+    *,
+    is_encrypted: bool,
+) -> LoaderResult:
+    """Load a Beancount file."""
+    # Encrypted files use beancount (rustledger doesn't support GPG decryption)
+    if is_encrypted:  # pragma: no cover
+        from beancount import loader
+
+        return loader.load_file(beancount_file_path)  # type: ignore[return-value]
+
+    return rl_load_uncached(beancount_file_path, is_encrypted=is_encrypted)