ddutils 0.1.6__tar.gz → 0.2.1__tar.gz

{ddutils-0.1.6 → ddutils-0.2.1}/PKG-INFO

@@ -1,20 +1,18 @@
 Metadata-Version: 2.4
 Name: ddutils
-Version: 0.1.6
+Version: 0.2.1
 Summary: Domain Driven Utils Library
-License: MIT
-License-File: LICENSE
 Keywords: python,ddutils
 Author: davyddd
-Requires-Python: >=3.9,<3.15
-Classifier: License :: OSI Approved :: MIT License
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 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
 
@@ -36,6 +34,21 @@ Install the library using pip:
 pip install ddutils
 ```
 
+## Development
+
+The project runs entirely in Docker. Requires Docker and [Fabric](https://www.fabfile.org/) on the host:
+
+```bash
+fab build      # build the dev image
+fab tests      # run pytest
+fab linters    # run ruff (with --fix), ty and complexipy
+fab shell      # IPython inside the container
+fab bash       # bash inside the container
+```
+
+This project was generated from [dd-lib-stub](https://github.com/davyddd/dd-lib-stub);
+run `uvx copier update` to pull in template updates.
+
 ## Type Annotation Helpers
 
 Utilities for inspecting and working with Python type hints and generic types.
@@ -322,33 +335,83 @@ json_loads = get_object_by_path('json.loads')
 
 ## Scoped Registry
 
-A registry that manages object instances within defined scopes.
+A registry that keeps one object instance per scope and manages its lifetime.
 
 ### ScopedRegistry
 
-Manages object instances within scopes (like per request or per session).
+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.
+Concurrent first accesses with the same key call `create_func` only once.
 
 ```python
+import asyncio
+
 from ddutils.scoped_registry import ScopedRegistry
 
 
-def get_current_request_id(): ...
+async def create_session(): ...
 
 
-def create_database_connection(): ...
+# One session per task: a child task spawned with gather/create_task gets its own session
+session_registry = ScopedRegistry(create_func=create_session, scope_func=asyncio.current_task, destructor_method_name='close')
 
 
-db_registry = ScopedRegistry(
-    create_func=create_database_connection,
-    scope_func=get_current_request_id,
-)
+async def handle_request():
+    async with session_registry.scope() as session:  # created here, closed and removed on exit
+        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:
 
-async def handle_request():
-    db = await db_registry()  # Returns existing or creates new db connection
-    await db.execute('select ...')
+- `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): ...
+
+
+log_registry = ScopedRegistry(create_func=create_log_properties, scope_func=execution_scope)
+
+
+async def middleware(headers):
+    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()
 ```
 
+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
 
 AST-based introspection for extracting exceptions from function source code.
@@ -376,4 +439,3 @@ get_safe_element(items, 0)   # 1
 get_safe_element(items, 10)  # None (no IndexError)
 get_safe_element(items, -1)  # 3
 ```
-

{ddutils-0.1.6 → ddutils-0.2.1}/README.md

@@ -16,6 +16,21 @@ Install the library using pip:
 pip install ddutils
 ```
 
+## Development
+
+The project runs entirely in Docker. Requires Docker and [Fabric](https://www.fabfile.org/) on the host:
+
+```bash
+fab build      # build the dev image
+fab tests      # run pytest
+fab linters    # run ruff (with --fix), ty and complexipy
+fab shell      # IPython inside the container
+fab bash       # bash inside the container
+```
+
+This project was generated from [dd-lib-stub](https://github.com/davyddd/dd-lib-stub);
+run `uvx copier update` to pull in template updates.
+
 ## Type Annotation Helpers
 
 Utilities for inspecting and working with Python type hints and generic types.
@@ -302,33 +317,83 @@ json_loads = get_object_by_path('json.loads')
 
 ## Scoped Registry
 
-A registry that manages object instances within defined scopes.
+A registry that keeps one object instance per scope and manages its lifetime.
 
 ### ScopedRegistry
 
-Manages object instances within scopes (like per request or per session).
+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.
+Concurrent first accesses with the same key call `create_func` only once.
 
 ```python
+import asyncio
+
 from ddutils.scoped_registry import ScopedRegistry
 
 
-def get_current_request_id(): ...
+async def create_session(): ...
+
+
+# One session per task: a child task spawned with gather/create_task gets its own session
+session_registry = ScopedRegistry(create_func=create_session, scope_func=asyncio.current_task, destructor_method_name='close')
 
 
-def create_database_connection(): ...
+async def handle_request():
+    async with session_registry.scope() as session:  # created here, closed and removed on exit
+        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:
 
-db_registry = ScopedRegistry(
-    create_func=create_database_connection,
-    scope_func=get_current_request_id,
-)
+- `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
 
-async def handle_request():
-    db = await db_registry()  # Returns existing or creates new db connection
-    await db.execute('select ...')
+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): ...
+
+
+log_registry = ScopedRegistry(create_func=create_log_properties, scope_func=execution_scope)
+
+
+async def middleware(headers):
+    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()
 ```
 
+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
 
 AST-based introspection for extracting exceptions from function source code.

{ddutils-0.1.6 → ddutils-0.2.1}/ddutils/annotation_helpers.py

@@ -1,14 +1,7 @@
 import inspect
-import sys
 from collections.abc import Sequence
-from typing import Any, Tuple, Union, get_args
-
-if sys.version_info >= (3, 10):
-    from types import UnionType
-else:
-
-    class UnionType: ...
-
+from types import UnionType
+from typing import Any, Union, get_args
 
 NON_COMPLEX_SEQUENCE_TYPES = (str, bytes, bytearray)
 
@@ -57,7 +50,7 @@ def get_complex_sequence_element_annotation(annotation: Any) -> Any:
     return element_annotation
 
 
-def get_dict_items_annotation(annotation: Any) -> Tuple[Any, Any]:
+def get_dict_items_annotation(annotation: Any) -> tuple[Any, Any]:
     if hasattr(annotation, '__supertype__'):
         return get_dict_items_annotation(annotation.__supertype__)
     elif not is_subclass(annotation, dict):

{ddutils-0.1.6 → ddutils-0.2.1}/ddutils/class_helpers.py

@@ -1,10 +1,11 @@
 import inspect
-from typing import Any, Callable, Optional, Type, TypeVar
+from collections.abc import Callable
+from typing import Any, TypeVar
 
 _T = TypeVar('_T', bound=Any)
 
 
-def get_origin_class_of_method(cls: Any, method_name: str) -> Optional[Type]:
+def get_origin_class_of_method(cls: Any, method_name: str) -> type | None:
     """
     Find the class in the inheritance hierarchy where a method is originally defined.
 
@@ -50,9 +51,9 @@ class classproperty:  # noqa: N801
         """
         self.fget = fget
         self.__doc__ = fget.__doc__
-        self.__name__ = fget.__name__
+        self.__name__ = getattr(fget, '__name__', type(fget).__name__)
 
-    def __get__(self, instance: Any, owner: Type[Any]) -> Any:
+    def __get__(self, instance: Any, owner: type[Any]) -> Any:
         """
         Retrieve the property value using the descriptor protocol.
 

ddutils-0.2.1/ddutils/datetime_helpers.py

@@ -0,0 +1,5 @@
+from datetime import UTC, datetime
+
+
+def utc_now() -> datetime:
+    return datetime.now(tz=UTC)

{ddutils-0.1.6 → ddutils-0.2.1}/ddutils/function_exceptions_extractor.py

@@ -2,9 +2,9 @@ import ast
 import builtins
 import inspect
 import textwrap
-from collections.abc import Generator
+from collections.abc import Callable, Generator
 from importlib import import_module
-from typing import Any, Callable, Dict, NamedTuple, Optional, Tuple, Type
+from typing import Any, NamedTuple
 
 from ddutils.module_getter import get_module
 
@@ -20,16 +20,16 @@ class Annotation(NamedTuple):
 
 
 class ExceptionInfo:
-    exception_class: Type[Exception]
-    args: Tuple[Any, ...]
-    kwargs: Dict[str, Any]
+    exception_class: type[Exception]
+    args: tuple[Any, ...]
+    kwargs: dict[str, Any]
 
-    def __init__(self, exception_class: Type[Exception], args: Tuple[Any, ...], kwargs: Dict[str, Any]):
+    def __init__(self, exception_class: type[Exception], args: tuple[Any, ...], kwargs: dict[str, Any]):
         self.exception_class = exception_class
         self.args = tuple(_v.value if isinstance(_v, ast.Constant) else UNDEFINED_VALUE for _v in args)
         self.kwargs = {_k: _v.value if isinstance(_v, ast.Constant) else UNDEFINED_VALUE for _k, _v in kwargs.items()}
 
-    def get_kwargs(self) -> Dict[str, Any]:
+    def get_kwargs(self) -> dict[str, Any]:
         annotations = tuple(
             Annotation(argument, argument_info.default)
             for argument, argument_info in inspect.signature(self.exception_class.__init__).parameters.items()
@@ -52,7 +52,7 @@ class ExceptionInfo:
 
         return kwargs
 
-    def get_exception_instance(self, dry_run: bool = True) -> Optional[Exception]:
+    def get_exception_instance(self, dry_run: bool = True) -> Exception | None:
         kwargs = {k: f'<{k}>' if v is UNDEFINED_VALUE else v for k, v in self.get_kwargs().items()}
         try:
             # There might be issues with strict typing because UNDEFINED_VALUE is always replaced with a string
@@ -75,37 +75,44 @@ def _get_node_name(node: ast.AST) -> str:
         raise TypeError(f'Unsupported node type: {type(node)}')
 
 
-def extract_function_exceptions(func: Callable) -> Generator[ExceptionInfo, None, None]:
-    source = textwrap.dedent(inspect.getsource(func))
-    tree = ast.parse(source)
+def _resolve_exception_class(func: Callable, exception_name: str) -> type[Exception] | None:
+    *sub_modules, class_name = exception_name.split('.')
+    exception_module = get_module(import_module(func.__module__), sub_modules)
+
+    exception_class: type[Exception] | None = getattr(exception_module, class_name, None)
+    if exception_class is None and hasattr(builtins, exception_name):
+        exception_class = getattr(builtins, exception_name)
+
+    return exception_class
 
-    for node in ast.walk(tree):
-        if isinstance(node, ast.Raise):
-            if node.exc is None:
-                continue
 
-            try:
-                exception_name: str = _get_node_name(node.exc)
-                exception_args: Tuple[Any, ...] = ()
-                exception_kwargs: Dict[str, Any] = {}
-            except TypeError:
-                continue
+def _extract_raise_exception(func: Callable, node: ast.Raise) -> ExceptionInfo | None:
+    if node.exc is None:
+        return None
 
-            if isinstance(node.exc, ast.Call):
-                exception_args = tuple(node.exc.args)
-                exception_kwargs = {kw.arg: kw.value for kw in node.exc.keywords if isinstance(kw.arg, str)}
+    try:
+        exception_name = _get_node_name(node.exc)
+    except TypeError:
+        return None
 
-            exception_name_slices = exception_name.split('.')
-            class_name = exception_name_slices[-1]
-            sub_modules = exception_name_slices[:-1]
+    exception_args: tuple[Any, ...] = ()
+    exception_kwargs: dict[str, Any] = {}
+    if isinstance(node.exc, ast.Call):
+        exception_args = tuple(node.exc.args)
+        exception_kwargs = {kw.arg: kw.value for kw in node.exc.keywords if isinstance(kw.arg, str)}
 
-            exception_module = get_module(import_module(func.__module__), sub_modules)
+    exception_class = _resolve_exception_class(func, exception_name)
+    if exception_class is None:
+        return None
 
-            exception_class: Optional[Type[Exception]] = getattr(exception_module, class_name, None)
-            if exception_class is None and hasattr(builtins, exception_name):
-                exception_class = getattr(builtins, exception_name)
+    return ExceptionInfo(exception_class=exception_class, args=exception_args, kwargs=exception_kwargs)
 
-            if exception_class is None:
-                continue
 
-            yield ExceptionInfo(exception_class=exception_class, args=exception_args, kwargs=exception_kwargs)
+def extract_function_exceptions(func: Callable) -> Generator[ExceptionInfo, None, None]:
+    source = textwrap.dedent(inspect.getsource(func))
+
+    for node in ast.walk(ast.parse(source)):
+        if isinstance(node, ast.Raise):
+            exception_info = _extract_raise_exception(func, node)
+            if exception_info is not None:
+                yield exception_info

ddutils-0.2.1/ddutils/function_helpers.py

@@ -0,0 +1,33 @@
+from types import CellType, CodeType, FunctionType
+
+
+def create_new_function(base_func: FunctionType, new_name: str | None = None) -> FunctionType:
+    base_code = base_func.__code__
+    func_name = new_name or base_code.co_name
+
+    new_code = CodeType(
+        base_code.co_argcount,
+        base_code.co_posonlyargcount,
+        base_code.co_kwonlyargcount,
+        base_code.co_nlocals,
+        base_code.co_stacksize,
+        base_code.co_flags,
+        base_code.co_code,
+        base_code.co_consts,
+        base_code.co_names,
+        base_code.co_varnames,
+        base_code.co_filename,
+        func_name,
+        func_name,
+        base_code.co_firstlineno,
+        base_code.co_linetable,
+        base_code.co_exceptiontable,
+        base_code.co_freevars,
+        base_code.co_cellvars,
+    )
+
+    closure = base_func.__closure__
+    if closure:
+        closure = tuple(CellType(cell.cell_contents) for cell in closure)
+
+    return FunctionType(new_code, base_func.__globals__, func_name, base_func.__defaults__, closure)

{ddutils-0.1.6 → ddutils-0.2.1}/ddutils/module_getter.py

@@ -1,8 +1,7 @@
 from types import ModuleType
-from typing import List
 
 
-def get_module(module: ModuleType, sub_modules: List[str]) -> ModuleType:
+def get_module(module: ModuleType, sub_modules: list[str]) -> ModuleType:
     if not module:
         raise ValueError('Argument `module` is required')
     elif not isinstance(sub_modules, list):

{ddutils-0.1.6 → ddutils-0.2.1}/ddutils/object_getter.py

@@ -1,8 +1,8 @@
 import importlib
-from typing import Any, Optional
+from typing import Any
 
 
-def get_object_by_path(path: Optional[str]) -> Any:
+def get_object_by_path(path: str | None) -> Any:
     try:
         if not isinstance(path, str):
             raise ValueError

{ddutils-0.1.6 → ddutils-0.2.1}/ddutils/safe_decorators.py

@@ -1,15 +1,16 @@
 import logging
+from collections.abc import Callable
 from functools import wraps
-from typing import Any, Callable, Optional, Tuple, Type
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
 
 def safe_call(
-    func: Optional[Callable] = None,
+    func: Callable | None = None,
     capture_exception: bool = True,
-    default_result: Optional[Any] = None,
-    exceptions: Tuple[Type[Exception], ...] = (Exception,),
+    default_result: Any | None = None,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
 ) -> Callable:
     if func is None:
         return lambda _func: safe_call(
@@ -32,7 +33,7 @@ def safe_call(
 
 
 def retry_once_after_exception(
-    func: Optional[Callable] = None, capture_exception: bool = True, exceptions: Tuple[Type[Exception], ...] = (Exception,)
+    func: Callable | None = None, capture_exception: bool = True, exceptions: tuple[type[Exception], ...] = (Exception,)
 ) -> Callable:
     if func is None:
         return lambda _func: retry_once_after_exception(func=_func, capture_exception=capture_exception, exceptions=exceptions)

ddutils-0.2.1/ddutils/scoped_registry.py

@@ -0,0 +1,127 @@
+import asyncio
+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 | 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.
+
+    `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__')
+
+    def __init__(
+        self,
+        create_func: _CreateFuncType,
+        scope_func: _ScopeFuncType,
+        destructor_method_name: str | None = None,
+    ) -> None:
+        self.create_func = create_func
+        self.scope_func = scope_func
+        self.registry: dict[_ScopeKey, _T] = {}
+        self.destructor_method_name = destructor_method_name
+        self._lock = asyncio.Lock()
+
+    @property
+    def generic_type(self) -> type[_T]:
+        orig_class = getattr(self, '__orig_class__', None)
+        try:
+            return get_args(orig_class)[0]
+        except IndexError as e:
+            raise TypeError('Cannot determine generic type parameter') from e
+
+    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
+
+    def get(self) -> _T | None:
+        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; may start a new scope."""
+        key = self._get_scope_key(uuid4().hex)
+        if key in self.registry:
+            return self.registry[key], False
+
+        async with self._lock:
+            if key in self.registry:
+                return self.registry[key], False
+            result = self.create_func(**kwargs)
+            self.registry[key] = await result if inspect.isawaitable(result) else result
+            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.
+
+        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
+
+    async def clear(self) -> None:
+        """Removes the value of the current scope and calls its destructor."""
+        instance = self.registry.pop(self._get_scope_key(), None)
+        destructor = getattr(instance, self.destructor_method_name or '', None)
+        if destructor is not None:
+            result = destructor()
+            if inspect.isawaitable(result):
+                await result
+
+    @asynccontextmanager
+    async def scope(self, **kwargs: Any) -> AsyncIterator[_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:
+            yield value
+        finally:
+            if created:
+                await self.clear()

ddutils-0.2.1/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "ddutils"
+description = "Domain Driven Utils Library"
+version = "0.2.1"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.11,<3.15"
+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]]
+name = "davyddd"
+
+[project.urls]
+Repository = "https://github.com/davyddd/ddutils"
+
+[dependency-groups]
+dev = [
+    "ipdb==0.13.13",
+    "ipython==9.16.1",
+]
+test = [
+    "pytest==9.0.3",
+    "pytest-cov==5.0.0",
+    "parameterized==0.9.0",
+]
+linter = [
+    "ruff==0.15.10",
+    "ty==0.0.15",
+    "complexipy==8.0.1",
+]
+
+[tool.uv.build-backend]
+module-root = ""
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"

ddutils-0.2.1/pyproject.toml.orig

@@ -0,0 +1,46 @@
+[project]
+name = "ddutils"
+description = "Domain Driven Utils Library"
+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]
+Repository = "https://github.com/davyddd/ddutils"
+
+[dependency-groups]
+dev = [
+    "ipdb==0.13.13",
+    "ipython==9.16.1",
+]
+test = [
+    "pytest==9.0.3",
+    "pytest-cov==5.0.0",
+    "parameterized==0.9.0",
+]
+linter = [
+    "ruff==0.15.10",
+    "ty==0.0.15",
+    "complexipy==8.0.1",
+]
+
+[tool.uv.build-backend]
+module-root = ""
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"

ddutils-0.1.6/ddutils/datetime_helpers.py

@@ -1,13 +0,0 @@
-import sys
-from datetime import datetime
-
-if sys.version_info >= (3, 11):
-    from datetime import UTC
-else:
-    from datetime import timezone
-
-    UTC = timezone.utc
-
-
-def utc_now() -> datetime:
-    return datetime.now(tz=UTC)

ddutils-0.1.6/ddutils/function_helpers.py

@@ -1,57 +0,0 @@
-import sys
-from types import CellType, CodeType, FunctionType
-from typing import Callable, Optional
-
-
-def create_new_function(base_func: Callable, new_name: Optional[str] = None) -> Callable:
-    base_code = base_func.__code__
-    func_name = new_name or base_code.co_name
-
-    if sys.version_info >= (3, 11):
-        # for python 3.11 and newer
-        new_code = CodeType(
-            base_code.co_argcount,
-            base_code.co_posonlyargcount,
-            base_code.co_kwonlyargcount,
-            base_code.co_nlocals,
-            base_code.co_stacksize,
-            base_code.co_flags,
-            base_code.co_code,
-            base_code.co_consts,
-            base_code.co_names,
-            base_code.co_varnames,
-            base_code.co_filename,
-            func_name,
-            func_name,
-            base_code.co_firstlineno,
-            base_code.co_lnotab,
-            base_code.co_exceptiontable,
-            base_code.co_freevars,
-            base_code.co_cellvars,
-        )
-    else:
-        # for python 3.10 and older
-        new_code = CodeType(
-            base_code.co_argcount,
-            base_code.co_posonlyargcount,
-            base_code.co_kwonlyargcount,
-            base_code.co_nlocals,
-            base_code.co_stacksize,
-            base_code.co_flags,
-            base_code.co_code,
-            base_code.co_consts,
-            base_code.co_names,
-            base_code.co_varnames,
-            base_code.co_filename,
-            func_name,
-            base_code.co_firstlineno,
-            base_code.co_lnotab,
-            base_code.co_freevars,
-            base_code.co_cellvars,
-        )
-
-    closure = base_func.__closure__
-    if closure:
-        closure = tuple(CellType(cell.cell_contents) for cell in closure)
-
-    return FunctionType(new_code, base_func.__globals__, func_name, base_func.__defaults__, closure)

ddutils-0.1.6/ddutils/scoped_registry.py

@@ -1,91 +0,0 @@
-import inspect
-from collections.abc import Awaitable, Hashable
-from typing import Any, Callable, Dict, Generic, Optional, Type, TypeVar, Union, get_args
-
-_T = TypeVar('_T', bound=Any)
-_CreateFuncType = Union[Callable[..., _T], Callable[..., Awaitable[_T]]]
-_ScopeType = Hashable
-_ScopeFuncType = Callable[[], _ScopeType]
-_RegistryType = Dict[_ScopeType, _T]
-
-
-class ScopedRegistry(Generic[_T]):
-    __slots__ = 'create_func', 'scope_func', 'registry', 'destructor_method_name', '__orig_class__'
-
-    create_func: _CreateFuncType
-    scope_func: _ScopeFuncType
-    registry: _RegistryType
-    destructor_method_name: Optional[str]
-
-    def __init__(self, create_func: _CreateFuncType, scope_func: _ScopeFuncType, destructor_method_name: Optional[str] = None):
-        self.create_func = create_func
-        self.scope_func = scope_func
-        self.registry = {}
-        self.destructor_method_name = destructor_method_name
-
-    @property
-    def generic_type(self) -> Type[_T]:
-        orig_class = getattr(self, '__orig_class__', None)
-        try:
-            return get_args(orig_class)[0]
-        except IndexError as e:
-            raise TypeError('Cannot determine generic type parameter') from e
-
-    def get(self) -> Optional[_T]:
-        try:
-            key = self.scope_func()
-            return self.registry[key]
-        except Exception:  # noqa: BLE001
-            return None
-
-    def _set(self, **kwargs: Any) -> tuple[_ScopeType, Union[_T, Awaitable[_T]]]:
-        key = self.scope_func()
-        if key in self.registry:
-            return key, self.registry[key]
-        return key, self.create_func(**kwargs)
-
-    def sync_set(self, **kwargs: Any) -> _T:
-        key, result = self._set(**kwargs)
-        if inspect.isawaitable(result):
-            raise TypeError('create_func returned an awaitable; use async_set instead')
-        self.registry[key] = result
-        return result
-
-    async def async_set(self, **kwargs: Any) -> _T:
-        key, result = self._set(**kwargs)
-        self.registry[key] = await result if inspect.isawaitable(result) else result
-        return self.registry[key]
-
-    def _clear(self, *scopes: _ScopeType):
-        if not scopes and (scope := self.scope_func()):
-            scopes = (scope,)
-
-        if not (self.registry and scopes):
-            return
-
-        for scope in scopes:
-            if scope in self.registry:
-                instance = self.registry.pop(scope)
-
-                if isinstance(self.destructor_method_name, str):
-                    destructor_method = getattr(instance, self.destructor_method_name, None)
-                    if destructor_method:
-                        yield destructor_method()
-
-    def sync_clear(self, *scopes: _ScopeType) -> None:
-        for result in self._clear(*scopes):
-            if inspect.isawaitable(result):
-                raise TypeError('destructor returned an awaitable; use async clear instead')
-
-    async def async_clear(self, *scopes: _ScopeType) -> None:
-        for result in self._clear(*scopes):
-            if inspect.isawaitable(result):
-                await result
-
-    # deprecated: use async_set / async_clear instead
-
-    async def __call__(self, **kwargs: Any) -> _T:
-        return await self.async_set(**kwargs)
-
-    async def clear(self, *scopes: _ScopeType) -> None:
-        await self.async_clear(*scopes)

ddutils-0.1.6/pyproject.toml

@@ -1,31 +0,0 @@
-[tool.poetry]
-name = "ddutils"
-description = "Domain Driven Utils Library"
-version = "0.1.6"
-authors = ["davyddd"]
-license = "MIT"
-repository = "https://github.com/davyddd/ddutils"
-readme = "README.md"
-keywords = ["python", "ddutils"]
-packages = [{include = "ddutils"}]
-
-[tool.poetry.dependencies]
-python = ">=3.9,<3.15"
-
-[tool.poetry.group.dev.dependencies]
-ipdb = "0.13.9"
-ipython = "8.12.3"
-
-[tool.poetry.group.test.dependencies]
-pytest = "8.1.1"
-pytest-cov = "5.0.0"
-parameterized = "0.9.0"
-typing-extensions = "^4.12.2"
-
-[tool.poetry.group.linter.dependencies]
-mypy = "1.18.2"
-ruff = "0.14.4"
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"