allowances 0.2.0__py3-none-any.whl

allowances/__init__.py

@@ -0,0 +1,86 @@
+"""
+allowances — grants and consumable budgets, enforced before the fact and auditable after it.
+
+The core is dependency-free and storage-agnostic: it does arithmetic against a
+:class:`~allowances.store.Store` you provide. ``import allowances`` never imports a web framework
+or a database driver.
+
+Most applications don't use this module directly — they install a backend
+(``pip install allowances[django]``) and call its shortcuts, which supply the store for you.
+"""
+
+from allowances.definitions import (
+    CurrencyDefinition,
+    CurrencySpec,
+    DefinitionProvider,
+    DictProvider,
+    FeatureDefinition,
+    FeatureSection,
+)
+from allowances.engine import (
+    archive_expired_wallets,
+    attach,
+    effective_balance,
+    find_unattached_fulfillment_records,
+    fulfill,
+    peek,
+    plan_switch,
+    unfulfill,
+)
+from allowances.errors import (
+    AllowancesError,
+    DefinitionNotFoundError,
+    InsufficientBalanceError,
+    RecordNotFoundError,
+    UnsupportedOperationError,
+)
+from allowances.store import Store
+from allowances.types import (
+    FulfillmentRecord,
+    FulfillmentResult,
+    Modifier,
+    ObjectRef,
+    SubjectRef,
+    Transaction,
+    TransactionKind,
+    Wallet,
+    WalletSpec,
+    WalletType,
+)
+from allowances.windows import window_start
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AllowancesError",
+    "CurrencyDefinition",
+    "CurrencySpec",
+    "DefinitionNotFoundError",
+    "DefinitionProvider",
+    "DictProvider",
+    "FeatureDefinition",
+    "FeatureSection",
+    "FulfillmentRecord",
+    "FulfillmentResult",
+    "InsufficientBalanceError",
+    "Modifier",
+    "ObjectRef",
+    "RecordNotFoundError",
+    "Store",
+    "SubjectRef",
+    "Transaction",
+    "TransactionKind",
+    "UnsupportedOperationError",
+    "Wallet",
+    "WalletSpec",
+    "WalletType",
+    "archive_expired_wallets",
+    "attach",
+    "effective_balance",
+    "find_unattached_fulfillment_records",
+    "fulfill",
+    "peek",
+    "plan_switch",
+    "unfulfill",
+    "window_start",
+]

allowances/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Storage backends shipped with the core. See ``docs/backends/`` for writing your own."""
+
+from allowances.backends.memory import MemoryStore
+
+__all__ = ["MemoryStore"]

allowances/backends/memory.py

@@ -0,0 +1,291 @@
+"""
+An in-memory :class:`~allowances.store.Store`.
+
+Two jobs. It makes the test suite fast — the engine's behaviour is arithmetic, and proving it
+doesn't need a database. And it keeps the port honest: every time the engine reaches for something
+only an ORM could do, this backend stops compiling, which is the signal that the abstraction leaked.
+
+Not for production. State lives in a dict, so it dies with the process and is invisible to every
+other one. Locking is a process-local ``RLock``, which is exactly as much concurrency control as a
+single-process test needs and no more.
+"""
+
+from __future__ import annotations
+
+import itertools
+import threading
+import uuid
+
+from contextlib import contextmanager
+from dataclasses import replace
+from datetime import datetime
+from decimal import Decimal
+from typing import Sequence
+
+from allowances.types import (
+    FulfillmentRecord,
+    Modifier,
+    ObjectRef,
+    SubjectRef,
+    Transaction,
+    TransactionKind,
+    Wallet,
+    WalletType,
+)
+from allowances.windows import utcnow
+
+
+class MemoryStore:
+    """A complete Store implementation over plain dicts."""
+
+    def __init__(self):
+        self._wallets: dict[int, Wallet] = {}
+        self._transactions: dict[int, Transaction] = {}
+        self._records: dict[uuid.UUID, FulfillmentRecord] = {}
+        self._modifiers: list[Modifier] = []
+        self.archived_wallets: list[Wallet] = []
+        self.archived_transactions: list[Transaction] = []
+
+        self._wallet_ids = itertools.count(1)
+        self._transaction_ids = itertools.count(1)
+        self._modifier_ids = itertools.count(1)
+        self._lock = threading.RLock()
+        self._depth = 0
+        # Distinguishes rows created within the same microsecond, so ordering stays deterministic
+        # on clocks too coarse to separate them.
+        self._sequence = itertools.count(1)
+        self._created_seq: dict[tuple[str, int], int] = {}
+
+    # -- transactions / locking ----------------------------------------------------------------
+
+    @contextmanager
+    def unit_of_work(self):
+        """
+        Atomic and re-entrant. The outermost block snapshots every collection and restores it if
+        anything raises; nested blocks join the outer one, exactly as a nested ``atomic()`` does.
+        """
+        self._lock.acquire()
+        self._depth += 1
+        snapshot = self._snapshot() if self._depth == 1 else None
+        try:
+            yield
+        except BaseException:
+            if snapshot is not None:
+                self._restore(snapshot)
+            raise
+        finally:
+            self._depth -= 1
+            self._lock.release()
+
+    def _snapshot(self):
+        # Every stored value is a frozen dataclass, so copying the containers is enough.
+        return (
+            dict(self._wallets),
+            dict(self._transactions),
+            dict(self._records),
+            list(self._modifiers),
+            list(self.archived_wallets),
+            list(self.archived_transactions),
+            dict(self._created_seq),
+        )
+
+    def _restore(self, snapshot):
+        (
+            self._wallets,
+            self._transactions,
+            self._records,
+            self._modifiers,
+            self.archived_wallets,
+            self.archived_transactions,
+            self._created_seq,
+        ) = snapshot
+
+    def _sort_key(self, kind: str, obj):
+        return (obj.created_at, self._created_seq.get((kind, obj.id), 0), obj.id)
+
+    # -- wallets -------------------------------------------------------------------------------
+
+    def find_wallets(
+        self,
+        *,
+        subjects: Sequence[SubjectRef],
+        wallet_types: Sequence[WalletType],
+        currencies: Sequence[str],
+        at: datetime,
+        lock: bool = False,
+    ) -> list[Wallet]:
+        subject_set = set(subjects)
+        type_set = {str(wallet_type) for wallet_type in wallet_types}
+        currency_set = set(currencies)
+        found = [
+            wallet
+            for wallet in self._wallets.values()
+            if wallet.subject in subject_set
+            and str(wallet.wallet_type) in type_set
+            and wallet.currency in currency_set
+            and wallet.is_valid_at(at)
+        ]
+        return sorted(found, key=lambda w: self._sort_key("wallet", w))
+
+    def get_wallet(self, wallet_id: object, *, lock: bool = False) -> Wallet | None:
+        return self._wallets.get(wallet_id)
+
+    def save_wallet(self, wallet: Wallet) -> None:
+        if wallet.id in self._wallets:
+            self._wallets[wallet.id] = wallet
+
+    def create_wallet(
+        self,
+        *,
+        subject: SubjectRef,
+        wallet_type: WalletType,
+        currency: str,
+        balance: Decimal,
+        overdraft_limit: Decimal | None = None,
+        reset_config: dict | None = None,
+        valid_from: datetime | None = None,
+        valid_until: datetime | None = None,
+    ) -> Wallet:
+        wallet = Wallet(
+            id=next(self._wallet_ids),
+            subject=subject,
+            wallet_type=WalletType(wallet_type),
+            currency=currency,
+            balance=Decimal(str(balance)),
+            created_at=utcnow(),
+            valid_from=valid_from,
+            valid_until=valid_until,
+            overdraft_limit=None if overdraft_limit is None else Decimal(str(overdraft_limit)),
+            reset_config=reset_config,
+        )
+        self._wallets[wallet.id] = wallet
+        self._created_seq[("wallet", wallet.id)] = next(self._sequence)
+        return wallet
+
+    def close_wallets(self, *, subject: SubjectRef, at: datetime) -> int:
+        closed = 0
+        for wallet_id, wallet in list(self._wallets.items()):
+            if wallet.subject == subject and wallet.is_valid_at(at):
+                self._wallets[wallet_id] = replace(wallet, valid_until=at)
+                closed += 1
+        return closed
+
+    def find_expired_wallets(self, *, at: datetime, lock: bool = False) -> list[Wallet]:
+        expired = [w for w in self._wallets.values() if w.valid_until is not None and w.valid_until <= at]
+        return sorted(expired, key=lambda w: self._sort_key("wallet", w))
+
+    def archive_wallet(self, wallet: Wallet) -> None:
+        stored = self._wallets.pop(wallet.id, None)
+        if stored is None:
+            return
+        self.archived_wallets.append(wallet)
+        for txn_id, txn in list(self._transactions.items()):
+            if txn.wallet_id == wallet.id:
+                self.archived_transactions.append(txn)
+                del self._transactions[txn_id]
+
+    # -- ledger --------------------------------------------------------------------------------
+
+    def sum_transactions(self, *, wallet_id: object, since: datetime, until: datetime) -> Decimal:
+        return sum(
+            (
+                t.amount
+                for t in self._transactions.values()
+                if t.wallet_id == wallet_id and since <= t.created_at <= until
+            ),
+            Decimal("0"),
+        )
+
+    def create_transaction(
+        self,
+        *,
+        wallet_id: object,
+        kind: TransactionKind,
+        amount: Decimal,
+        record_guid: uuid.UUID | None = None,
+        feature: str = "",
+        storno_of_id: object = None,
+        at: datetime | None = None,
+    ) -> Transaction:
+        if storno_of_id is not None and any(t.storno_of_id == storno_of_id for t in self._transactions.values()):
+            # The relational backends enforce this with a unique constraint; a lost race here would
+            # silently refund twice, so the in-memory one refuses just as loudly.
+            raise ValueError(f"Transaction {storno_of_id!r} has already been stornoed")
+        txn = Transaction(
+            id=next(self._transaction_ids),
+            wallet_id=wallet_id,
+            kind=TransactionKind(kind),
+            amount=Decimal(str(amount)),
+            created_at=at or utcnow(),
+            record_guid=record_guid,
+            feature=feature,
+            storno_of_id=storno_of_id,
+        )
+        self._transactions[txn.id] = txn
+        self._created_seq[("transaction", txn.id)] = next(self._sequence)
+        return txn
+
+    def transactions_for_record(self, *, record_guid: uuid.UUID, lock: bool = False) -> list[Transaction]:
+        found = [t for t in self._transactions.values() if t.record_guid == record_guid]
+        return sorted(found, key=lambda t: self._sort_key("transaction", t))
+
+    def attach_object(self, *, transaction_ids: Sequence[object], obj: ObjectRef) -> None:
+        for txn_id in transaction_ids:
+            txn = self._transactions.get(txn_id)
+            if txn is not None:
+                self._transactions[txn_id] = replace(txn, obj=obj)
+
+    # -- fulfillment records -------------------------------------------------------------------
+
+    def get_or_create_record(self, guid: uuid.UUID | None = None) -> FulfillmentRecord:
+        if guid is None:
+            guid = uuid.uuid4()
+        record = self._records.get(guid)
+        if record is None:
+            record = FulfillmentRecord(guid=guid, created_at=utcnow())
+            self._records[guid] = record
+        return record
+
+    def get_record(self, guid: uuid.UUID, *, lock: bool = False) -> FulfillmentRecord | None:
+        return self._records.get(guid)
+
+    def records_with_unattached_transactions(self, *, older_than: datetime | None = None) -> list[FulfillmentRecord]:
+        guids = {t.record_guid for t in self._transactions.values() if t.obj is None and t.record_guid is not None}
+        records = [self._records[g] for g in guids if g in self._records]
+        if older_than is not None:
+            records = [r for r in records if r.created_at <= older_than]
+        return sorted(records, key=lambda r: (r.created_at, str(r.guid)))
+
+    # -- modifiers -----------------------------------------------------------------------------
+
+    def add_modifier(
+        self,
+        *,
+        subject: SubjectRef,
+        feature: str,
+        factor: Decimal,
+        valid_from: datetime | None = None,
+        valid_until: datetime | None = None,
+    ) -> Modifier:
+        """Not part of the port — modifiers are seeded by an application, not by the engine."""
+        modifier = Modifier(
+            id=next(self._modifier_ids),
+            subject=subject,
+            feature=feature,
+            factor=Decimal(str(factor)),
+            valid_from=valid_from,
+            valid_until=valid_until,
+        )
+        self._modifiers.append(modifier)
+        return modifier
+
+    def find_modifier_factors(self, *, feature: str, subjects: Sequence[SubjectRef], at: datetime) -> list[Decimal]:
+        subject_set = set(subjects)
+        return [
+            m.factor
+            for m in self._modifiers
+            if m.feature == feature
+            and m.subject in subject_set
+            and (m.valid_from is None or m.valid_from <= at)
+            and (m.valid_until is None or m.valid_until >= at)
+        ]

allowances/definitions.py

@@ -0,0 +1,199 @@
+"""
+The definition layer: what rights *exist*, as opposed to what a subject currently *holds*.
+
+Definitions (features, currencies, conversion rates, fulfillment order) are configuration, not
+state — they are not rows in a database and they are not versioned per subject. The engine never
+reads them directly; it asks a :class:`DefinitionProvider`.
+
+:class:`DictProvider` reads them from a plain dict. The Django adapter subclasses it to read
+``settings.ALLOWANCES``. A remote licence server would be a third implementation, and the engine
+would not notice.
+"""
+
+from __future__ import annotations
+
+import abc
+import importlib
+
+from dataclasses import dataclass
+from decimal import Decimal
+
+from allowances.errors import DefinitionNotFoundError
+
+
+def import_string(dotted_path: str):
+    """
+    Import ``"package.module.attribute"`` and return the attribute.
+
+    A dependency-free equivalent of ``django.utils.module_loading.import_string`` — the core must
+    not import Django to resolve a ``fulfillment_order`` callable.
+    """
+    module_path, _, attr = dotted_path.rpartition(".")
+    if not module_path:
+        raise ImportError(f"{dotted_path!r} is not a dotted module path")
+    try:
+        return getattr(importlib.import_module(module_path), attr)
+    except AttributeError as exc:
+        raise ImportError(f"Module {module_path!r} has no attribute {attr!r}") from exc
+
+
+@dataclass(frozen=True)
+class CurrencyDefinition:
+    """
+    A named unit of entitlement.
+
+    ``general=True`` marks a fallback currency (e.g. ``credits``) that any feature accepting it may
+    draw from. ``round_fn`` decides how a fractional cost is turned into a whole unit —
+    ``"floor"``, ``"ceil"``, ``"round"``, or ``None`` to leave fractions alone.
+    """
+
+    name: str
+    general: bool = False
+    round_fn: str | None = None
+
+
+@dataclass(frozen=True)
+class CurrencySpec:
+    """
+    One entry in a feature section's ``currencies`` list: a currency plus its conversion rate
+    against the feature's own request unit. ``("credits", 0.5)`` means one unit of this feature
+    costs half a credit. A bare string means a rate of 1.
+    """
+
+    currency: str
+    rate: Decimal = Decimal("1")
+
+
+@dataclass(frozen=True)
+class FeatureSection:
+    """The ``grant`` or ``consumable`` half of a feature definition."""
+
+    currencies: tuple[CurrencySpec, ...]
+
+    def rate_for(self, currency: str) -> Decimal | None:
+        for spec in self.currencies:
+            if spec.currency == currency:
+                return spec.rate
+        return None
+
+    @property
+    def currency_names(self) -> tuple[str, ...]:
+        return tuple(spec.currency for spec in self.currencies)
+
+
+@dataclass(frozen=True)
+class FeatureDefinition:
+    """
+    A named capability: ``send_email``, ``coolant_fill``.
+
+    ``fulfillment_order`` is either a list of ``(wallet_type, subject_name)`` steps or a callable
+    that receives the candidate wallets and returns them in draw order. Note the callable receives
+    a ``list[Wallet]`` — plain value objects, not a database query — so the same ordering function
+    works against any backend.
+    """
+
+    name: str
+    grant: FeatureSection | None
+    consumable: FeatureSection | None
+    subjects: frozenset
+    fulfillment_order: object
+    overdraft: bool = False
+
+    def section_for(self, wallet_type: str) -> FeatureSection | None:
+        return self.grant if wallet_type == "grant" else self.consumable
+
+
+class DefinitionProvider(abc.ABC):
+    """Abstract source of feature and currency definitions."""
+
+    @abc.abstractmethod
+    def get_feature(self, name: str) -> FeatureDefinition: ...
+
+    @abc.abstractmethod
+    def get_currency(self, name: str) -> CurrencyDefinition: ...
+
+
+class DictProvider(DefinitionProvider):
+    """
+    Reads definitions from a dict of the shape::
+
+        {
+            "currencies": {
+                "email_send": {},
+                "credits": {"general": True, "round_fn": "ceil"},
+            },
+            "features": {
+                "send_email": {
+                    "grant": {"currencies": ["email_send"]},
+                    "consumable": {"currencies": ["email_send", ("credits", 0.5)]},
+                    "subjects": {"device", "team"},
+                    "fulfillment_order": [("grant", "device"), ("grant", None), "team"],
+                    "overdraft": False,
+                },
+            },
+        }
+    """
+
+    def __init__(self, config: dict | None = None):
+        self._config = config
+
+    @property
+    def config(self) -> dict:
+        return self._config if self._config is not None else {}
+
+    def get_feature(self, name: str) -> FeatureDefinition:
+        try:
+            raw = self.config["features"][name]
+        except KeyError:
+            raise DefinitionNotFoundError(f"Unknown feature: {name!r}") from None
+        return self._parse_feature(name, raw)
+
+    def get_currency(self, name: str) -> CurrencyDefinition:
+        try:
+            raw = self.config["currencies"][name]
+        except KeyError:
+            raise DefinitionNotFoundError(f"Unknown currency: {name!r}") from None
+        return CurrencyDefinition(
+            name=name,
+            general=bool(raw.get("general", False)),
+            round_fn=raw.get("round_fn"),
+        )
+
+    def _parse_feature(self, name: str, raw: dict) -> FeatureDefinition:
+        return FeatureDefinition(
+            name=name,
+            grant=self._parse_section(raw.get("grant")),
+            consumable=self._parse_section(raw.get("consumable")),
+            subjects=frozenset(raw.get("subjects", ())),
+            fulfillment_order=self._parse_fulfillment_order(raw.get("fulfillment_order", [])),
+            overdraft=bool(raw.get("overdraft", False)),
+        )
+
+    @staticmethod
+    def _parse_section(raw: dict | None) -> FeatureSection | None:
+        if raw is None:
+            return None
+        specs = []
+        for entry in raw.get("currencies", []):
+            if isinstance(entry, (tuple, list)):
+                currency, rate = entry
+                specs.append(CurrencySpec(currency=currency, rate=Decimal(str(rate))))
+            else:
+                specs.append(CurrencySpec(currency=entry, rate=Decimal("1")))
+        return FeatureSection(currencies=tuple(specs))
+
+    @staticmethod
+    def _parse_fulfillment_order(raw):
+        if callable(raw):
+            return raw
+        if isinstance(raw, str):
+            return import_string(raw)
+        parsed = []
+        for entry in raw:
+            if isinstance(entry, str):
+                # Shorthand: "team" means (None, "team") — any wallet type, that subject.
+                parsed.append((None, entry))
+            else:
+                wallet_type, subject = entry
+                parsed.append((wallet_type, subject))
+        return parsed