stratae 0.0.1a0__py3-none-any.whl

stratae/__init__.py

@@ -0,0 +1,31 @@
+"""
+Stratae: Composable tools for building applications in Python.
+
+Stratae provides lightweight, high-performance tools for dependency injection,
+lifecycle management, and context variables. Built on Python's native features,
+it works anywhere: APIs, CLIs, workers, and tests.
+
+Quick example:
+    >>> from stratae.depends import Depends, inject
+    >>> from stratae.lifecycle import Lifecycle
+    >>>
+    >>> lifecycle = Lifecycle(['application', 'request'])
+    >>>
+    >>> @lifecycle.cache('application')
+    >>> def get_database():
+    ...     return Database(url="postgresql://...")
+    >>>
+    >>> @inject
+    >>> def create_user(name: str, db = Depends(get_database)):
+    ...     return db.users.create(name=name)
+    >>>
+    >>> with lifecycle.start('application'):
+    ...     with lifecycle.start('request'):
+    ...         user = create_user("Alice")
+
+Modules:
+    cache: Caching protocols and implementations
+    depends: Dependency injection and resolution
+    lifecycle: Scope-based caching and resource management
+    context: Context variables with nested scopes
+"""

stratae/cache/__init__.py

@@ -0,0 +1,8 @@
+"""Caching tools for managing single or multiple caches."""
+
+from stratae.cache.cache import Cache
+from stratae.cache.memory import MemoryCache
+from stratae.cache.thread import ThreadSafeMemoryCache
+from stratae.cache.util import get_function_key
+
+__all__ = ["Cache", "MemoryCache", "ThreadSafeMemoryCache", "get_function_key"]

stratae/cache/cache.py

@@ -0,0 +1,44 @@
+"""Protocol class for cache implementations."""
+
+from typing import Any, Awaitable, Callable, Hashable, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Cache(Protocol):
+    """Abstract base class for cache implementations."""
+
+    def has(self, key: Hashable) -> bool:
+        """Check if an item exists in the cache."""
+        ...
+
+    def get(self, key: Hashable, default: Any = ...) -> Any:
+        """Retrieve an item from the cache."""
+        ...
+
+    def get_or_set[T](self, key: Hashable, factory: Callable[[], T]) -> T:
+        """Get an item from the cache or set it using a factory function."""
+        ...
+
+    async def aget_or_set[T](self, key: Hashable, factory: Callable[[], Awaitable[T]]) -> T:
+        """Asynchronously get an item from the cache or set it using a factory function."""
+        ...
+
+    def set(self, key: Hashable, value: Any) -> None:
+        """Store an item in the cache."""
+        ...
+
+    def unset(self, key: Hashable) -> None:
+        """Unset a cached item."""
+        ...
+
+    def clear(self) -> None:
+        """Clear the cache."""
+        ...
+
+    async def aclear(self) -> None:
+        """Asynchronously clear the cache."""
+        ...
+
+    def is_empty(self) -> bool:
+        """Check if the cache is empty."""
+        ...

stratae/cache/memory.py

@@ -0,0 +1,64 @@
+"""In-memory cache implementation."""
+
+from typing import Any, Awaitable, Callable, Hashable
+
+
+class MemoryCache:
+    """A simple in-memory cache."""
+
+    _missing = object()
+
+    def __init__(self):
+        """Initialize the memory cache."""
+        self._cache: dict[Hashable, Any] = {}
+
+    def has(self, key: Hashable) -> bool:
+        """Check if an item exists in the cache."""
+        return key in self._cache
+
+    def get(self, key: Hashable, default: Any = _missing) -> Any:
+        """Retrieve an item from the cache."""
+        if key in self._cache:
+            return self._cache.get(key)
+        if default is not self._missing:
+            return default
+        raise KeyError(key)
+
+    def get_or_set[T](self, key: Hashable, factory: Callable[[], T]) -> T:
+        """Get an item from the cache or set it using a factory function."""
+        if key in self._cache:
+            return self._cache[key]
+        value = factory()
+        self.set(key, value)
+        return value
+
+    async def aget_or_set[T](self, key: Hashable, factory: Callable[[], Awaitable[T]]) -> T:
+        """Asynchronously get an item from the cache or set it using a factory function."""
+        if key in self._cache:
+            return self._cache[key]
+        value = await factory()
+        self.set(key, value)
+        return value
+
+    def set(self, key: Hashable, value: Any) -> None:
+        """Store an item in the cache."""
+        self._cache[key] = value
+
+    def unset(self, key: Hashable) -> None:
+        """Unset a cached item."""
+        if key in self._cache:
+            del self._cache[key]
+        else:
+            raise KeyError(key)
+
+    def clear(self) -> None:
+        """Clear the cache."""
+        self._cache.clear()
+
+    async def aclear(self) -> None:
+        """Asynchronously clear the cache."""
+        self.clear()
+
+    def is_empty(self) -> bool:
+        """Check if the cache is empty."""
+        return not self._cache

stratae/cache/thread.py

@@ -0,0 +1,62 @@
+"""Thread-Safe In-memory cache implementation."""
+
+import threading
+from typing import Any, Awaitable, Callable, Hashable
+
+from stratae.cache import MemoryCache
+
+
+class ThreadSafeMemoryCache:
+    """A thread-safe in-memory cache."""
+
+    _missing = object()
+
+    def __init__(self):
+        """Initialize the memory cache."""
+        self._cache = MemoryCache()
+        self._lock = threading.RLock()
+
+    def has(self, key: Hashable) -> bool:
+        """Check if an item exists in the cache."""
+        with self._lock:
+            return self._cache.has(key)
+
+    def get(self, key: Hashable, default: Any = _missing) -> Any:
+        """Retrieve an item from the cache."""
+        with self._lock:
+            if default is self._missing:
+                return self._cache.get(key)
+            return self._cache.get(key, default)
+
+    def get_or_set[T](self, key: Hashable, factory: Callable[[], T]) -> T:
+        """Get an item from the cache or set it using a factory function."""
+        with self._lock:
+            return self._cache.get_or_set(key, factory)
+
+    async def aget_or_set[T](self, key: Hashable, factory: Callable[[], Awaitable[T]]) -> T:
+        """Asynchronously get an item from the cache or set it using a factory function."""
+        raise NotImplementedError("ThreadSafeMemoryCache does not support async operations.")
+
+    def set(self, key: Hashable, value: Any) -> None:
+        """Store an item in the cache."""
+        with self._lock:
+            self._cache.set(key, value)
+
+    def unset(self, key: Hashable) -> None:
+        """Unset a cached item."""
+        with self._lock:
+            self._cache.unset(key)
+
+    def clear(self) -> None:
+        """Clear the cache."""
+        with self._lock:
+            self._cache.clear()
+
+    async def aclear(self) -> None:
+        """Asynchronously clear the cache."""
+        raise NotImplementedError("ThreadSafeMemoryCache does not support async operations.")
+
+    def is_empty(self) -> bool:
+        """Check if the cache is empty."""
+        with self._lock:
+            return self._cache.is_empty()

stratae/cache/util.py

@@ -0,0 +1,8 @@
+"""Utility functions for cache management."""
+
+from typing import Any, Awaitable, Callable, Hashable
+
+
+def get_function_key(func: Callable[..., Any] | Callable[..., Awaitable[Any]]) -> Hashable:
+    """Generate a unique key for a function based on its name and module."""
+    return (func.__module__, func.__qualname__, id(func))

stratae/context/__init__.py

@@ -0,0 +1,5 @@
+"""Context management utilities."""
+
+from .context import Context
+
+__all__ = ["Context"]

stratae/context/context.py

@@ -0,0 +1,58 @@
+"""Wrapper around contextvars for named context providers."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+
+
+class _ContextScope[T]:
+    """Stateful context manager for a single context value."""
+
+    def __init__(self, provider: Context[T], value: T):
+        """Initialize the context scope with provider and value."""
+        self._provider = provider
+        self._value = value
+        self._token: Token[T]
+
+    def __enter__(self):
+        """Enter the context, setting the value."""
+        self._token = self._provider.set(self._value)
+        return self._value
+
+    def __exit__(self, *_):
+        """Exit the context, resetting the value."""
+        self._provider.reset(self._token)
+
+
+class Context[T]:
+    """Named context provider using contextvars."""
+
+    def __init__(self, name: str):
+        """Initialize the ContextProvider with a name."""
+        self._name = name
+        self._var: ContextVar[T] = ContextVar(name)
+
+    def __call__(self) -> T:
+        """Get the current context value."""
+        try:
+            return self._var.get()
+        except LookupError as lookup_err:
+            raise RuntimeError(
+                f"Context '{self._name}' is not set. Use `with {self._name}.use(value):` to set it."
+            ) from lookup_err
+
+    def get(self, default: T | None = None) -> T | None:
+        """Get current value, or default if not set."""
+        return self._var.get(default)
+
+    def set(self, value: T) -> Token[T]:
+        """Set the context value."""
+        return self._var.set(value)
+
+    def reset(self, token: Token[T]) -> None:
+        """Reset the context value to a previous state."""
+        self._var.reset(token)
+
+    def use(self, value: T) -> _ContextScope[T]:
+        """Create a context scope for the given value."""
+        return _ContextScope(self, value)

stratae/depends/__init__.py

@@ -0,0 +1,13 @@
+"""Dependency Injection Module."""
+
+from stratae.depends.depends import AUTO, Depends, DependsWrapper
+from stratae.depends.inject import inject
+from stratae.depends.resolver import Resolver
+
+__all__ = [
+    "Resolver",
+    "AUTO",
+    "Depends",
+    "DependsWrapper",
+    "inject",
+]

stratae/depends/_wrappers.py

@@ -0,0 +1,124 @@
+"""Wrappers for dependency injection in synchronous and asynchronous functions."""
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, Generator
+
+from stratae.depends.exceptions import OverrideNotAllowedError
+
+if TYPE_CHECKING:
+    from stratae.depends.depends import DependsWrapper
+
+
+def create_sync_wrapper(
+    func: Callable[..., Any], resolved_deps: dict[str, DependsWrapper], no_override: set[str]
+) -> Callable[..., Any]:
+    """Create a synchronous wrapper function that injects resolved dependencies."""
+    deps_items = tuple(resolved_deps.items())
+
+    @wraps(func)
+    def sync_wrapper(*args: Any, **kwargs: Any):
+        if not kwargs:
+            return func(*args, **{k: v.provide() for k, v in deps_items})
+        if no_override and kwargs.keys() & no_override:
+            raise OverrideNotAllowedError(
+                "Overriding these dependencies is not allowed: "
+                f"{', '.join(k for k in kwargs if k in no_override)}"
+            )
+        return func(*args, **({k: v.provide() for k, v in deps_items if k not in kwargs} | kwargs))
+
+    return sync_wrapper
+
+
+def create_sync_gen_wrapper(
+    func: Callable[..., Any], resolved_deps: dict[str, DependsWrapper], no_override: set[str]
+) -> Callable[..., Any]:
+    """Create a synchronous generator wrapper function that injects resolved dependencies."""
+    deps_items = tuple(resolved_deps.items())
+
+    @wraps(func)
+    def sync_gen_wrapper(*args: Any, **kwargs: Any) -> Generator[Any, None, None]:
+        if not kwargs:
+            yield from func(*args, **{k: v.provide() for k, v in resolved_deps.items()})
+            return
+        if no_override and any(k in no_override for k in kwargs):
+            raise OverrideNotAllowedError(
+                "Overriding these dependencies is not allowed: "
+                f"{', '.join(k for k in kwargs if k in no_override)}"
+            )
+        yield from func(
+            *args, **({k: v.provide() for k, v in deps_items if k not in kwargs} | kwargs)
+        )
+
+    return sync_gen_wrapper
+
+
+def create_async_wrapper(
+    func: Callable[..., Any], resolved_deps: dict[str, DependsWrapper], no_override: set[str]
+) -> Callable[..., Any]:
+    """Create an asynchronous wrapper function that injects resolved dependencies."""
+    deps_items = tuple(resolved_deps.items())
+
+    @wraps(func)
+    async def async_wrapper(*args: Any, **kwargs: Any):
+        if not kwargs:
+            return await func(
+                *args,
+                **{k: await v.aprovide() if v.is_async else v.provide() for k, v in deps_items},
+            )
+        if no_override and kwargs.keys() & no_override:
+            raise OverrideNotAllowedError(
+                "Overriding these dependencies is not allowed: "
+                f"{', '.join(k for k in kwargs if k in no_override)}"
+            )
+        return await func(
+            *args,
+            **(
+                {
+                    k: await v.aprovide() if v.is_async else v.provide()
+                    for k, v in deps_items
+                    if k not in kwargs
+                }
+                | kwargs
+            ),
+        )
+
+    return async_wrapper
+
+
+def create_async_gen_wrapper(
+    func: Callable[..., Any], resolved_deps: dict[str, DependsWrapper], no_override: set[str]
+):
+    """Create an asynchronous generator wrapper function that injects resolved dependencies."""
+    deps_items = tuple(resolved_deps.items())
+
+    @wraps(func)
+    async def async_gen_wrapper(*args: Any, **kwargs: Any):
+        if not kwargs:
+            async for item in func(
+                *args,
+                **{k: await v.aprovide() if v.is_async else v.provide() for k, v in deps_items},
+            ):
+                yield item
+            return
+
+        if no_override and kwargs.keys() & no_override:
+            raise OverrideNotAllowedError(
+                "Overriding these dependencies is not allowed: "
+                f"{', '.join(k for k in kwargs if k in no_override)}"
+            )
+        async for item in func(
+            *args,
+            **(
+                {
+                    k: await v.aprovide() if v.is_async else v.provide()
+                    for k, v in deps_items
+                    if k not in kwargs
+                }
+                | kwargs
+            ),
+        ):
+            yield item
+
+    return async_gen_wrapper

stratae/depends/depends.py

@@ -0,0 +1,59 @@
+"""Depends function for dependency injection."""
+
+from inspect import iscoroutinefunction, unwrap
+from typing import Any, Awaitable, Callable, cast, overload
+
+AUTO: Any = None
+
+
+class DependsWrapper:
+    """Class used to wrap the dependency injection."""
+
+    def __init__(self, dependency: Callable[..., Any], allow_override: bool = True) -> None:
+        """Initialize the Depends instance with an injectable dependency."""
+        self.dependency = dependency
+        self._is_async = iscoroutinefunction(dependency)
+        self.allow_override = allow_override
+
+    def provide(self):
+        """Provide the dependency."""
+        self._fix_outermost()
+        self.provide = self._fixed_provide
+        return self.dependency()
+
+    async def aprovide(self):
+        """Asynchronously provide the dependency."""
+        self._fix_outermost()
+        self.aprovide = self._fixed_aprovide
+        return await self.dependency()
+
+    def _fixed_provide(self):
+        return self.dependency()
+
+    async def _fixed_aprovide(self):
+        return await self.dependency()
+
+    def _fix_outermost(self) -> None:
+        """Fix the dependency to use its outermost version, if applicable."""
+        original = unwrap(self.dependency)
+        if hasattr(original, "__outermost__"):
+            self.dependency = original.__outermost__
+        self._resolved_outermost = True
+
+    @property
+    def is_async(self) -> bool:
+        """Return True if the dependency is asynchronous, False otherwise."""
+        return self._is_async
+
+
+@overload
+def Depends[**P, R](dependency: Callable[P, Awaitable[R]], *, allow_override: bool = True) -> R: ...
+
+
+@overload
+def Depends[**P, R](dependency: Callable[P, R], *, allow_override: bool = True) -> R: ...
+
+
+def Depends[**P, R](dependency: Callable[P, R | Awaitable[R]], *, allow_override: bool = True) -> R:
+    """Marker function used to denote a dependency injection."""
+    return cast(R, DependsWrapper(dependency=dependency, allow_override=allow_override))

stratae/depends/exceptions.py

@@ -0,0 +1,21 @@
+"""Exceptions for errors in dependency injection."""
+
+
+class DependencyInjectionError(Exception):
+    """Base class for all dependency injection related exceptions."""
+
+
+class DIResolutionError(DependencyInjectionError):
+    """Exception raised when dependency resolution fails."""
+
+
+class CircularDependencyError(DependencyInjectionError):
+    """Exception raised when a circular dependency is detected."""
+
+
+class RegistrationError(DependencyInjectionError, ValueError):
+    """Exception raised when a registration error occurs in dependency resolution."""
+
+
+class OverrideNotAllowedError(DependencyInjectionError, RuntimeError):
+    """Exception raised when an override is attempted but not allowed."""

stratae/depends/inject.py

@@ -0,0 +1,49 @@
+"""
+Inject decorator to resolve and inject dependencies into functions.
+
+This module provides:
+- A global Resolver instance for managing dependencies.
+- The `inject` decorator for resolving and injecting dependencies into functions.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, overload
+
+from stratae.depends.resolver import Resolver
+
+_resolver = Resolver()
+
+
+def get_resolver() -> Resolver:
+    """Get the global dependency resolver."""
+    return _resolver
+
+
+@overload
+def inject[**P, R](func: Callable[P, R]) -> Callable[P, R]: ...
+
+
+@overload
+def inject[**P, R]() -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+
+@overload
+def inject[**P, R](func: Callable[P, R], *, allow_override: bool) -> Callable[P, R]: ...
+
+
+@overload
+def inject[**P, R](*, allow_override: bool) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+
+def inject[**P, R](
+    func: Callable[P, R] | None = None, *, allow_override: bool = True
+) -> Callable[P, R] | Callable[[Callable[P, R]], Callable[P, R]]:
+    """Inject decorator to resolve dependencies for a function."""
+
+    def decorator(f: Callable[P, R]) -> Callable[P, R]:
+        return get_resolver().resolve_function(f, allow_override=allow_override)
+
+    if func is None:
+        return decorator
+    return decorator(func)