semifun 0.3.0__py3-none-any.whl

semifun/caching/cached_method.py

@@ -0,0 +1,56 @@
+import inspect
+import functools
+from semifun.caching.dictdefault import dictdefault
+
+
+def cached_method(fn):
+    """Decorator that caches method results by hashed arguments.
+
+    Example::
+
+        @dataclass(frozen=True)
+        class MyService:
+            cache_codec: Inject[TmsgpackCodec]
+            ...
+
+            @cached_method
+            def get_config(self, env: str) -> Config: ...
+
+            @cached_method
+            async def fetch_user(self, user_id: int) -> User: ...
+    """
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.keys())
+    assert params and params[0] == 'self'
+    cache_attr = f'_method_cache_{fn.__name__}'
+    is_async = inspect.iscoroutinefunction(fn)
+    dd = dictdefault.a if is_async else dictdefault
+
+    # Build a signature without 'self' for normalization
+    norm_sig = sig.replace(parameters=[sig.parameters[p] for p in params[1:]])
+
+    def _get_cache(self):
+        try:
+            return getattr(self, cache_attr)
+        except AttributeError:
+            cache = {}
+            object.__setattr__(self, cache_attr, cache)
+            return cache
+
+    def _make_key(self, args, kwargs):
+        bound = norm_sig.bind(*args, **kwargs)
+        bound.apply_defaults()
+        return self.cache_codec.hash_to_bytes(bound.args + tuple(bound.kwargs.items()))
+
+    if is_async:
+        @functools.wraps(fn)
+        async def wrapper(self, *args, **kwargs):
+            key = _make_key(self, args, kwargs)
+            return await dd(_get_cache(self), key, lambda: fn(self, *args, **kwargs))
+        return wrapper
+    else:
+        @functools.wraps(fn)
+        def wrapper(self, *args, **kwargs):
+            key = _make_key(self, args, kwargs)
+            return dd(_get_cache(self), key, lambda: fn(self, *args, **kwargs))
+        return wrapper

semifun/caching/cached_property.py

@@ -0,0 +1,52 @@
+# We do not use functools.cached_property because it contains messy
+# and unnecessary code for threaded programs.  In addition, our
+# `@cached_property` decorator can be used correctly with async methods.
+
+import inspect, asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeVar, Generic, Callable, Any, overload
+
+T = TypeVar('T')
+
+class cached_property(Generic[T]):
+    fn: Callable[[Any], T]
+    _name: str
+
+    def __init__(self, fn: Callable[[Any], T]):
+        import types
+        fn2 = fn if isinstance(fn, types.FunctionType) else getattr(fn, '__call__', fn)  # type: ignore[arg-type]
+        if inspect.iscoroutinefunction(fn2):
+            self.fn = lambda self: create_task_loop_check(fn(self), name=None, context=None)  # type: ignore[assignment,return-value]
+        else:
+            self.fn = fn
+        self._name = fn.__name__
+        self.__doc__ = fn.__doc__
+
+    @overload
+    def __get__(self, instance: None, cls: type) -> cached_property[T]: ...
+    @overload
+    def __get__(self, instance: object, cls: type) -> T: ...
+
+    def __get__(self, instance: object | None, cls: type) -> T | cached_property[T]:
+        if instance is None:
+            return self
+        value = self.fn(instance)
+        instance.__dict__[self._name] = value
+        return value
+
+def create_task_loop_check(coro: Any, name: str | None, context: Any) -> LoopCheck:
+    task = asyncio.create_task(coro, name=name, context=context)
+    task._loop_check_parent_task = asyncio.current_task()  # type: ignore[attr-defined]
+    return LoopCheck(task=task)
+
+@dataclass(frozen=True)
+class LoopCheck:
+    task: asyncio.Task[Any]
+
+    def __await__(self):
+        testing = asyncio.current_task()
+        while testing:
+            if testing is self.task:
+                raise ValueError(f'Deadlock: {self.task}')
+            testing = getattr(testing, '_loop_check_parent_task', None)
+        return self.task.__await__()

semifun/caching/dictdefault.py

@@ -0,0 +1,59 @@
+"""dictdefault — a caching accessor for normal dicts.
+
+The name is a play on ``defaultdict``: instead of using a special dict type,
+you use a normal dict and a caching accessor function.
+
+Variants:
+
+- ``dictdefault``    — sync, key not passed to the function.
+- ``dictdefault.k``  — sync, key passed as first argument.
+- ``dictdefault.a``  — async, key not passed.
+- ``dictdefault.ak`` — async, key passed as first argument.
+
+The async variants ensure the computation runs only once, even when
+additional requests arrive while the first computation is still running.
+All callers receive the same awaitable task object.
+
+All variants accept ``**kwargs`` which are forwarded to the function.
+They are considered only the first time — when the computation is performed.
+
+Example::
+
+    cache1 = {}; cache2 = {}  # sync and async use distinct caching formats
+    config  = dictdefault(cache1, 'db', load_config)        # → load_config()
+    user    = dictdefault.k(cache1, 'alice', fetch_user)    # → fetch_user('alice')
+    session = await dictdefault.a(cache2, 'main', async_create_session)
+        # → await async_create_session()
+    page    = await dictdefault.ak(cache2, url, async_fetch_page)
+        # → await async_fetch_page(url)
+"""
+
+def _mk_dictdefault():
+    def _dd(with_key):
+        def dictdefault(_d, _key, _fn, **kwargs):
+            if _key not in _d:
+                _d[_key] = _fn(_key, **kwargs) if with_key else _fn(**kwargs)
+            return _d[_key]
+        return dictdefault
+
+    def _dda(with_key):
+        from semifun.caching.cached_property import create_task_loop_check
+        async def dictdefault(_d, _key, _fn, **kwargs):
+            if _key not in _d:
+                _d[_key] = (
+                  create_task_loop_check(
+                      _fn(_key, **kwargs) if with_key else _fn(**kwargs),
+                      name=None, context=None,
+                  )
+                )
+            return await _d[_key]
+        return dictdefault
+
+    dictdefault    = _dd(False)
+    dictdefault.k  = _dd(True)
+    dictdefault.a  = _dda(False)
+    dictdefault.ak = _dda(True)
+
+    return dictdefault
+
+dictdefault = _mk_dictdefault()

semifun/cli/argv.py

@@ -0,0 +1,28 @@
+"""Parse CLI argv into positional args and keyword args.
+
+Pure string processing — no knowledge of the target function.
+"""
+
+
+def split_argv(argv: list[str]) -> tuple[list[str], dict[str, str]]:
+    """Split argv tokens into positional args and keyword args.
+
+    Tokens containing '=' (split at the first '=') become keyword args.
+    All other tokens are positional args, in their original order.
+
+    Example:
+        split_argv(['hello', 'time=now', 'world', 'age=10'])
+        → (['hello', 'world'], {'time': 'now', 'age': '10'})
+
+    Returns:
+        (args, kwargs) — both contain raw strings, no type casting.
+    """
+    args: list[str] = []
+    kwargs: dict[str, str] = {}
+    for token in argv:
+        if '=' in token:
+            key, value = token.split('=', 1)
+            kwargs[key] = value
+        else:
+            args.append(token)
+    return args, kwargs

semifun/cli/cast.py

@@ -0,0 +1,101 @@
+"""Type-cast CLI string arguments based on function signature annotations.
+
+Self-contained — uses only the standard library's inspect module.
+Handles regular parameters, *args with element-level annotations,
+and **kwargs with element-level annotations.
+"""
+
+import inspect
+from typing import Any
+
+
+def cast_args(
+    fn: Any,
+    args: list[str],
+    kwargs: dict[str, str],
+) -> tuple[tuple[Any, ...], dict[str, Any]]:
+    """Cast string args and kwargs to the types declared in fn's signature.
+
+    Inspects fn's signature and casts each value:
+    - Regular positional/keyword params: cast by their annotation
+    - *args (VAR_POSITIONAL): cast each element by the *args annotation
+    - **kwargs (VAR_KEYWORD): cast each element by the **kwargs annotation
+
+    Only int, float, and bool are cast. All other types (or missing
+    annotations) pass the string through unchanged.
+
+    Args:
+        fn: The target function whose signature provides type information.
+        args: Positional arguments as strings.
+        kwargs: Keyword arguments as strings.
+
+    Returns:
+        (cast_args_tuple, cast_kwargs_dict) ready for fn(*args, **kwargs).
+    """
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.values())
+
+    cast_positional: list[Any] = []
+    cast_kwargs: dict[str, Any] = {}
+
+    # Separate params by kind
+    positional_params: list[inspect.Parameter] = []
+    var_positional: inspect.Parameter | None = None
+    keyword_params: dict[str, inspect.Parameter] = {}
+    var_keyword: inspect.Parameter | None = None
+
+    for p in params:
+        if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD):
+            positional_params.append(p)
+        elif p.kind == p.VAR_POSITIONAL:
+            var_positional = p
+        elif p.kind == p.KEYWORD_ONLY:
+            keyword_params[p.name] = p
+        elif p.kind == p.VAR_KEYWORD:
+            var_keyword = p
+
+    # Cast positional args
+    for i, value in enumerate(args):
+        if i < len(positional_params):
+            annotation = positional_params[i].annotation
+        elif var_positional is not None:
+            annotation = var_positional.annotation
+        else:
+            annotation = inspect.Parameter.empty
+        cast_positional.append(_cast_value(annotation, value))
+
+    # Cast keyword args
+    for key, value in kwargs.items():
+        if key in keyword_params:
+            annotation = keyword_params[key].annotation
+        elif key in {p.name for p in positional_params}:
+            # Named arg matching a positional param
+            param = next(p for p in positional_params if p.name == key)
+            annotation = param.annotation
+        elif var_keyword is not None:
+            annotation = var_keyword.annotation
+        else:
+            annotation = inspect.Parameter.empty
+        cast_kwargs[key] = _cast_value(annotation, value)
+
+    return tuple(cast_positional), cast_kwargs
+
+
+def _cast_value(annotation: Any, value: str) -> Any:
+    """Cast a single string value to the annotated type.
+
+    Only int, float, and bool are cast. Everything else passes through.
+    """
+    if annotation is inspect.Parameter.empty:
+        return value
+    if annotation is int:
+        return int(value)
+    if annotation is float:
+        return float(value)
+    if annotation is bool:
+        if value in ('0', 'false', 'False', 'no'):
+            return False
+        if value in ('1', 'true', 'True', 'yes'):
+            return True
+        raise ValueError(f"Cannot cast {value!r} to bool. Use 0/1/true/false/yes/no.")
+    return value

semifun/cli/decorator.py

@@ -0,0 +1,26 @@
+"""Decorator for sync functions that own the async event loop.
+
+Some functions (e.g., HTTP server launchers) are sync but start their own
+async event loop internally. These cannot be called from within an existing
+event loop — they must use the sync DI API instead of async.
+
+This is a supported but non-standard pattern. It is an anti-pattern for
+composability: such functions never compose cleanly with other async code.
+"""
+
+
+def sync_function_owns_async_loop(fn):
+    """Mark a sync function as owning the async event loop.
+
+    `sync_cli_dispatch_engine` detects this attribute and uses the sync DI
+    API (sync_call_with_args).  `cli_dispatch_engine`, the standard engine,
+    ignores it: such a command cannot be awaited, which is why it needs the
+    engine that owns the loop.
+
+    Usage:
+        @sync_function_owns_async_loop
+        def start_server(host: str = 'localhost', port: int = 8080):
+            uvicorn.run(app, host=host, port=int(port))
+    """
+    fn.sync_function_owns_async_loop = True
+    return fn

semifun/cli/dispatch.py

@@ -0,0 +1,145 @@
+"""CLI dispatch: discover a function by name, call it with DI and type-cast args.
+
+This module composes the pieces (argv splitting, type casting, DI invocation)
+into a complete CLI dispatcher.
+
+Two engines are exposed:
+
+* `cli_dispatch_engine` — async, awaits in the caller's loop.  The standard.
+* `sync_cli_dispatch_engine` — sync, for commands that must own the loop.
+"""
+
+import asyncio
+import inspect
+import sys
+import textwrap
+
+from semifun.plugins.registry import get_cached_feature_map
+
+from semifun.di.registry_integration import get_injector
+
+from .argv import split_argv
+from .cast import cast_args
+
+
+async def cli_dispatch_engine(
+    cli_feature_type: str,
+    injector_feature_type: str,
+    argv: list[str],
+    seed_data: dict,
+):
+    """Discover and run a CLI command with DI and type-cast arguments.
+
+    Runs inside the caller's event loop — it does not create one.  This is
+    the standard engine; see `sync_cli_dispatch_engine` for the other path.
+
+    Args:
+        cli_feature_type: Feature type for CLI commands (e.g., 'cli').
+        injector_feature_type: Feature type for DI injectors (e.g., 'cli_inject').
+        argv: Command-line arguments, without the program name.
+        seed_data: seed_data dict for DI; `{}` when there is none.
+    """
+    resolved = _resolve(cli_feature_type, argv)
+    if resolved is None:
+        return
+    fn, cast_positional, cast_kwargs = resolved
+
+    di = get_injector(injector_feature_type).with_seed_data(seed_data)
+
+    result = await di.async_call_with_args(
+        fn=fn,
+        args=cast_positional,
+        kwargs=cast_kwargs,
+    )
+
+    if result is not None:
+        print(result)
+
+
+def sync_cli_dispatch_engine(
+    cli_feature_type: str,
+    injector_feature_type: str,
+    argv: list[str],
+    seed_data: dict,
+):
+    """Same as `cli_dispatch_engine`, but owns the event loop.
+
+    Use this only when a command function is itself sync and
+    starts its own loop (marked `@sync_function_owns_async_loop`); such a
+    command cannot be awaited and so forces the dispatcher to be outermost.
+    Prefer `cli_dispatch_engine`.
+    """
+    resolved = _resolve(cli_feature_type, argv)
+    if resolved is None:
+        return
+    fn, cast_positional, cast_kwargs = resolved
+
+    di = get_injector(injector_feature_type).with_seed_data(seed_data)
+
+    if getattr(fn, 'sync_function_owns_async_loop', False):
+        result = di.sync_call_with_args(
+            fn=fn,
+            args=cast_positional,
+            kwargs=cast_kwargs,
+        )
+    else:
+        result = asyncio.run(di.async_call_with_args(
+            fn=fn,
+            args=cast_positional,
+            kwargs=cast_kwargs,
+        ))
+
+    if result is not None:
+        print(result)
+
+
+def _resolve(cli_feature_type: str, argv: list[str]):
+    """Find the command and prepare its arguments — everything before the call.
+
+    Returns (fn, args, kwargs), or None when help was printed instead.
+    Exits with status 1 on an unknown command.
+    """
+    cli_map = get_cached_feature_map(feature_type=cli_feature_type)
+
+    if not argv or argv[0] == '--help':
+        _print_help(cli_map)
+        return None
+
+    command_name = argv[0]
+    command_argv = argv[1:]
+
+    fn = cli_map(feature=command_name, default=None)
+
+    if fn is None:
+        print(f"Unknown command: {command_name}")
+        print()
+        _print_help(cli_map)
+        sys.exit(1)
+
+    if command_argv == ['--help']:
+        _print_command_help(command_name, fn)
+        return None
+
+    str_args, str_kwargs = split_argv(command_argv)
+    cast_positional, cast_kwargs = cast_args(fn, str_args, str_kwargs)
+    return fn, cast_positional, cast_kwargs
+
+
+def _print_command_help(name: str, fn):
+    """Print detailed help for a single command."""
+    sig = inspect.signature(fn)
+    doc = inspect.cleandoc(fn.__doc__ or "(no description)")
+    indented = textwrap.indent(doc, "    ")
+    print(f"{name}{sig}")
+    print(indented)
+
+
+def _print_help(cli_map):
+    """Print help for all discovered CLI commands."""
+    if not cli_map.feature_names:
+        print("No commands available.")
+        return
+    print("Available commands:\n")
+    for name, fn in cli_map.feature_names_and_objects:
+        _print_command_help(name, fn)
+        print()

semifun/di/async_execution_context.py

@@ -0,0 +1,154 @@
+"""Per-call async execution context for dependency injection.
+
+A new `_AsyncExecutionContext` is created for each public async DI API call.
+It holds the per-call state (resolution cache, cleanup stack, cycle-detection
+lock) and delegates signature lookups to the parent `DependencyInjector`.
+
+This module is internal — the public API lives on `DependencyInjector`.
+
+**THIS IS THE SOURCE OF TRUTH FOR THE DI EXECUTION LOGIC.** Any changes here
+must be propagated to `sync_execution_context.py` following the rules in
+`SYNC-CONVERSION.md`.
+"""
+
+from dataclasses import dataclass, field
+from inspect import isasyncgen, isawaitable, isgenerator
+from typing import Any, Callable, TYPE_CHECKING
+
+from .model import InjectArg
+from .signature_processing import cache_key_for
+
+if TYPE_CHECKING:
+    from .injector import DependencyInjector
+
+
+@dataclass(frozen=True)
+class _AsyncExecutionContext:
+    """One async DI execution. Created fresh per public API call, disposed at end.
+
+    Holds:
+    - `cache`: Type → resolved value, seeded from seed_data
+    - `cleanup_stack`: generators awaiting their final next/anext for cleanup
+    - `lock`: cache keys of functions currently being invoked (cycle detection)
+    - `injector`: reference to the parent DependencyInjector
+    """
+
+    injector: "DependencyInjector"
+    cache: dict[type, Any] = field(init=False)
+    cleanup_stack: list[Any] = field(default_factory=list, init=False)
+    lock: set[Any] = field(default_factory=set, init=False)
+
+    def __post_init__(self) -> None:
+        # Shallow copy of seed_data, plus auto-seed DependencyInjector for re-entrant DI access.
+        object.__setattr__(self, 'cache', {**self.injector.seed_data, type(self.injector): self.injector})
+
+    # --- Resolution of one injected argument ---
+
+    async def _resolve_inject_arg(self, arg: InjectArg) -> Any:
+        """Resolve one InjectArg to a value.
+
+        Order:
+        1. Cache hit → return cached value.
+        2. No cache and no injector → raise.
+        3. Otherwise call the injector recursively, isinstance-check, cache, return.
+        """
+        if arg.type in self.cache:
+            return self.cache[arg.type]
+        if arg.injector_fn is None:
+            raise LookupError(
+                f"Cannot resolve injection for parameter {arg.name!r}: "
+                f"type {arg.type.__name__!r} is not in seed_data and no injector "
+                f"is registered for that type name."
+            )
+        value = await self._invoke_call_with_args(arg.injector_fn, args=(), kwargs={})
+        if not isinstance(value, arg.type):
+            raise TypeError(
+                f"Injector for {arg.type.__name__!r} returned a value of type "
+                f"{type(value).__name__!r} which is not an instance of "
+                f"{arg.type.__name__!r}."
+            )
+        self.cache[arg.type] = value
+        return value
+
+    # --- Invoking functions with DI ---
+
+    async def _invoke_call_with_args(
+        self,
+        fn: Callable[..., Any],
+        args: tuple,
+        kwargs: dict[str, Any],
+    ) -> Any:
+        """Call `fn` with passthrough args/kwargs plus resolved Inject[T] args.
+
+        Python's call mechanism does the passthrough/keyword matching, default
+        filling, and conflict detection (e.g. caller kwargs cannot collide with
+        injected names — Python raises 'multiple values for keyword argument').
+        """
+        key = cache_key_for(fn)
+        if key in self.lock:
+            raise RecursionError(
+                f"Circular dependency detected: {_fn_name(fn)} is already being resolved."
+            )
+        self.lock.add(key)
+        try:
+            sig = self.injector.cached_call_with_args_signature(fn)
+            inject_kwargs: dict[str, Any] = {}
+            for arg in sig.injected_args:
+                inject_kwargs[arg.name] = await self._resolve_inject_arg(arg)
+            return await self._handle_result(fn(*args, **kwargs, **inject_kwargs))
+        finally:
+            self.lock.discard(key)
+
+    # --- Handling fn's return value (generator / async-generator / awaitable / value) ---
+
+    async def _handle_result(self, result: Any) -> Any:
+        """Process whatever the function returned.
+
+        - sync generator → take first yield, push to cleanup stack
+        - async generator → await first yield, push to cleanup stack
+        - awaitable (coroutine) → await it
+        - plain value → return as-is
+        """
+        if isgenerator(result):
+            gen = result
+            value = next(gen)
+            self.cleanup_stack.append(gen)
+            return value
+        if isasyncgen(result):
+            gen = result
+            value = await gen.__anext__()
+            self.cleanup_stack.append(gen)
+            return value
+        if isawaitable(result):
+            return await result
+        return result
+
+    # --- Cleanup at end of DI execution ---
+
+    async def _cleanup(self) -> None:
+        """Drain the cleanup stack in reverse order.
+
+        Each generator gets one more next/anext; we expect StopIteration /
+        StopAsyncIteration. Other exceptions are chained and re-raised after
+        all cleanups have run.
+        """
+        exception: BaseException | None = None
+        for gen in reversed(self.cleanup_stack):
+            try:
+                if isasyncgen(gen):
+                    await gen.__anext__()
+                else:
+                    next(gen)
+            except (StopIteration, StopAsyncIteration):
+                pass
+            except BaseException as new_exc:
+                if exception is not None:
+                    new_exc.__context__ = exception
+                exception = new_exc
+        self.cleanup_stack.clear()
+        if exception is not None:
+            raise exception
+
+
+def _fn_name(fn: Callable[..., Any]) -> str:
+    return getattr(fn, "__name__", repr(fn))