af-di-core 0.0.2__py3-none-any.whl

af_di_core-0.0.2.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: af-di-core
+Version: 0.0.2
+Summary: Reusable framework-agnostic DI container & @component auto-discovery
+License: MIT
+Author: Allfly
+Author-email: engineering@allfly.io
+Requires-Python: >=3.13,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: dependency-injector (>=4.48.1,<5.0.0)
+Requires-Dist: loguru (>=0.7.2,<0.8.0)
+Description-Content-Type: text/markdown
+
+# af-di-core
+
+A small, framework-agnostic dependency-injection framework for Python. Decorate your classes with `@component`, point the auto-discovery scanner at your package, and get a wired global container — no manual registration boilerplate. Works in a FastAPI app, a plain script, an AWS Lambda, or anywhere else.
+
+Built on [`dependency-injector`](https://python-dependency-injector.ets-labs.org/) for the underlying provider machinery.
+
+## Installation
+
+```bash
+pip install af-di-core
+# or with Poetry:
+poetry add af-di-core
+```
+
+## Quickstart
+
+Mark the classes you want managed with `@component` (pairs naturally with `@attrs.define`):
+
+```python
+import attrs
+from allfly.di.core import component
+
+
+@component
+@attrs.define
+class GreetingRepository:
+    def greeting(self) -> str:
+        return "hello"
+
+
+@component
+@attrs.define
+class GreetingService:
+    _repo: GreetingRepository
+
+    def greet(self) -> str:
+        return self._repo.greeting()
+```
+
+At startup, scan your package once and then resolve anything:
+
+```python
+from allfly.di.core import auto_discover_components, di_provide
+
+auto_discover_components(base_package="myapp")
+
+service = di_provide(GreetingService)   # GreetingRepository injected automatically
+service.greet()
+```
+
+Constructor dependencies are resolved from their type hints. Registration is multi-pass, so the order in which components are discovered does not matter. Parameters **with default values are treated as optional** and skipped, and an `Optional[T]` / `T | None` dependency is skipped when no provider for `T` exists.
+
+## How resolution works
+
+`auto_discover_components(base_package, registrars=None)` runs in three steps:
+
+1. **`@settings` functions** are registered first as singletons (see below).
+2. **`registrars`** — optional callbacks for manual singletons that need special construction (e.g. third-party clients) — are invoked.
+3. **`@component` classes** are registered with multi-pass dependency resolution.
+
+```python
+from allfly.di.core import auto_discover_components, di_register_singleton
+
+
+def register_external_clients() -> None:
+    di_register_singleton(SomeClient, api_key="...")
+
+
+auto_discover_components(base_package="myapp", registrars=[register_external_clients])
+```
+
+## Settings providers
+
+Use `@settings` on a function whose return type is the type to register. Combine with `functools.lru_cache` for single instantiation:
+
+```python
+from functools import lru_cache
+from allfly.di.core import settings
+
+
+@settings
+@lru_cache
+def get_db_settings() -> DatabaseSettings:
+    return DatabaseSettings()
+```
+
+The returned instance is registered as a singleton keyed by the return annotation, so any `@component` depending on `DatabaseSettings` receives it.
+
+## Core providers (app-supplied)
+
+`af-di-core` ships **no** opinionated providers — it is deliberately decoupled from databases, sessions, and web frameworks. Your application supplies its own "core" providers (things that must exist before anything is resolved, e.g. a DB session factory) by registering one or more callables on the container. They run **once**, lazily, the first time anything is provided:
+
+```python
+from allfly.di.core import register_core_provider, di_register, di_provide
+
+
+def register_db_providers() -> None:
+    di_register(DatabaseSettings, providers.Object(get_db_settings()))
+    di_register_singleton(SessionFactory, settings=get_provider(DatabaseSettings))
+
+
+register_core_provider(register_db_providers)
+
+# First di_provide(...) anywhere triggers ensure_core_providers() internally.
+di_provide(SessionFactory)
+```
+
+You can also drive this explicitly via `ensure_core_providers()`. Initialization is guarded by a lock and a one-time flag, so it is safe to call repeatedly. Register core providers at startup, before the first `di_provide`.
+
+## Public API
+
+```python
+from allfly.di.core import (
+    component,                       # class decorator → register for auto-discovery
+    settings,                        # function decorator → register a singleton by return type
+    auto_discover_components,        # scan a package and wire the container
+
+    di_provide,                      # resolve an instance by type
+    di_register,                     # register a raw dependency-injector provider
+    di_register_factory,             # register a Factory provider
+    di_register_singleton,           # register a Singleton provider
+    get_provider,                    # get the provider (not the instance) for chaining
+    provider_exists,                 # check whether a type is registered
+
+    register_core_provider,          # add an app-supplied core provider callable
+    ensure_core_providers,           # run core providers once (called lazily by di_provide)
+
+    get_global_container,            # the GlobalDependencyContainer singleton
+    dependency_container,            # alias for the same singleton
+    GlobalDependencyContainer,       # the container type
+    get_component_registry,          # introspection: everything @component/@settings collected
+    analyze_component_dependencies,  # introspection: a class's required constructor deps
+)
+```
+
+## FastAPI
+
+The framework intentionally does **not** import FastAPI. To expose a component to routes, write the small glue in your app:
+
+```python
+from typing import Annotated
+from fastapi import Depends, Request
+from allfly.di.core import get_global_container
+
+# Make the container available on app.state at startup:
+#   application.state.provide = get_global_container().provide
+
+def build(request: Request) -> GreetingService:
+    return request.app.state.provide(GreetingService)
+
+GreetingServiceDI = Annotated[GreetingService, Depends(build)]
+```
+
+## Logging
+
+The library logs through [loguru](https://github.com/Delgan/loguru) (mostly at `trace`/`debug`). If your app does not configure loguru, these messages are simply silent by default at higher levels.
+

af_di_core-0.0.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+allfly/di/core/__init__.py,sha256=Pe3oWMXkrvfg1f2kMUk33CY5e3igUf1YmufFdvbqkYM,960
+allfly/di/core/auto_discovery.py,sha256=0qS-EVQhM2rU8AVSPQcbWrH0c9_17Xc-Uq-c-51uQBg,9968
+allfly/di/core/container.py,sha256=27rNBgGfkGF_lOyNIJK753miW2kDonitQxAK869q6pk,3632
+allfly/di/core/decorators.py,sha256=IhAjykpQQFFAhcRvbp8bG5Y-H1HQe6QQyvDwLgr8TSk,2508
+allfly/di/core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+af_di_core-0.0.2.dist-info/METADATA,sha256=XHBtP5VtMyDT7jWCG9SBOpSx49gUdeediibg36yok90,6475
+af_di_core-0.0.2.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+af_di_core-0.0.2.dist-info/RECORD,,

af_di_core-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

allfly/di/core/__init__.py

@@ -0,0 +1,41 @@
+from allfly.di.core.auto_discovery import auto_discover_components
+from allfly.di.core.container import (
+    GlobalDependencyContainer,
+    dependency_container,
+    di_provide,
+    di_register,
+    di_register_factory,
+    di_register_singleton,
+    ensure_core_providers,
+    get_global_container,
+    get_provider,
+    provider_exists,
+    register_core_provider,
+)
+from allfly.di.core.decorators import (
+    analyze_component_dependencies,
+    component,
+    get_component_registry,
+    settings,
+)
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "GlobalDependencyContainer",
+    "analyze_component_dependencies",
+    "auto_discover_components",
+    "component",
+    "dependency_container",
+    "di_provide",
+    "di_register",
+    "di_register_factory",
+    "di_register_singleton",
+    "ensure_core_providers",
+    "get_component_registry",
+    "get_global_container",
+    "get_provider",
+    "provider_exists",
+    "register_core_provider",
+    "settings",
+]

allfly/di/core/auto_discovery.py

@@ -0,0 +1,269 @@
+import importlib
+import pkgutil
+import types
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Type, get_args, get_origin
+from typing import Union as TypingUnion
+
+from dependency_injector import providers
+from loguru import logger
+
+from allfly.di.core.container import (
+    GlobalDependencyContainer,
+    dependency_container,
+    di_register,
+    di_register_factory,
+    provider_exists,
+)
+from allfly.di.core.decorators import analyze_component_dependencies, get_component_registry
+
+
+@dataclass
+class DependencyAnalysis:
+    type: Type
+    available: bool
+    suggestion: str
+
+
+@dataclass
+class ComponentDependencyAnalysis:
+    dependencies: dict[str, DependencyAnalysis]
+
+    def get_missing_dependencies(self) -> dict[str, DependencyAnalysis]:
+        return {name: analysis for name, analysis in self.dependencies.items() if not analysis.available}
+
+    def get_available_dependencies(self) -> dict[str, DependencyAnalysis]:
+        return {name: analysis for name, analysis in self.dependencies.items() if analysis.available}
+
+    def has_missing_dependencies(self) -> bool:
+        return any(not analysis.available for analysis in self.dependencies.values())
+
+
+def auto_discover_components(
+    base_package: str = "src", registrars: list[Callable[[], None]] | None = None
+) -> GlobalDependencyContainer:
+    logger.info(f"Starting auto-discovery of components in package '{base_package}'")
+
+    _import_all_modules(base_package)
+
+    registry = get_component_registry()
+
+    function_components = [item for item in registry if callable(item) and not isinstance(item, type)]
+    class_components = [item for item in registry if isinstance(item, type)]
+
+    logger.trace(f"Found {len(function_components)} callable components and {len(class_components)} class components")
+
+    logger.trace(f"Step 1: Registering {len(function_components)} callable components")
+    for func in function_components:
+        _register_component_function(func)
+
+    if registrars:
+        logger.trace(f"Step 2: Calling {len(registrars)} custom registrar(s)")
+        for idx, registrar in enumerate(registrars, 1):
+            logger.trace(f"Calling registrar {idx}/{len(registrars)}: {registrar.__name__}")
+            try:
+                registrar()
+            except Exception as e:
+                logger.error(f"Failed to execute registrar {registrar.__name__}: {e}")
+                raise
+
+    logger.trace(f"Step 3: Registering {len(class_components)} class components")
+
+    registered_count = _register_component_classes_with_resolution(class_components)
+
+    logger.info(
+        f"Auto-discovery complete: {len(function_components)} functions + {registered_count} classes registered"
+    )
+    return dependency_container()
+
+
+def _import_all_modules(package_name: str) -> None:
+    try:
+        package = importlib.import_module(package_name)
+        package_path = getattr(package, "__path__", None)
+
+        if package_path is None:
+            return
+
+        for _, module_name, _ in pkgutil.walk_packages(package_path, package_name + "."):
+            try:
+                importlib.import_module(module_name)
+            except Exception as e:
+                logger.trace(f"Could not import module {module_name}: {e}")
+                continue
+
+    except Exception as e:
+        logger.warning(f"Could not scan package {package_name}: {e}")
+
+
+def _register_component(component_cls: Type) -> None:
+    dependencies = analyze_component_dependencies(component_cls)
+
+    if not dependencies:
+        di_register_factory(component_cls)
+        return
+
+    for param_name, param_type in dependencies.items():
+        base_type, is_optional = _unwrap_union_non_none(param_type)
+        if is_optional and not provider_exists(base_type):
+            continue
+        if not provider_exists(base_type):
+            available_types = _get_registered_types()
+            available_names = [_get_type_name(cls) for cls in available_types]
+            raise ValueError(
+                f"Cannot resolve dependency '{param_name}: {_get_type_name(param_type)}' for {component_cls.__name__}. "
+                f"Available types: {available_names}"
+            )
+
+    def lazy_factory():
+        container = dependency_container()
+        resolved_deps = {}
+        for item_name, item_type in dependencies.items():
+            base_type, is_optional = _unwrap_union_non_none(item_type)
+            if is_optional and not provider_exists(base_type):
+                continue
+            resolved_deps[item_name] = container.provide(base_type)
+        return component_cls(**resolved_deps)
+
+    factory_provider = providers.Callable(lazy_factory)
+    di_register(component_cls, factory_provider)
+
+
+def _unwrap_union_non_none(tp: type) -> tuple[type, bool]:
+    origin = None
+    try:
+        origin = get_origin(tp)
+    except Exception:
+        pass
+    if origin in (types.UnionType, TypingUnion):
+        args = get_args(tp)
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            return non_none[0], True
+    return tp, False
+
+
+def _get_registered_types() -> set[Type]:
+    try:
+        container = dependency_container()
+        return set(container.get_registry_keys())
+    except Exception:
+        return set()
+
+
+def _get_type_name(param_type: type) -> str:
+    if isinstance(param_type, types.UnionType):
+        args = get_args(param_type)
+        arg_names = [_get_type_name(arg) for arg in args]
+        return " | ".join(arg_names)
+    elif hasattr(param_type, "__name__"):
+        return param_type.__name__
+    elif hasattr(param_type, "_name"):
+        return param_type._name  # noqa: SLF001
+    else:
+        return str(param_type)
+
+
+def _register_component_function(func) -> None:
+    registration_type = getattr(func, "__di_registration_type__", None)
+    if not registration_type:
+        raise ValueError(f"Component function {func.__name__} missing __di_registration_type__ metadata")
+
+    try:
+        component_instance = func()
+        di_register(registration_type, providers.Object(component_instance))
+
+        logger.trace(f"Registered settings: {registration_type.__name__} from {func.__name__}()")
+    except Exception as e:
+        logger.error(f"Failed to register settings from {func.__name__}: {e}")
+        raise
+
+
+def _register_component_classes_with_resolution(class_components: list[Type]) -> int:
+    remaining_components = set(class_components)
+    registered_count = 0
+    pass_number = 1
+    max_passes = len(class_components) + 1
+
+    while remaining_components and pass_number <= max_passes:
+        logger.trace(f"Registration pass {pass_number}: {len(remaining_components)} components remaining")
+
+        registered_this_pass = []
+
+        for component_cls in list(remaining_components):
+            try:
+                _register_component(component_cls)
+                registered_this_pass.append(component_cls)
+                registered_count += 1
+                logger.trace(f"Successfully registered component: {component_cls.__name__}")
+            except Exception as e:
+                logger.trace(f"Pass {pass_number}: {component_cls.__name__} not ready: {e}")
+                continue
+
+        for component_cls in registered_this_pass:
+            remaining_components.remove(component_cls)
+
+        if not registered_this_pass:
+            logger.trace(f"No progress in pass {pass_number}, stopping registration")
+            break
+
+        pass_number += 1
+
+    if remaining_components:
+        _report_unregistered_components(remaining_components)
+
+    return registered_count
+
+
+def _report_unregistered_components(unregistered: set[Type]) -> None:
+    logger.warning(f"Could not register {len(unregistered)} components due to missing dependencies:")
+    logger.warning("")
+
+    for component_cls in unregistered:
+        analysis = _analyze_missing_dependencies(component_cls)
+
+        if not analysis.dependencies:
+            logger.warning(f"  - {component_cls.__name__} (could not analyze dependencies)")
+            continue
+
+        total_count = len(analysis.dependencies)
+
+        logger.warning(f"  - {component_cls.__name__} requires {total_count} dependencies:")
+
+        for param_name, dep_info in analysis.get_available_dependencies().items():
+            logger.warning(f"    ✓ {param_name}: {_get_type_name(dep_info.type)} (available)")
+
+        for param_name, dep_info in analysis.get_missing_dependencies().items():
+            suggestion = f" - {dep_info.suggestion}" if dep_info.suggestion else ""
+            logger.warning(f"    ✗ {param_name}: {_get_type_name(dep_info.type)} (not registered{suggestion})")
+
+        logger.warning("")
+
+    logger.warning("To fix these issues:")
+    logger.warning("  1. Add @component decorator to missing service/repository classes")
+    logger.warning("  2. Or register missing dependencies manually as singletons before discovery")
+    logger.warning("  3. Ensure all imported dependencies are accessible")
+
+
+def _analyze_missing_dependencies(component_cls: Type) -> ComponentDependencyAnalysis:
+    try:
+        dependencies = analyze_component_dependencies(component_cls)
+        registered_types = _get_registered_types()
+
+        analysis = {}
+        for param_name, param_type in dependencies.items():
+            is_available = param_type in registered_types
+
+            suggestion = ""
+            if not is_available:
+                type_name = _get_type_name(param_type)
+                suggestion = f"Register {type_name} with @component decorator or manually as a singleton"
+
+            analysis[param_name] = DependencyAnalysis(type=param_type, available=is_available, suggestion=suggestion)
+
+        return ComponentDependencyAnalysis(dependencies=analysis)
+
+    except Exception as e:
+        logger.error(f"Failed to analyze dependencies for {component_cls.__name__}: {e}")
+        return ComponentDependencyAnalysis(dependencies={})

allfly/di/core/container.py

@@ -0,0 +1,118 @@
+import threading
+from collections.abc import Callable
+from typing import Type, TypeVar
+
+from dependency_injector import containers, providers
+from loguru import logger
+
+T = TypeVar("T")
+
+
+class GlobalDependencyContainer(containers.DynamicContainer):
+    def __init__(self):
+        super().__init__()
+        self._type_registry: dict[Type, str] = {}
+        self._core_providers: list[Callable[[], None]] = []
+        self._core_providers_initialized = False
+        self._init_lock = threading.Lock()
+
+    def register(self, cls: Type[T], provider: providers.Provider):
+        name = f"_type_{cls.__module__}.{cls.__qualname__}"
+        self.set_provider(name, provider)
+        self._type_registry[cls] = name
+        logger.trace(f"Registered provider for {cls}")
+
+    def register_factory(self, cls: Type[T], **kwargs):
+        factory = providers.Factory(cls, **kwargs)
+        self.register(cls, factory)
+
+    def register_singleton(self, cls: Type[T], **kwargs):
+        singleton = providers.Singleton(cls, **kwargs)
+        self.register(cls, singleton)
+
+    def provide(self, cls: Type[T]) -> T:
+        name = self._type_registry.get(cls)
+        if not name:
+            raise KeyError(f"No provider for {cls}")
+        logger.trace(f"Providing {cls}")
+        return self.providers[name]()
+
+    def get_provider(self, cls: Type[T]) -> providers.Provider:
+        name = self._type_registry.get(cls)
+        if not name:
+            raise KeyError(f"No provider for {cls}")
+        return self.providers[name]
+
+    def get_registry_keys(self):
+        return self._type_registry.keys()
+
+    def get_registered_type_by_name(self, class_name: str) -> type | None:
+        for registered_class in self.get_registry_keys():
+            if registered_class.__name__ == class_name:
+                return registered_class
+        return None
+
+    def register_core_provider(self, registrar: Callable[[], None]) -> None:
+        self._core_providers.append(registrar)
+
+    def ensure_core_providers(self) -> None:
+        with self._init_lock:
+            if self._core_providers_initialized:
+                return
+
+            for registrar in self._core_providers:
+                registrar()
+
+            self._core_providers_initialized = True
+
+
+logger.debug("Creating global dependency container")
+__global_container = GlobalDependencyContainer()
+logger.debug("Global dependency container created")
+
+
+def dependency_container() -> GlobalDependencyContainer:
+    return __global_container
+
+
+def get_global_container() -> GlobalDependencyContainer:
+    return __global_container
+
+
+def register_core_provider(registrar: Callable[[], None]) -> None:
+    dependency_container().register_core_provider(registrar)
+
+
+def ensure_core_providers() -> None:
+    dependency_container().ensure_core_providers()
+
+
+def di_register(cls: Type[T], provider: providers.Provider):
+    dependency_container().register(cls, provider)
+
+
+def di_register_factory(cls: Type[T], **kwargs):
+    dependency_container().register_factory(cls, **kwargs)
+
+
+def di_register_singleton(cls: Type[T], **kwargs):
+    dependency_container().register_singleton(cls, **kwargs)
+
+
+def di_provide(cls: Type[T]) -> T:
+    ensure_core_providers()
+    try:
+        return dependency_container().provide(cls)
+    except KeyError as e:
+        logger.error(f"No provider for {cls}")
+        raise e
+
+
+def get_provider(cls: Type[T]) -> providers.Provider:
+    ensure_core_providers()
+    return dependency_container().get_provider(cls)
+
+
+def provider_exists(cls: Type[T]) -> bool:
+    ensure_core_providers()
+    return cls in dependency_container().get_registry_keys()

allfly/di/core/decorators.py

@@ -0,0 +1,86 @@
+import inspect
+from typing import Callable, Type, TypeVar, Union, get_type_hints
+
+from loguru import logger
+
+T = TypeVar("T")
+
+_component_registry: set[Union[Type, Callable]] = set()
+
+
+def component(cls: Type[T]) -> Type[T]:
+    logger.trace(f"Marking {cls.__name__} as component")
+
+    if not _has_valid_constructor(cls):
+        raise ValueError(f"@component class {cls.__name__} must have a proper __init__ method")
+
+    _component_registry.add(cls)
+
+    return cls
+
+
+def get_component_registry() -> set[Union[Type, Callable]]:
+    return _component_registry.copy()
+
+
+def analyze_component_dependencies(cls: Type) -> dict[str, Type]:
+    try:
+        type_hints = get_type_hints(cls.__init__)
+        function_signature = inspect.signature(cls.__init__)
+
+        dependencies = {}
+        for name, hint in type_hints.items():
+            if name in ("return", "self"):
+                continue
+
+            param = function_signature.parameters.get(name)
+            if param and param.default is not inspect.Parameter.empty:
+                logger.trace(f"Skipping {cls.__name__}.{name} - has default value")
+                continue
+
+            dependencies[name] = hint
+
+        logger.trace(f"Analyzed {cls.__name__} dependencies: {list(dependencies.keys())}")
+
+        return dependencies
+
+    except Exception as e:
+        raise ValueError(f"Failed to analyze dependencies for {cls.__name__}: {e}") from e
+
+
+def _has_valid_constructor(cls: Type) -> bool:
+    try:
+        init_method = getattr(cls, "__init__", None)
+        if not init_method or not callable(init_method):
+            return False
+
+        signature = inspect.signature(init_method)
+
+        params = list(signature.parameters.keys())
+        return len(params) >= 1 and params[0] == "self"
+
+    except Exception:
+        return False
+
+
+def settings(func: Callable) -> Callable:
+    registration_type = _extract_return_type(func)
+
+    if not registration_type:
+        raise ValueError(f"@settings on {func.__name__} requires a return type annotation")
+
+    func.__di_registration_type__ = registration_type
+
+    _component_registry.add(func)
+    logger.trace(f"Marked {func.__name__} as settings provider for {registration_type.__name__}")
+
+    return func
+
+
+def _extract_return_type(func: Callable) -> Type | None:
+    try:
+        hints = get_type_hints(func)
+        return hints.get("return")
+    except Exception as e:
+        logger.warning(f"Could not extract return type from {func.__name__}: {e}")
+        return None