lib-ledger-core 0.3.0__py3-none-any.whl

ledger_core/__init__.py

@@ -0,0 +1,53 @@
+from ledger_core.adapters import (
+    EVENT_STORE_ADAPTER_GROUP,
+    LEDGER_ADAPTER_GROUP,
+    list_event_store_adapters,
+    list_ledger_adapters,
+    load_event_store_adapter,
+    load_ledger_adapter,
+)
+from ledger_core.ddl import (
+    DDL_PLUGIN_GROUP,
+    DdlPlugin,
+    apply_ddl_plugins,
+    list_ddl_plugins,
+    load_ddl_plugins,
+)
+from ledger_core.exceptions import (
+    InsufficientBalanceError,
+    LedgerError,
+    OccError,
+)
+from ledger_core.interfaces import EventStorePort, LedgerPort
+from ledger_core.models import Entry, TransferCommand
+from ledger_core.schema import (
+    event_store_events,
+    ledger_accounts,
+    ledger_transfers,
+    metadata,
+)
+
+__all__ = [
+    "LedgerPort",
+    "EventStorePort",
+    "TransferCommand",
+    "Entry",
+    "LedgerError",
+    "InsufficientBalanceError",
+    "OccError",
+    "metadata",
+    "ledger_accounts",
+    "ledger_transfers",
+    "event_store_events",
+    "LEDGER_ADAPTER_GROUP",
+    "EVENT_STORE_ADAPTER_GROUP",
+    "load_ledger_adapter",
+    "load_event_store_adapter",
+    "list_ledger_adapters",
+    "list_event_store_adapters",
+    "DDL_PLUGIN_GROUP",
+    "DdlPlugin",
+    "load_ddl_plugins",
+    "apply_ddl_plugins",
+    "list_ddl_plugins",
+]

ledger_core/adapters/__init__.py

@@ -0,0 +1,17 @@
+from ledger_core.adapters.registry import (
+    EVENT_STORE_ADAPTER_GROUP,
+    LEDGER_ADAPTER_GROUP,
+    list_event_store_adapters,
+    list_ledger_adapters,
+    load_event_store_adapter,
+    load_ledger_adapter,
+)
+
+__all__ = [
+    "LEDGER_ADAPTER_GROUP",
+    "EVENT_STORE_ADAPTER_GROUP",
+    "load_ledger_adapter",
+    "load_event_store_adapter",
+    "list_ledger_adapters",
+    "list_event_store_adapters",
+]

ledger_core/adapters/kurrent.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from ledger_core.exceptions import OccError
+
+
+class KurrentEventStore:
+    """EventStorePort implementation backed by KurrentDB."""
+
+    def __init__(self, connection_string: str) -> None:
+        self.connection_string = connection_string
+        self._client: Any | None = None
+
+    @property
+    def client(self) -> Any:
+        if self._client is None:
+            from kurrentdbclient import AsyncKurrentDBClient
+
+            self._client = AsyncKurrentDBClient(uri=self.connection_string)
+        return self._client
+
+    async def close(self) -> None:
+        if self._client is not None:
+            await self._client.close()
+            self._client = None
+
+    async def ping(self) -> bool:
+        try:
+            await self.client.get_current_version(stream_name="__ping__")
+            return True
+        except Exception:
+            return False
+
+    def _stream_name(self, tenant_id: str, stream_id: str) -> str:
+        return f"{tenant_id}-{stream_id}"
+
+    async def _current_version(self, tenant_id: str, stream_id: str) -> int:
+        from kurrentdbclient import StreamState
+
+        version = await self.client.get_current_version(
+            stream_name=self._stream_name(tenant_id, stream_id)
+        )
+        if version is StreamState.NO_STREAM:
+            return 0
+        return int(version) + 1
+
+    async def append(
+        self,
+        tenant_id: str,
+        stream_id: str,
+        events: list[dict[str, Any]],
+        expected_version: int | None = None,
+    ) -> None:
+        import msgspec
+        from kurrentdbclient import NewEvent, StreamState
+        from kurrentdbclient.exceptions import WrongCurrentVersionError
+
+        full_stream = self._stream_name(tenant_id, stream_id)
+        new_events = []
+        for event in events:
+            data = dict(event)
+            event_type = data.pop("type", "Unknown")
+            new_events.append(
+                NewEvent(
+                    id=uuid.uuid4(),
+                    type=event_type,
+                    data=msgspec.json.encode(data),
+                )
+            )
+
+        current_version: int | StreamState = StreamState.ANY
+        if expected_version is not None:
+            if expected_version == 0:
+                current_version = StreamState.NO_STREAM
+            else:
+                current_version = expected_version - 1
+
+        try:
+            await self.client.append_to_stream(
+                stream_name=full_stream,
+                events=new_events,
+                current_version=current_version,
+            )
+        except WrongCurrentVersionError as e:
+            actual = await self._current_version(tenant_id, stream_id)
+            raise OccError(stream_id, expected_version, actual) from e
+
+    async def read(self, tenant_id: str, stream_id: str) -> list[dict[str, Any]]:
+        import msgspec
+        from kurrentdbclient.exceptions import NotFoundError
+
+        full_stream = self._stream_name(tenant_id, stream_id)
+        try:
+            events: list[dict[str, Any]] = []
+            async for recorded in await self.client.read_stream(
+                stream_name=full_stream
+            ):
+                data = msgspec.json.decode(recorded.data)
+                data["type"] = recorded.type
+                events.append(data)
+            return events
+        except NotFoundError:
+            return []

ledger_core/adapters/registry.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import importlib.metadata as metadata
+from collections.abc import Callable
+from typing import Any
+
+from ledger_core.interfaces import EventStorePort, LedgerPort
+
+LEDGER_ADAPTER_GROUP = "ledger_core.ledger"
+EVENT_STORE_ADAPTER_GROUP = "ledger_core.event_store"
+
+
+def _load_factory(group: str, name: str) -> Callable[..., Any]:
+    eps = metadata.entry_points(group=group)
+    for ep in eps:
+        if ep.name == name:
+            return ep.load()  # type: ignore[no-any-return]
+    raise KeyError(f"No adapter named {name!r} in group {group!r}")
+
+
+def load_ledger_adapter(name: str) -> Callable[..., LedgerPort]:
+    """Load a ledger adapter factory by entry-point name."""
+    return _load_factory(LEDGER_ADAPTER_GROUP, name)
+
+
+def load_event_store_adapter(name: str) -> Callable[..., EventStorePort]:
+    """Load an event-store adapter factory by entry-point name."""
+    return _load_factory(EVENT_STORE_ADAPTER_GROUP, name)
+
+
+def list_ledger_adapters() -> list[str]:
+    """Return names of all registered ledger adapters."""
+    return [ep.name for ep in metadata.entry_points(group=LEDGER_ADAPTER_GROUP)]
+
+
+def list_event_store_adapters() -> list[str]:
+    """Return names of all registered event-store adapters."""
+    return [ep.name for ep in metadata.entry_points(group=EVENT_STORE_ADAPTER_GROUP)]

ledger_core/adapters/sqlalchemy.py

@@ -0,0 +1,355 @@
+from __future__ import annotations
+
+import uuid
+from datetime import UTC
+from decimal import Decimal
+from typing import Any
+
+import sqlalchemy as sa
+from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine, create_async_engine
+
+from ledger_core.exceptions import LedgerError, OccError
+from ledger_core.models import Entry, TransferCommand
+from ledger_core.schema import event_store_events, ledger_accounts, ledger_transfers
+
+
+class SqlAlchemyLedger:
+    """LedgerPort implementation using SQLAlchemy Core async.
+
+    Balance convention: balance(account) = credits_into(account) - debits_from(account).
+    A transfer credits the source account and debits the destination account.
+    The source account (credit_account) must have a non-negative balance after
+    the transfer. This matches the stock-keeper semantics where the source
+    warehouse must have enough stock.
+    """
+
+    def __init__(self, engine: AsyncEngine) -> None:
+        self._engine = engine
+
+    @classmethod
+    def from_url(cls, url: str | sa.URL, **kwargs: Any) -> SqlAlchemyLedger:
+        return cls(create_async_engine(url, **kwargs))
+
+    async def ping(self) -> bool:
+        async with self._engine.connect() as conn:
+            await conn.execute(sa.text("SELECT 1"))
+            return True
+
+    async def close(self) -> None:
+        await self._engine.dispose()
+
+    async def seed_account(self, tenant_id: str, account: str, amount: Decimal) -> None:
+        """Create balance for an account without enforcing source balance.
+
+        Useful in tests and for bootstrapping opening balances.
+        """
+        async with self._engine.begin() as conn:
+            await self._ensure_account(conn, tenant_id, account)
+            await conn.execute(
+                sa.insert(ledger_transfers).values(
+                    id=uuid.uuid4(),
+                    tenant_id=tenant_id,
+                    debit_account=account,
+                    credit_account="EXTERNAL",
+                    amount=amount,
+                    reference="seed",
+                    status="committed",
+                )
+            )
+
+    async def _ensure_account(
+        self,
+        conn: AsyncConnection,
+        tenant_id: str,
+        account_code: str,
+    ) -> None:
+        stmt = sa.select(ledger_accounts.c.id).where(
+            ledger_accounts.c.tenant_id == tenant_id,
+            ledger_accounts.c.account_code == account_code,
+        )
+        result = await conn.execute(stmt)
+        if result.scalar_one_or_none() is None:
+            await conn.execute(
+                sa.insert(ledger_accounts).values(
+                    id=uuid.uuid4(),
+                    tenant_id=tenant_id,
+                    account_code=account_code,
+                )
+            )
+
+    async def _balance_at(
+        self,
+        conn: AsyncConnection,
+        tenant_id: str,
+        account: str,
+        exclude_transfer_ids: list[uuid.UUID] | None = None,
+    ) -> Decimal:
+        """Balance = debits_into_account - credits_from_account."""
+        debit_sum = sa.select(
+            sa.func.coalesce(sa.func.sum(ledger_transfers.c.amount), Decimal("0"))
+        ).where(
+            ledger_transfers.c.tenant_id == tenant_id,
+            ledger_transfers.c.debit_account == account,
+            ledger_transfers.c.status == "committed",
+        )
+        credit_sum = sa.select(
+            sa.func.coalesce(sa.func.sum(ledger_transfers.c.amount), Decimal("0"))
+        ).where(
+            ledger_transfers.c.tenant_id == tenant_id,
+            ledger_transfers.c.credit_account == account,
+            ledger_transfers.c.status == "committed",
+        )
+        if exclude_transfer_ids:
+            debit_sum = debit_sum.where(
+                ledger_transfers.c.id.notin_(exclude_transfer_ids)
+            )
+            credit_sum = credit_sum.where(
+                ledger_transfers.c.id.notin_(exclude_transfer_ids)
+            )
+
+        debit = Decimal((await conn.execute(debit_sum)).scalar_one())
+        credit = Decimal((await conn.execute(credit_sum)).scalar_one())
+        return debit - credit
+
+    async def transfer(self, cmd: TransferCommand) -> str:
+        if cmd.legs:
+            return await self._compound_transfer(cmd)
+
+        transfer_id = uuid.uuid4()
+        status = "pending" if cmd.is_pending else "committed"
+        async with self._engine.begin() as conn:
+            await self._ensure_account(conn, cmd.tenant_id, cmd.debit_account)
+            await self._ensure_account(conn, cmd.tenant_id, cmd.credit_account)
+
+            if status == "committed":
+                # Removed InsufficientBalanceError check;
+                # ERP accounts naturally have credit balances
+                pass
+
+            await conn.execute(
+                sa.insert(ledger_transfers).values(
+                    id=transfer_id,
+                    tenant_id=cmd.tenant_id,
+                    debit_account=cmd.debit_account,
+                    credit_account=cmd.credit_account,
+                    amount=cmd.amount,
+                    reference=cmd.reference,
+                    description=cmd.description,
+                    status=status,
+                )
+            )
+
+        return str(transfer_id)
+
+    async def _compound_transfer(self, cmd: TransferCommand) -> str:
+        group_id = uuid.uuid4()
+        rows = []
+        for leg in cmd.legs:
+            rows.append(
+                {
+                    "id": uuid.uuid4(),
+                    "tenant_id": cmd.tenant_id,
+                    "debit_account": leg["debit_account"],
+                    "credit_account": leg["credit_account"],
+                    "amount": Decimal(leg["amount"]),
+                    "reference": cmd.reference,
+                    "description": cmd.description,
+                    "status": "committed",
+                }
+            )
+
+        async with self._engine.begin() as conn:
+            for row in rows:
+                await self._ensure_account(conn, cmd.tenant_id, row["debit_account"])
+                await self._ensure_account(conn, cmd.tenant_id, row["credit_account"])
+
+            await conn.execute(sa.insert(ledger_transfers), rows)
+
+        return str(group_id)
+
+    async def get_balance(self, tenant_id: str, account: str) -> Decimal:
+        async with self._engine.begin() as conn:
+            return await self._balance_at(conn, tenant_id, account)
+
+    async def get_history(
+        self, tenant_id: str, account: str, limit: int = 100
+    ) -> list[Entry]:
+        stmt = (
+            sa.select(
+                ledger_transfers.c.id,
+                ledger_transfers.c.created_at,
+                ledger_transfers.c.debit_account,
+                ledger_transfers.c.credit_account,
+                ledger_transfers.c.amount,
+                ledger_transfers.c.reference,
+                ledger_transfers.c.status,
+            )
+            .where(
+                ledger_transfers.c.tenant_id == tenant_id,
+                ledger_transfers.c.status != "voided",
+                ledger_transfers.c.reference != "seed",
+                sa.or_(
+                    ledger_transfers.c.debit_account == account,
+                    ledger_transfers.c.credit_account == account,
+                ),
+            )
+            .order_by(
+                ledger_transfers.c.created_at.desc(),
+                ledger_transfers.c.id.desc(),
+            )
+            .limit(limit)
+        )
+        async with self._engine.connect() as conn:
+            result = await conn.execute(stmt)
+            rows = result.mappings().all()
+
+        entries: list[Entry] = []
+        for row in rows:
+            ts = row["created_at"]
+            if ts.tzinfo is None:
+                ts = ts.replace(tzinfo=UTC)
+            if row["debit_account"] == account:
+                entries.append(
+                    Entry(
+                        id=str(row["id"]),
+                        timestamp=ts,
+                        account=account,
+                        amount=Decimal(row["amount"]),
+                        type="debit",
+                        reference=row["reference"] or "",
+                    )
+                )
+            else:
+                entries.append(
+                    Entry(
+                        id=str(row["id"]),
+                        timestamp=ts,
+                        account=account,
+                        amount=Decimal(row["amount"]),
+                        type="credit",
+                        reference=row["reference"] or "",
+                    )
+                )
+        return entries
+
+    async def post_pending(self, tenant_id: str, pending_id: str) -> str:
+        transfer_id = uuid.UUID(pending_id)
+        async with self._engine.begin() as conn:
+            row = (
+                (
+                    await conn.execute(
+                        sa.select(
+                            ledger_transfers.c.credit_account,
+                            ledger_transfers.c.amount,
+                        ).where(
+                            ledger_transfers.c.id == transfer_id,
+                            ledger_transfers.c.tenant_id == tenant_id,
+                        )
+                    )
+                )
+                .mappings()
+                .one_or_none()
+            )
+
+            if row is None:
+                raise LedgerError(f"Pending transfer {pending_id} not found")
+
+            # Removed InsufficientBalanceError check
+
+            await conn.execute(
+                sa.update(ledger_transfers)
+                .where(ledger_transfers.c.id == transfer_id)
+                .values(status="committed")
+            )
+        return pending_id
+
+    async def void_pending(self, tenant_id: str, pending_id: str) -> str:
+        transfer_id = uuid.UUID(pending_id)
+        async with self._engine.begin() as conn:
+            result = await conn.execute(
+                sa.update(ledger_transfers)
+                .where(
+                    ledger_transfers.c.id == transfer_id,
+                    ledger_transfers.c.tenant_id == tenant_id,
+                )
+                .values(status="voided")
+            )
+            if result.rowcount == 0:
+                raise LedgerError(f"Pending transfer {pending_id} not found")
+        return pending_id
+
+
+class SqlAlchemyEventStore:
+    """EventStorePort implementation using SQLAlchemy Core async."""
+
+    def __init__(self, engine: AsyncEngine) -> None:
+        self._engine = engine
+
+    @classmethod
+    def from_url(cls, url: str | sa.URL, **kwargs: Any) -> SqlAlchemyEventStore:
+        return cls(create_async_engine(url, **kwargs))
+
+    async def ping(self) -> bool:
+        async with self._engine.connect() as conn:
+            await conn.execute(sa.text("SELECT 1"))
+            return True
+
+    async def close(self) -> None:
+        await self._engine.dispose()
+
+    async def append(
+        self,
+        tenant_id: str,
+        stream_id: str,
+        events: list[dict[str, Any]],
+        expected_version: int | None = None,
+    ) -> None:
+        async with self._engine.begin() as conn:
+            max_version_stmt = sa.select(
+                sa.func.coalesce(sa.func.max(event_store_events.c.version), 0)
+            ).where(
+                event_store_events.c.tenant_id == tenant_id,
+                event_store_events.c.stream_id == stream_id,
+            )
+            current_version = (await conn.execute(max_version_stmt)).scalar_one()
+
+            if expected_version is not None and current_version != expected_version:
+                raise OccError(stream_id, expected_version, current_version)
+
+            def _sanitize_for_json(obj: Any) -> Any:
+                if isinstance(obj, dict):
+                    return {k: _sanitize_for_json(v) for k, v in obj.items()}
+                elif isinstance(obj, (list, tuple)):
+                    return [_sanitize_for_json(v) for v in obj]
+                elif isinstance(obj, Decimal):
+                    return str(obj)
+                elif isinstance(obj, uuid.UUID):
+                    return str(obj)
+                return obj
+
+            rows = []
+            for idx, event in enumerate(events, start=1):
+                rows.append(
+                    {
+                        "id": uuid.uuid4(),
+                        "tenant_id": tenant_id,
+                        "stream_id": stream_id,
+                        "version": current_version + idx,
+                        "event_type": event.get("type"),
+                        "data": _sanitize_for_json(dict(event)),
+                    }
+                )
+            await conn.execute(sa.insert(event_store_events), rows)
+
+    async def read(self, tenant_id: str, stream_id: str) -> list[dict[str, Any]]:
+        stmt = (
+            sa.select(event_store_events.c.data)
+            .where(
+                event_store_events.c.tenant_id == tenant_id,
+                event_store_events.c.stream_id == stream_id,
+            )
+            .order_by(event_store_events.c.version.asc())
+        )
+        async with self._engine.connect() as conn:
+            result = await conn.execute(stmt)
+            return [row[0] for row in result.all()]