ddutils 0.2.0__tar.gz → 0.2.1__tar.gz

ddutils-0.2.0/README.md → ddutils-0.2.1/PKG-INFO

@@ -1,3 +1,21 @@
+Metadata-Version: 2.4
+Name: ddutils
+Version: 0.2.1
+Summary: Domain Driven Utils Library
+Keywords: python,ddutils
+Author: davyddd
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11, <3.15
+Project-URL: Repository, https://github.com/davyddd/ddutils
+Description-Content-Type: text/markdown
+
 # DDUtils
 
 [![pypi](https://img.shields.io/pypi/v/ddutils.svg)](https://pypi.python.org/pypi/ddutils)
@@ -321,9 +339,8 @@ A registry that keeps one object instance per scope and manages its lifetime.
 
 ### ScopedRegistry
 
-Keeps one object per scope. The scope key comes from `scope_func`, for example `asyncio.current_task`
-(one object per task), `os.getpid` (one per process) or a `ContextVar` getter (one per request, inherited
-by the tasks spawned inside it).
+Keeps one object per scope. `scope_func` decides what the current scope is and returns its key; `None` means
+"no current scope" and makes every method raise `RuntimeError`.
 
 `scope()` is the entry point into a scope: it creates the object on enter and removes it on exit, calling
 the optional destructor exactly once. Nested `scope()` blocks join the existing object and leave it alone.
@@ -331,7 +348,6 @@ Concurrent first accesses with the same key call `create_func` only once.
 
 ```python
 import asyncio
-from contextvars import ContextVar
 
 from ddutils.scoped_registry import ScopedRegistry
 
@@ -348,32 +364,53 @@ async def handle_request():
         await session.execute('select ...')
         async with session_registry.scope() as same_session:  # nested block joins
             ...
+```
+
+Lower-level methods are available when a context manager does not fit:
+
+- `get()` returns the current object or `None`;
+- `set(**kwargs)` returns the existing object or creates it. Whoever calls it takes over the cleanup that
+  `scope()` does on exit and must call `clear()` when the object is no longer needed, if it ever is: a
+  per-process client may live until the process ends;
+- `clear()` removes the object of the current scope and calls the destructor.
+
+#### Scopes kept in a ContextVar
+
+A `scope_func` that declares a `token` parameter receives a freshly generated token when `scope()` is entered
+and `None` on every other access. This is for a scope of one execution (an HTTP request, an actor run) rather
+than one task: the function stores the token in a `ContextVar`, so coroutines spawned inside the block
+(`gather`, `TaskGroup`, `create_task`) inherit it and share the object with the parent, while outside of
+`scope()` there is no key and every method raises.
+
+```python
+from contextvars import ContextVar
+
+execution_key: ContextVar[str | None] = ContextVar('execution_key', default=None)
+
+
+def execution_scope(token: str | None) -> str | None:
+    key = execution_key.get()
+    if key is None and token is not None:  # entering scope() outside of an execution: start one
+        execution_key.set(token)
+        key = token
+    return key
 
 
 async def create_log_properties(**kwargs): ...
 
 
-# One object per request: the key lives in a ContextVar set by the middleware, child tasks inherit it
-request_key: ContextVar[object | None] = ContextVar('request_key', default=None)
-log_registry = ScopedRegistry(create_func=create_log_properties, scope_func=request_key.get)
+log_registry = ScopedRegistry(create_func=create_log_properties, scope_func=execution_scope)
 
 
 async def middleware(headers):
-    token = request_key.set(object())
-    try:
-        async with log_registry.scope(headers=headers) as log_properties:
-            await asyncio.gather(work(), work())  # both see the same log_properties via log_registry.get()
-    finally:
-        request_key.reset(token)
+    async with log_registry.scope(headers=headers) as log_properties:
+        await asyncio.gather(work(), work())  # both see the same log_properties via log_registry.get()
 ```
 
-Lower-level methods are available when a context manager does not fit:
-
-- `get()` returns the current object or `None`;
-- `set(**kwargs)` returns the existing object or creates it;
-- `clear()` removes the object of the current scope and calls the destructor.
-
-`scope_func` must return a hashable key; if it returns `None` or an unhashable value, every method raises `RuntimeError`.
+Reads never start a scope: a `get()` from a long-living context (a startup log in the server's main task)
+that planted a key would be inherited by every request task, making all requests share one object. For the
+same reason the key is not reset when the block ends, so `scope()` must be entered in a task that does not
+outlive the block (a request handler, an actor run).
 
 ## Function Exception Extraction
 

ddutils-0.2.0/PKG-INFO → ddutils-0.2.1/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: ddutils
-Version: 0.2.0
-Summary: Domain Driven Utils Library
-Keywords: python,ddutils
-Author: davyddd
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.11, <3.15
-Project-URL: Repository, https://github.com/davyddd/ddutils
-Description-Content-Type: text/markdown
-
 # DDUtils
 
 [![pypi](https://img.shields.io/pypi/v/ddutils.svg)](https://pypi.python.org/pypi/ddutils)
@@ -333,9 +321,8 @@ A registry that keeps one object instance per scope and manages its lifetime.
 
 ### ScopedRegistry
 
-Keeps one object per scope. The scope key comes from `scope_func`, for example `asyncio.current_task`
-(one object per task), `os.getpid` (one per process) or a `ContextVar` getter (one per request, inherited
-by the tasks spawned inside it).
+Keeps one object per scope. `scope_func` decides what the current scope is and returns its key; `None` means
+"no current scope" and makes every method raise `RuntimeError`.
 
 `scope()` is the entry point into a scope: it creates the object on enter and removes it on exit, calling
 the optional destructor exactly once. Nested `scope()` blocks join the existing object and leave it alone.
@@ -343,7 +330,6 @@ Concurrent first accesses with the same key call `create_func` only once.
 
 ```python
 import asyncio
-from contextvars import ContextVar
 
 from ddutils.scoped_registry import ScopedRegistry
 
@@ -360,32 +346,53 @@ async def handle_request():
         await session.execute('select ...')
         async with session_registry.scope() as same_session:  # nested block joins
             ...
+```
+
+Lower-level methods are available when a context manager does not fit:
+
+- `get()` returns the current object or `None`;
+- `set(**kwargs)` returns the existing object or creates it. Whoever calls it takes over the cleanup that
+  `scope()` does on exit and must call `clear()` when the object is no longer needed, if it ever is: a
+  per-process client may live until the process ends;
+- `clear()` removes the object of the current scope and calls the destructor.
+
+#### Scopes kept in a ContextVar
+
+A `scope_func` that declares a `token` parameter receives a freshly generated token when `scope()` is entered
+and `None` on every other access. This is for a scope of one execution (an HTTP request, an actor run) rather
+than one task: the function stores the token in a `ContextVar`, so coroutines spawned inside the block
+(`gather`, `TaskGroup`, `create_task`) inherit it and share the object with the parent, while outside of
+`scope()` there is no key and every method raises.
+
+```python
+from contextvars import ContextVar
+
+execution_key: ContextVar[str | None] = ContextVar('execution_key', default=None)
+
+
+def execution_scope(token: str | None) -> str | None:
+    key = execution_key.get()
+    if key is None and token is not None:  # entering scope() outside of an execution: start one
+        execution_key.set(token)
+        key = token
+    return key
 
 
 async def create_log_properties(**kwargs): ...
 
 
-# One object per request: the key lives in a ContextVar set by the middleware, child tasks inherit it
-request_key: ContextVar[object | None] = ContextVar('request_key', default=None)
-log_registry = ScopedRegistry(create_func=create_log_properties, scope_func=request_key.get)
+log_registry = ScopedRegistry(create_func=create_log_properties, scope_func=execution_scope)
 
 
 async def middleware(headers):
-    token = request_key.set(object())
-    try:
-        async with log_registry.scope(headers=headers) as log_properties:
-            await asyncio.gather(work(), work())  # both see the same log_properties via log_registry.get()
-    finally:
-        request_key.reset(token)
+    async with log_registry.scope(headers=headers) as log_properties:
+        await asyncio.gather(work(), work())  # both see the same log_properties via log_registry.get()
 ```
 
-Lower-level methods are available when a context manager does not fit:
-
-- `get()` returns the current object or `None`;
-- `set(**kwargs)` returns the existing object or creates it;
-- `clear()` removes the object of the current scope and calls the destructor.
-
-`scope_func` must return a hashable key; if it returns `None` or an unhashable value, every method raises `RuntimeError`.
+Reads never start a scope: a `get()` from a long-living context (a startup log in the server's main task)
+that planted a key would be inherited by every request task, making all requests share one object. For the
+same reason the key is not reset when the block ends, so `scope()` must be entered in a task that does not
+outlive the block (a request handler, an actor run).
 
 ## Function Exception Extraction
 

{ddutils-0.2.0 → ddutils-0.2.1}/ddutils/scoped_registry.py

@@ -3,15 +3,42 @@ import inspect
 from collections.abc import AsyncIterator, Awaitable, Callable, Hashable
 from contextlib import asynccontextmanager
 from typing import Any, Generic, TypeVar, get_args
+from uuid import uuid4
 
 _T = TypeVar('_T')
 _CreateFuncType = Callable[..., _T] | Callable[..., Awaitable[_T]]
 _ScopeKey = Hashable
-_ScopeFuncType = Callable[[], _ScopeKey]
+_ScopeFuncType = Callable[..., _ScopeKey | None]
+# A `scope_func` that declares this parameter receives a freshly generated key when `scope()` is entered
+# and `None` on every other access; functions without it are called with no arguments.
+SCOPE_TOKEN_PARAMETER = 'token'
 
 
 class ScopedRegistry(Generic[_T]):
-    """One value per scope; the scope key comes from `scope_func` (e.g. `asyncio.current_task`, `os.getpid`)."""
+    """
+    One value per scope.
+
+    `scope_func` decides what the current scope is and returns its key; `None` means "no current scope" and
+    makes the registry raise `RuntimeError`. Plain key functions take no arguments:
+
+        asyncio.current_task   # one value per task, a child task does not see the parent's value
+        os.getpid              # one value per process
+
+    A `scope_func` that declares a `token` parameter is meant for scopes kept in a `ContextVar`: on entering
+    `scope()` (or on `set()`) it receives a freshly generated token that it may store as the key of a new scope,
+    and on every other access (`get`, `clear`, a nested `scope()`) it receives `None` and must only read:
+
+        def execution_scope(token):            # one value per execution (HTTP request, actor run),
+            key = execution_key.get()          # inherited by the tasks spawned inside the block
+            if key is None and token is not None:
+                execution_key.set(token)
+                key = token
+            return key
+
+    A scope started this way is not reset when the block ends, so `scope()` must be entered in a task that does
+    not outlive the block (a request handler, an actor run); a key left in a long-living task would be
+    inherited by every task spawned from it afterwards.
+    """
 
     __slots__ = ('create_func', 'scope_func', 'registry', 'destructor_method_name', '_lock', '__orig_class__')
 
@@ -35,9 +62,17 @@ class ScopedRegistry(Generic[_T]):
         except IndexError as e:
             raise TypeError('Cannot determine generic type parameter') from e
 
-    def _get_scope_key(self) -> _ScopeKey:
-        key = self.scope_func()
-        if key is None or not isinstance(key, Hashable):
+    def _get_scope_func_kwargs(self, token: str | None) -> dict[str, Any]:
+        kwargs = {}
+        if SCOPE_TOKEN_PARAMETER in inspect.signature(self.scope_func).parameters:
+            kwargs['token'] = token
+        return kwargs
+
+    def _get_scope_key(self, token: str | None = None) -> _ScopeKey:
+        key = self.scope_func(**self._get_scope_func_kwargs(token))
+        if key is None:
+            raise RuntimeError('There is no current scope')
+        if not isinstance(key, Hashable):
             raise RuntimeError(f'scope_func must return a hashable scope key, got {key!r}')
         return key
 
@@ -45,8 +80,8 @@ class ScopedRegistry(Generic[_T]):
         return self.registry.get(self._get_scope_key())
 
     async def _set(self, **kwargs: Any) -> tuple[_T, bool]:
-        """Returns the value of the current scope and whether this call created it."""
-        key = self._get_scope_key()
+        """Returns the value of the current scope and whether this call created it; may start a new scope."""
+        key = self._get_scope_key(uuid4().hex)
         if key in self.registry:
             return self.registry[key], False
 
@@ -58,7 +93,13 @@ class ScopedRegistry(Generic[_T]):
             return self.registry[key], True
 
     async def set(self, **kwargs: Any) -> _T:
-        """Returns the value of the current scope, creating it with `create_func(**kwargs)` if needed."""
+        """
+        Returns the value of the current scope, creating it with `create_func(**kwargs)` if needed.
+
+        Prefer `scope()`: it removes what it created on exit. Whoever calls `set()` directly takes over that
+        responsibility and must call `clear()` when the value is no longer needed (if it ever is: a per-process
+        client may live until the process ends). A `scope_func` with a `token` parameter may start a new scope here.
+        """
         value, _ = await self._set(**kwargs)
         return value
 
@@ -76,6 +117,7 @@ class ScopedRegistry(Generic[_T]):
         """
         Enters the current scope: joins the existing value or creates one. Only the block that created the
         value removes it (and calls the destructor) on exit; nested blocks join and leave it alone.
+        A `scope_func` with a `token` parameter is offered a fresh token here and may start a new scope with it.
         """
         value, created = await self._set(**kwargs)
         try:

{ddutils-0.2.0 → ddutils-0.2.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "ddutils"
 description = "Domain Driven Utils Library"
-version = "0.2.0"
+version = "0.2.1"
 license = "MIT"
 license-files = ["LICENSE"]
 readme = "README.md"
@@ -10,6 +10,14 @@ keywords = [
     "python",
     "ddutils",
 ]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
 dependencies = []
 
 [[project.authors]]

{ddutils-0.2.0 → ddutils-0.2.1}/pyproject.toml.orig

@@ -1,13 +1,22 @@
 [project]
 name = "ddutils"
 description = "Domain Driven Utils Library"
-version = "0.2.0"
+version = "0.2.1"
 authors = [{ name = "davyddd" }]
 license = "MIT"
 license-files = ["LICENSE"]
 readme = "README.md"
 requires-python = ">=3.11,<3.15"
 keywords = ["python", "ddutils"]
+# uv_build does not derive these from requires-python (poetry did); PyPI and the pyversions badge read them
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
 dependencies = []
 
 [project.urls]