allowances 0.2.0__tar.gz

allowances-0.2.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: allowances
+Version: 0.2.0
+Summary: Grants and consumable budgets — enforced before the fact, auditable after it. Storage-agnostic, with a Django backend.
+License-Expression: MIT
+Keywords: licensing,entitlements,quota,metering,billing,ledger,django
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: django
+Requires-Dist: Django<7,>=5.2; extra == "django"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-django; extra == "test"
+Requires-Dist: psycopg2-binary; extra == "test"
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: Django<7,>=5.2; extra == "test"
+
+# allowances
+
+Grants and consumable budgets — enforced before the fact, auditable after it. Storage-agnostic, with a Django backend.
+
+📖 **Documentation:** [docs.velis.si/allowances](https://docs.velis.si/allowances). The source lives in `docs/` — `npm install && npm run docs:dev` serves it locally.
+
+---
+
+## What it does
+
+Applications keep needing to answer the same shape of question:
+
+> Can this user send an email right now? How many API calls does this organisation have left this month? Does this device still have a service contract, and does the customer have enough coolant credit to fill it?
+
+`allowances` answers it, records what the answer cost, and lets you take it back if the operation it paid for never happened.
+
+It is **not a payment system** — no invoices, no card charges, no money anywhere. The units it counts are whatever you say they are. Use it for rights that are bought, expire, or get spent.
+
+## Install
+
+Django is optional. The core is `import allowances` and depends on nothing at all — not Django, not a database driver, not anything outside the standard library. Everything that matters (the ordering walk, conversion, rounding, overdraft, sliding windows) lives there, and talks to storage through a sixteen-method port.
+
+```bash
+pip install allowances            # the engine, zero dependencies
+pip install "allowances[django]"  # ...and the Django models, store and admin
+```
+
+The Django binding is one extra line, and the rest of this README assumes you took it:
+
+```python
+INSTALLED_APPS = ["allowances_django"]
+```
+
+Without it you supply your own `Store` — a dict-backed one ships in the box for tests, and [writing another](https://docs.velis.si/allowances/backends/writing-a-backend) is an afternoon.
+
+## Use
+
+```python
+# settings.py
+ALLOWANCES = {
+    "currencies": {
+        "email_send": {},
+        "credits": {"general": True, "round_fn": "ceil"},
+    },
+    "features": {
+        "send_email": {
+            "consumable": {"currencies": ["email_send", ("credits", 0.5)]},
+            "subjects": {"user", "team"},
+            "fulfillment_order": [("consumable", "user"), ("consumable", "team")],
+        },
+    },
+}
+```
+
+```python
+from allowances import InsufficientBalanceError
+from allowances_django.shortcuts import fulfill, attach, unfulfill
+
+try:
+    result = fulfill("send_email", 1, {"user": request.user, "team": team})
+except InsufficientBalanceError as exc:
+    return http_402(f"Only {exc.result.granted} left")
+
+message = send_the_email()
+attach(result.guid, message)   # record what the quota bought
+# ...or unfulfill(result.guid) if it failed
+```
+
+## The shape of it
+
+Two layers, kept apart. **Definition** — what rights exist at all: features, currencies, conversion rates, priority order. Configuration, not rows. **State** — what a subject holds and has spent: wallets and a transaction ledger.
+
+The engine sits between them and knows nothing about either's storage. It receives definitions through a provider and state through a sixteen-method store port, which is why the same code runs against Postgres, SQLite or a dict.
+
+```
+   allowances.engine        peek · fulfill · attach · unfulfill · plan_switch
+           │
+   ┌───────┴────────┐
+   ▼                ▼
+Store port   DefinitionProvider
+   │                │
+   ▼                ▼
+DjangoStore    SettingsProvider
+MemoryStore    DictProvider
+```
+
+Highlights:
+
+- **Grants and consumables in one flow.** A boolean entitlement and a metered budget resolve together, in an order you declare.
+- **Multi-source payment.** One operation can draw from a dedicated budget, then general credits, then a promotional grant, at conversion rates you set.
+- **Nothing edited in place.** Consumption writes a ledger entry; reversal writes a matching storno; spent-out wallets move to an archive.
+- **Sliding windows without a reset job.** "200 a day" works by ageing consumption out of a window, not by a nightly job that can fail.
+- **Multi-subject.** A licence can belong to a user, an organisation, a device, a location — resolved across all of them in one call.
+
+## What it could also be
+
+A permissions layer, if you push it. Not the point of the library, but the pieces line up: a grant with no expiry *is* a permission bit, the fulfillment order *is* a resolution order across user, team and organisation, and the ledger is the audit trail permission systems usually bolt on afterwards. You get things they rarely offer natively — rights that expire on a date, that may be exercised *n* times, or that are inherited from an organisation and revoked with it.
+
+Only the plumbing is missing, and `NEXT_STEPS.md` already scopes it: a grant-only permissions backend, after which the decorators, mixins and checks you have already written keep working unchanged. See [the guide](https://docs.velis.si/allowances/guide/).
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest                                 # 188 tests, both stores, no setup
+ruff check . && ruff format --check .
+
+npm install
+npm run docs:dev
+```
+
+No database server required: the suite defaults to a file-backed SQLite. Copy `tests/env.example.py` to `tests/env.py` to point it at a local Postgres instead, and `ALLOWANCES_TEST_DB=sqlite pytest` to go back. Both engines are supported and both are covered — including `tests/django/test_concurrency.py`, which races eight threads for the same wallet and insists it is granted exactly once.
+
+Locally that runs against whichever Django you have installed. CI runs the suite five times — Django 5.2 on Python 3.11, 6.0 on 3.12 and 6.1 on 3.13 against Postgres, plus each end of that range against SQLite — which is what the `Django>=5.2,<7` pin is based on.
+
+`DECISIONS.md` records every judgment call and what it would cost to revisit — read it before changing behaviour.
+
+## Licence
+
+MIT.

allowances-0.2.0/README.md

@@ -0,0 +1,120 @@
+# allowances
+
+Grants and consumable budgets — enforced before the fact, auditable after it. Storage-agnostic, with a Django backend.
+
+📖 **Documentation:** [docs.velis.si/allowances](https://docs.velis.si/allowances). The source lives in `docs/` — `npm install && npm run docs:dev` serves it locally.
+
+---
+
+## What it does
+
+Applications keep needing to answer the same shape of question:
+
+> Can this user send an email right now? How many API calls does this organisation have left this month? Does this device still have a service contract, and does the customer have enough coolant credit to fill it?
+
+`allowances` answers it, records what the answer cost, and lets you take it back if the operation it paid for never happened.
+
+It is **not a payment system** — no invoices, no card charges, no money anywhere. The units it counts are whatever you say they are. Use it for rights that are bought, expire, or get spent.
+
+## Install
+
+Django is optional. The core is `import allowances` and depends on nothing at all — not Django, not a database driver, not anything outside the standard library. Everything that matters (the ordering walk, conversion, rounding, overdraft, sliding windows) lives there, and talks to storage through a sixteen-method port.
+
+```bash
+pip install allowances            # the engine, zero dependencies
+pip install "allowances[django]"  # ...and the Django models, store and admin
+```
+
+The Django binding is one extra line, and the rest of this README assumes you took it:
+
+```python
+INSTALLED_APPS = ["allowances_django"]
+```
+
+Without it you supply your own `Store` — a dict-backed one ships in the box for tests, and [writing another](https://docs.velis.si/allowances/backends/writing-a-backend) is an afternoon.
+
+## Use
+
+```python
+# settings.py
+ALLOWANCES = {
+    "currencies": {
+        "email_send": {},
+        "credits": {"general": True, "round_fn": "ceil"},
+    },
+    "features": {
+        "send_email": {
+            "consumable": {"currencies": ["email_send", ("credits", 0.5)]},
+            "subjects": {"user", "team"},
+            "fulfillment_order": [("consumable", "user"), ("consumable", "team")],
+        },
+    },
+}
+```
+
+```python
+from allowances import InsufficientBalanceError
+from allowances_django.shortcuts import fulfill, attach, unfulfill
+
+try:
+    result = fulfill("send_email", 1, {"user": request.user, "team": team})
+except InsufficientBalanceError as exc:
+    return http_402(f"Only {exc.result.granted} left")
+
+message = send_the_email()
+attach(result.guid, message)   # record what the quota bought
+# ...or unfulfill(result.guid) if it failed
+```
+
+## The shape of it
+
+Two layers, kept apart. **Definition** — what rights exist at all: features, currencies, conversion rates, priority order. Configuration, not rows. **State** — what a subject holds and has spent: wallets and a transaction ledger.
+
+The engine sits between them and knows nothing about either's storage. It receives definitions through a provider and state through a sixteen-method store port, which is why the same code runs against Postgres, SQLite or a dict.
+
+```
+   allowances.engine        peek · fulfill · attach · unfulfill · plan_switch
+           │
+   ┌───────┴────────┐
+   ▼                ▼
+Store port   DefinitionProvider
+   │                │
+   ▼                ▼
+DjangoStore    SettingsProvider
+MemoryStore    DictProvider
+```
+
+Highlights:
+
+- **Grants and consumables in one flow.** A boolean entitlement and a metered budget resolve together, in an order you declare.
+- **Multi-source payment.** One operation can draw from a dedicated budget, then general credits, then a promotional grant, at conversion rates you set.
+- **Nothing edited in place.** Consumption writes a ledger entry; reversal writes a matching storno; spent-out wallets move to an archive.
+- **Sliding windows without a reset job.** "200 a day" works by ageing consumption out of a window, not by a nightly job that can fail.
+- **Multi-subject.** A licence can belong to a user, an organisation, a device, a location — resolved across all of them in one call.
+
+## What it could also be
+
+A permissions layer, if you push it. Not the point of the library, but the pieces line up: a grant with no expiry *is* a permission bit, the fulfillment order *is* a resolution order across user, team and organisation, and the ledger is the audit trail permission systems usually bolt on afterwards. You get things they rarely offer natively — rights that expire on a date, that may be exercised *n* times, or that are inherited from an organisation and revoked with it.
+
+Only the plumbing is missing, and `NEXT_STEPS.md` already scopes it: a grant-only permissions backend, after which the decorators, mixins and checks you have already written keep working unchanged. See [the guide](https://docs.velis.si/allowances/guide/).
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest                                 # 188 tests, both stores, no setup
+ruff check . && ruff format --check .
+
+npm install
+npm run docs:dev
+```
+
+No database server required: the suite defaults to a file-backed SQLite. Copy `tests/env.example.py` to `tests/env.py` to point it at a local Postgres instead, and `ALLOWANCES_TEST_DB=sqlite pytest` to go back. Both engines are supported and both are covered — including `tests/django/test_concurrency.py`, which races eight threads for the same wallet and insists it is granted exactly once.
+
+Locally that runs against whichever Django you have installed. CI runs the suite five times — Django 5.2 on Python 3.11, 6.0 on 3.12 and 6.1 on 3.13 against Postgres, plus each end of that range against SQLite — which is what the `Django>=5.2,<7` pin is based on.
+
+`DECISIONS.md` records every judgment call and what it would cost to revisit — read it before changing behaviour.
+
+## Licence
+
+MIT.

allowances-0.2.0/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-0.2.0/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-0.2.0/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)
+        ]