resourcecap 0.2.1__tar.gz → 0.2.3__tar.gz

{resourcecap-0.2.1 → resourcecap-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: resourcecap
-Version: 0.2.1
+Version: 0.2.3
 Summary: A python package to limit the resource usage of any program
 Author: purushottam-dafure
 Author-email: purushottam-dafure <purushottamdafure@gmail.com>
@@ -97,6 +97,24 @@ Each call to `foo()` logs something like:
 the above code will stop execution at that point and raise BudgetExhaustedError,
 after the 4th call to `foo()` pushes the spend from 30 to 40.
 
+`BudgetExhaustedError` carries structured fields, not just a message, so you
+can handle it programmatically without parsing text:
+
+```python
+try:
+    with Budget(amount = 30):
+        [foo() for i in range(5)]
+except BudgetExhaustedError as e:
+    print(e.resource, e.limit, e.spent)  # "cost" 30 40.0
+```
+
+A `Budget` instance can be reused across separate, non-overlapping `with`
+blocks (its spend resets each time), but it can't be open twice at once —
+entering it while it's already open, from a concurrent task/thread or
+otherwise, raises `BudgetReentryError`. If you need several concurrent
+pieces of work to share one budget, open it once around all of them; if
+each needs independent tracking, give each its own `Budget` instance.
+
 ## Multiple resources
 
 `amount` on `costs`/`Budget` tracks a single, default resource. To track

{resourcecap-0.2.1 → resourcecap-0.2.3}/README.md

@@ -83,6 +83,24 @@ Each call to `foo()` logs something like:
 the above code will stop execution at that point and raise BudgetExhaustedError,
 after the 4th call to `foo()` pushes the spend from 30 to 40.
 
+`BudgetExhaustedError` carries structured fields, not just a message, so you
+can handle it programmatically without parsing text:
+
+```python
+try:
+    with Budget(amount = 30):
+        [foo() for i in range(5)]
+except BudgetExhaustedError as e:
+    print(e.resource, e.limit, e.spent)  # "cost" 30 40.0
+```
+
+A `Budget` instance can be reused across separate, non-overlapping `with`
+blocks (its spend resets each time), but it can't be open twice at once —
+entering it while it's already open, from a concurrent task/thread or
+otherwise, raises `BudgetReentryError`. If you need several concurrent
+pieces of work to share one budget, open it once around all of them; if
+each needs independent tracking, give each its own `Budget` instance.
+
 ## Multiple resources
 
 `amount` on `costs`/`Budget` tracks a single, default resource. To track

{resourcecap-0.2.1 → resourcecap-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "resourcecap"
-version = "0.2.1"
+version = "0.2.3"
 description = "A python package to limit the resource usage of any program"
 readme = "README.md"
 license = "MIT"

{resourcecap-0.2.1 → resourcecap-0.2.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "resourcecap"
-version = "0.2.1"
+version = "0.2.3"
 description = "A python package to limit the resource usage of any program"
 readme = "README.md"
 license = "MIT"

resourcecap-0.2.3/src/resourcecap/__init__.py

@@ -0,0 +1,5 @@
+from ._budget import Budget, BudgetExhaustedError, BudgetReentryError
+from ._costs import costs
+from ._resources import Spendable
+
+__all__ = ["Budget", "BudgetExhaustedError", "BudgetReentryError", "Spendable", "costs"]

{resourcecap-0.2.1 → resourcecap-0.2.3}/src/resourcecap/_budget.py

@@ -11,7 +11,31 @@ logger = logging.getLogger("resourcecap")
 
 
 class BudgetExhaustedError(Exception):
-    """Raised when a `Budget`'s limit for some resource is exceeded."""
+    """Raised when a `Budget`'s limit for some resource is exceeded.
+
+    Attributes:
+        resource: the key of the resource whose limit was exceeded.
+        limit: that resource's limit.
+        spent: how much had been spent when the limit was exceeded.
+    """
+
+    def __init__(self, resource: Hashable, limit: float, spent: float) -> None:
+        super().__init__(f"budget for resource {resource!r} of {limit} exhausted: spent {spent}")
+        self.resource = resource
+        self.limit = limit
+        self.spent = spent
+
+
+class BudgetReentryError(RuntimeError):
+    """Raised when a `Budget` is entered while it's already open.
+
+    A single `Budget` instance isn't safe to have open twice at once —
+    whether that's one task/thread re-entering it while still inside an
+    outer block on the same instance, or two concurrent tasks/threads
+    each entering it independently. Either enter it once around the
+    concurrent work (so everything inside shares that one open block),
+    or create a separate `Budget` instance per concurrent call.
+    """
 
 
 class Budget:
@@ -30,7 +54,9 @@ class Budget:
     that limit before the decorated call runs rather than after.
 
     Each resource's spend resets to zero every time the block is
-    entered, so a `Budget` instance can be reused across separate blocks.
+    entered, so a `Budget` instance can be reused across separate,
+    non-overlapping blocks. It is **not** safe to have the same
+    instance open twice at once — see `BudgetReentryError`.
     """
 
     def __init__(
@@ -41,7 +67,7 @@ class Budget:
         self.limits = merge_resources(amount, limits)
         self.spent: dict[Hashable, float] = {}
         self._lock = threading.Lock()
-        self._token: contextvars.Token[tuple[_tracking._Chargeable, ...]] | None = None
+        self._token: contextvars.Token[tuple[Budget, ...]] | None = None
 
     def exhausts_at_start(self, key: Hashable) -> bool:
         """Whether `key`'s limit should be enforced before the call runs."""
@@ -86,14 +112,18 @@ class Budget:
                     "resource=%s limit=%s exhausted: spent=%s", key, limit.amount, spent
                 )
             else:
-                raise BudgetExhaustedError(
-                    f"budget for resource {key!r} of {limit.amount} exhausted: spent {spent}"
-                )
+                raise BudgetExhaustedError(key, limit.amount, spent)
 
     def __enter__(self) -> "Budget":
         with self._lock:
+            if self._token is not None:
+                raise BudgetReentryError(
+                    "this Budget is already open: a Budget instance can't be entered "
+                    "while it's still open elsewhere. Enter it once around the "
+                    "concurrent work, or use a separate Budget per concurrent call."
+                )
             self.spent = {}
-        self._token = _tracking.push(self)
+            self._token = _tracking.push(self)
         return self
 
     def __exit__(
@@ -102,9 +132,10 @@ class Budget:
         exc: BaseException | None,
         tb: TracebackType | None,
     ) -> None:
-        assert self._token is not None
-        _tracking.pop(self._token)
-        self._token = None
+        with self._lock:
+            assert self._token is not None
+            _tracking.pop(self._token)
+            self._token = None
 
     async def __aenter__(self) -> "Budget":
         return self.__enter__()

{resourcecap-0.2.1 → resourcecap-0.2.3}/src/resourcecap/_costs.py

@@ -85,9 +85,7 @@ def costs[**P, R](
                     resolved.amount,
                     total,
                 )
-                _tracking.charge_active_budgets_after(
-                    key, resolved.amount, partial_amounts.get(key, 0.0)
-                )
+                _tracking.charge_active_budgets_after(key, resolved.amount, partial_amounts[key])
 
         if inspect.iscoroutinefunction(func):
             async_func = cast(Callable[P, Awaitable[R]], func)

{resourcecap-0.2.1 → resourcecap-0.2.3}/src/resourcecap/_resources.py

@@ -64,6 +64,9 @@ class Spendable:
     def coerce(cls, value: "float | Spendable") -> "Spendable":
         return value if isinstance(value, Spendable) else cls(value)
 
+    def _with_amount(self, amount: float) -> "Spendable":
+        return Spendable(amount, warn_only=self.warn_only, exhaust_at_start=self.exhaust_at_start)
+
     def resolve(
         self, args: tuple[Any, ...], kwargs: dict[str, Any], result: Any  # noqa: ANN401
     ) -> "Spendable":
@@ -80,7 +83,7 @@ class Spendable:
             total += self.from_args(*args, **kwargs)
         if self.from_result is not None:
             total += self.from_result(result)
-        return Spendable(total, warn_only=self.warn_only, exhaust_at_start=self.exhaust_at_start)
+        return self._with_amount(total)
 
     def resolve_partial(self, args: tuple[Any, ...], kwargs: dict[str, Any]) -> "Spendable":
         """Like `resolve`, but only the static `amount` and `from_args`.
@@ -91,11 +94,7 @@ class Spendable:
         if self.from_args is None:
             return self
 
-        return Spendable(
-            self.amount + self.from_args(*args, **kwargs),
-            warn_only=self.warn_only,
-            exhaust_at_start=self.exhaust_at_start,
-        )
+        return self._with_amount(self.amount + self.from_args(*args, **kwargs))
 
 
 def merge_resources(

{resourcecap-0.2.1 → resourcecap-0.2.3}/src/resourcecap/_tracking.py

@@ -1,32 +1,26 @@
+from __future__ import annotations
+
 import contextvars
 from collections.abc import Hashable
-from typing import Protocol
-
-
-class _Chargeable(Protocol):
-    def exhausts_at_start(self, key: Hashable) -> bool: ...
+from typing import TYPE_CHECKING
 
-    def charge(self, key: Hashable, amount: float) -> None: ...
+if TYPE_CHECKING:
+    from ._budget import Budget
 
 
-_active_budgets: contextvars.ContextVar[tuple[_Chargeable, ...]] = contextvars.ContextVar(
+_active_budgets: contextvars.ContextVar[tuple[Budget, ...]] = contextvars.ContextVar(
     "resourcecap_active_budgets", default=()
 )
 
 
-def push(budget: _Chargeable) -> contextvars.Token[tuple[_Chargeable, ...]]:
+def push(budget: Budget) -> contextvars.Token[tuple[Budget, ...]]:
     return _active_budgets.set((*_active_budgets.get(), budget))
 
 
-def pop(token: contextvars.Token[tuple[_Chargeable, ...]]) -> None:
+def pop(token: contextvars.Token[tuple[Budget, ...]]) -> None:
     _active_budgets.reset(token)
 
 
-def charge_active_budgets(key: Hashable, amount: float) -> None:
-    for budget in _active_budgets.get():
-        budget.charge(key, amount)
-
-
 def charge_active_budgets_at_start(key: Hashable, partial_amount: float) -> None:
     if not partial_amount:
         return

resourcecap-0.2.1/src/resourcecap/__init__.py

@@ -1,5 +0,0 @@
-from ._budget import Budget, BudgetExhaustedError
-from ._costs import costs
-from ._resources import Spendable
-
-__all__ = ["Budget", "BudgetExhaustedError", "Spendable", "costs"]