allowances 0.2.0__tar.gz → 0.3.0__tar.gz

{allowances-0.2.0 → allowances-0.3.0}/PKG-INFO

@@ -1,19 +1,17 @@
 Metadata-Version: 2.4
 Name: allowances
-Version: 0.2.0
+Version: 0.3.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
+License-Expression: MIT
+Requires-Dist: django>=5.2,<7 ; extra == 'django'
 Requires-Python: >=3.11
-Description-Content-Type: text/markdown
+Project-URL: Homepage, https://github.com/velis74/allowances
+Project-URL: Documentation, https://docs.velis.si/allowances
+Project-URL: Source, https://github.com/velis74/allowances
+Project-URL: Issues, https://github.com/velis74/allowances/issues
 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"
+Description-Content-Type: text/markdown
 
 # allowances
 
@@ -35,7 +33,7 @@ It is **not a payment system** — no invoices, no card charges, no money anywhe
 
 ## 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.
+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 seventeen-method port.
 
 ```bash
 pip install allowances            # the engine, zero dependencies
@@ -87,10 +85,10 @@ attach(result.guid, message)   # record what the quota bought
 
 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.
+The engine sits between them and knows nothing about either's storage. It receives definitions through a provider and state through a seventeen-method store port, which is why the same code runs against Postgres, SQLite or a dict.
 
 ```
-   allowances.engine        peek · fulfill · attach · unfulfill · plan_switch
+   allowances.engine        peek · fulfill · attach · unfulfill · credit · plan_switch
            │
    ┌───────┴────────┐
    ▼                ▼
@@ -118,15 +116,15 @@ Only the plumbing is missing, and `NEXT_STEPS.md` already scopes it: a grant-onl
 ## Development
 
 ```bash
-pip install -e ".[test]"
-pytest                                 # 188 tests, both stores, no setup
-ruff check . && ruff format --check .
+uv sync
+uv run pytest                          # both stores, no setup
+uv run ruff check . && uv run 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.
+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 uv run 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.
 

{allowances-0.2.0 → allowances-0.3.0}/README.md

@@ -18,7 +18,7 @@ It is **not a payment system** — no invoices, no card charges, no money anywhe
 
 ## 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.
+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 seventeen-method port.
 
 ```bash
 pip install allowances            # the engine, zero dependencies
@@ -70,10 +70,10 @@ attach(result.guid, message)   # record what the quota bought
 
 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.
+The engine sits between them and knows nothing about either's storage. It receives definitions through a provider and state through a seventeen-method store port, which is why the same code runs against Postgres, SQLite or a dict.
 
 ```
-   allowances.engine        peek · fulfill · attach · unfulfill · plan_switch
+   allowances.engine        peek · fulfill · attach · unfulfill · credit · plan_switch
            │
    ┌───────┴────────┐
    ▼                ▼
@@ -101,15 +101,15 @@ Only the plumbing is missing, and `NEXT_STEPS.md` already scopes it: a grant-onl
 ## Development
 
 ```bash
-pip install -e ".[test]"
-pytest                                 # 188 tests, both stores, no setup
-ruff check . && ruff format --check .
+uv sync
+uv run pytest                          # both stores, no setup
+uv run ruff check . && uv run 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.
+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 uv run 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.
 

{allowances-0.2.0 → allowances-0.3.0}/allowances/__init__.py

@@ -18,11 +18,16 @@ from allowances.definitions import (
     FeatureSection,
 )
 from allowances.engine import (
+    adjust_wallet,
     archive_expired_wallets,
     attach,
+    cancel_scheduled_switch,
+    consumed,
+    credit,
     effective_balance,
     find_unattached_fulfillment_records,
     fulfill,
+    open_wallet,
     peek,
     plan_switch,
     unfulfill,
@@ -32,7 +37,9 @@ from allowances.errors import (
     DefinitionNotFoundError,
     InsufficientBalanceError,
     RecordNotFoundError,
+    UnsuitableWalletError,
     UnsupportedOperationError,
+    WalletNotFoundError,
 )
 from allowances.store import Store
 from allowances.types import (
@@ -40,7 +47,9 @@ from allowances.types import (
     FulfillmentResult,
     Modifier,
     ObjectRef,
+    PLAN_SOURCE,
     SubjectRef,
+    SwitchPolicy,
     Transaction,
     TransactionKind,
     Wallet,
@@ -49,7 +58,7 @@ from allowances.types import (
 )
 from allowances.windows import window_start
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "AllowancesError",
@@ -65,20 +74,29 @@ __all__ = [
     "InsufficientBalanceError",
     "Modifier",
     "ObjectRef",
+    "PLAN_SOURCE",
     "RecordNotFoundError",
     "Store",
     "SubjectRef",
+    "SwitchPolicy",
     "Transaction",
     "TransactionKind",
+    "UnsuitableWalletError",
     "UnsupportedOperationError",
     "Wallet",
+    "WalletNotFoundError",
     "WalletSpec",
     "WalletType",
     "archive_expired_wallets",
+    "adjust_wallet",
     "attach",
+    "cancel_scheduled_switch",
+    "consumed",
+    "credit",
     "effective_balance",
     "find_unattached_fulfillment_records",
     "fulfill",
+    "open_wallet",
     "peek",
     "plan_switch",
     "unfulfill",

{allowances-0.2.0 → allowances-0.3.0}/allowances/backends/memory.py

@@ -26,6 +26,7 @@ from allowances.types import (
     FulfillmentRecord,
     Modifier,
     ObjectRef,
+    PLAN_SOURCE,
     SubjectRef,
     Transaction,
     TransactionKind,
@@ -110,19 +111,19 @@ class MemoryStore:
         *,
         subjects: Sequence[SubjectRef],
         wallet_types: Sequence[WalletType],
-        currencies: Sequence[str],
+        currencies: Sequence[str] | None,
         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)
+        currency_set = None if currencies is None else 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 (currency_set is None or wallet.currency in currency_set)
             and wallet.is_valid_at(at)
         ]
         return sorted(found, key=lambda w: self._sort_key("wallet", w))
@@ -145,6 +146,9 @@ class MemoryStore:
         reset_config: dict | None = None,
         valid_from: datetime | None = None,
         valid_until: datetime | None = None,
+        source: str = PLAN_SOURCE,
+        allotment: Decimal | None = None,
+        scheduled: dict | None = None,
     ) -> Wallet:
         wallet = Wallet(
             id=next(self._wallet_ids),
@@ -157,18 +161,17 @@ class MemoryStore:
             valid_until=valid_until,
             overdraft_limit=None if overdraft_limit is None else Decimal(str(overdraft_limit)),
             reset_config=reset_config,
+            source=source,
+            allotment=None if allotment is None else Decimal(str(allotment)),
+            scheduled=scheduled,
         )
         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_scheduled_wallets(self, *, subject: SubjectRef, lock: bool = False) -> list[Wallet]:
+        found = [w for w in self._wallets.values() if w.subject == subject and w.scheduled]
+        return sorted(found, key=lambda w: self._sort_key("wallet", w))
 
     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]
@@ -196,6 +199,10 @@ class MemoryStore:
             Decimal("0"),
         )
 
+    def transactions_for_wallet(self, *, wallet_id: object, since: datetime, until: datetime) -> list[Transaction]:
+        found = [t for t in self._transactions.values() if t.wallet_id == wallet_id and since <= t.created_at <= until]
+        return sorted(found, key=lambda t: self._sort_key("transaction", t))
+
     def create_transaction(
         self,
         *,

{allowances-0.2.0 → allowances-0.3.0}/allowances/definitions.py

@@ -86,8 +86,9 @@ 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
+    ``fulfillment_order`` is either a list of ``(wallet_type, subject_name, source)`` steps or a
+    callable that receives the candidate wallets and returns them in draw order. A ``source`` of
+    ``None`` matches wallets of every source. Note the callable receives
     a ``list[Wallet]`` — plain value objects, not a database query — so the same ordering function
     works against any backend.
     """
@@ -127,7 +128,12 @@ class DictProvider(DefinitionProvider):
                     "grant": {"currencies": ["email_send"]},
                     "consumable": {"currencies": ["email_send", ("credits", 0.5)]},
                     "subjects": {"device", "team"},
-                    "fulfillment_order": [("grant", "device"), ("grant", None), "team"],
+                    "fulfillment_order": [
+                        ("grant", "device"),
+                        ("grant", None),
+                        ("consumable", "team", "plan"),
+                        "team",
+                    ],
                     "overdraft": False,
                 },
             },
@@ -191,9 +197,12 @@ class DictProvider(DefinitionProvider):
         parsed = []
         for entry in raw:
             if isinstance(entry, str):
-                # Shorthand: "team" means (None, "team") — any wallet type, that subject.
-                parsed.append((None, entry))
-            else:
+                # Shorthand: "team" means (None, "team", None) — any wallet type and source, that subject.
+                parsed.append((None, entry, None))
+            elif len(entry) == 2:
                 wallet_type, subject = entry
-                parsed.append((wallet_type, subject))
+                parsed.append((wallet_type, subject, None))
+            else:
+                wallet_type, subject, source = entry
+                parsed.append((wallet_type, subject, source))
         return parsed