pico-ioc 1.5.0__py3-none-any.whl → 2.0.1__py3-none-any.whl

pico_ioc-2.0.1.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: pico-ioc
+Version: 2.0.1
+Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 David Pérez Cabrera
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/dperezcabrera/pico-ioc
+Project-URL: Repository, https://github.com/dperezcabrera/pico-ioc
+Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-ioc/issues
+Keywords: ioc,di,dependency injection,inversion of control,decorator
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: yaml
+Requires-Dist: PyYAML; extra == "yaml"
+Provides-Extra: graphviz
+Requires-Dist: graphviz; extra == "graphviz"
+Dynamic: license-file
+
+# 📦 Pico-IoC: A Robust, Async-Native IoC Container for Python
+
+[![PyPI](https://img.shields.io/pypi/v/pico-ioc.svg)](https://pypi.org/project/pico-ioc/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-ioc)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-ioc/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-ioc/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-ioc)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+
+**Pico-IoC** is a **lightweight, async-ready, decorator-driven IoC container** built for clarity, testability, and performance.
+It brings *Inversion of Control* and *dependency injection* to Python in a deterministic, modern, and framework-agnostic way.
+
+> 🐍 Requires **Python 3.10+**
+
+---
+
+## ⚖️ Core Principles
+
+-   **Single Purpose** – Do one thing: dependency management.
+-   **Declarative** – Use simple decorators (`@component`, `@factory`, `@configuration`) instead of config files or YAML magic.
+-   **Deterministic** – No hidden scanning or side-effects; everything flows from an explicit `init()`.
+-   **Async-Native** – Fully supports async providers, async lifecycle hooks, and async interceptors.
+-   **Fail-Fast** – Detects missing bindings and circular dependencies at bootstrap.
+-   **Testable by Design** – Use `overrides` and `profiles` to swap components instantly.
+-   **Zero Core Dependencies** – Built entirely on the Python standard library. Optional features may require external packages (see Installation).
+
+---
+
+## 🚀 Why Pico-IoC?
+
+As Python systems evolve, wiring dependencies by hand becomes fragile and unmaintainable.
+**Pico-IoC** eliminates that friction by letting you declare how components relate — not how they’re created.
+
+| Feature        | Manual Wiring              | With Pico-IoC                   |
+| :------------- | :------------------------- | :------------------------------ |
+| Object creation| `svc = Service(Repo(Config()))` | `svc = container.get(Service)`  |
+| Replacing deps | Monkey-patch               | `overrides={Repo: FakeRepo()}`  |
+| Coupling       | Tight                      | Loose                           |
+| Testing        | Painful                    | Instant                         |
+| Async support  | Manual                     | Built-in                        |
+
+---
+
+## 🧩 Highlights (v2.0.0)
+
+-   **Full redesign:** unified architecture with simpler, more powerful APIs.
+-   **Async-aware AOP system** — method interceptors via `@intercepted_by`.
+-   **Typed configuration** — dataclasses with JSON/YAML/env sources.
+-   **Scoped resolution** — singleton, prototype, request, session, transaction.
+-   **UnifiedComponentProxy** — transparent lazy/AOP proxy supporting serialization.
+-   **Tree-based configuration runtime** with reusable adapters and discriminators.
+-   **Observable container context** with stats, health checks, and async cleanup.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pico-ioc
+```
+
+For optional features, you can install extras:
+
+  * **YAML Configuration:**
+
+    ```bash
+    pip install pico-ioc[yaml]
+    ```
+
+    (Requires `PyYAML`)
+
+  * **Dependency Graph Export:**
+
+    ```bash
+    pip install pico-ioc[graphviz]
+    ```
+
+    (Requires the `graphviz` Python package and the Graphviz command-line tools)
+
+-----
+
+## ⚙️ Quick Example
+
+```python
+from dataclasses import dataclass
+from pico_ioc import component, configuration, init
+
+@configuration
+@dataclass
+class Config:
+    db_url: str = "sqlite:///demo.db"
+
+@component
+class Repo:
+    def __init__(self, cfg: Config):
+        self.cfg = cfg
+    def fetch(self):
+        return f"fetching from {self.cfg.db_url}"
+
+@component
+class Service:
+    def __init__(self, repo: Repo):
+        self.repo = repo
+    def run(self):
+        return self.repo.fetch()
+
+container = init(modules=[__name__])
+svc = container.get(Service)
+print(svc.run())
+```
+
+**Output:**
+
+```
+fetching from sqlite:///demo.db
+```
+
+-----
+
+## 🧪 Testing with Overrides
+
+```python
+class FakeRepo:
+    def fetch(self): return "fake-data"
+
+container = init(modules=[__name__], overrides={Repo: FakeRepo()})
+svc = container.get(Service)
+assert svc.run() == "fake-data"
+```
+
+-----
+
+## 🩺 Lifecycle & AOP
+
+```python
+from pico_ioc import intercepted_by, MethodInterceptor, MethodCtx
+
+class LogInterceptor(MethodInterceptor):
+    def invoke(self, ctx: MethodCtx, call_next):
+        print(f"→ calling {ctx.name}")
+        res = call_next(ctx)
+        print(f"← {ctx.name} done")
+        return res
+
+@component
+class Demo:
+    @intercepted_by(LogInterceptor)
+    def work(self):
+        return "ok"
+
+c = init(modules=[__name__])
+c.get(Demo).work()
+```
+
+-----
+
+## 📖 Documentation
+
+The full documentation is available within the `docs/` directory of the project repository. Start with `docs/README.md` for navigation.
+
+  * **Getting Started:** `docs/getting-started.md`
+  * **User Guide:** `docs/user-guide/README.md`
+  * **Advanced Features:** `docs/advanced-features/README.md`
+  * **Observability:** `docs/observability/README.md`
+  * **Integrations:** `docs/integrations/README.md`
+  * **Cookbook (Patterns):** `docs/cookbook/README.md`
+  * **Architecture:** `docs/architecture/README.md`
+  * **API Reference:** `docs/api-reference/README.md`
+  * **ADR Index:** `docs/adr/README.md`
+
+-----
+
+## 🧩 Development
+
+```bash
+pip install tox
+tox
+```
+
+-----
+
+## 🧾 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) — *Full redesign for v2.0.0.*
+
+-----
+
+## 📜 License
+
+MIT — [LICENSE](https://opensource.org/licenses/MIT)
+

pico_ioc-2.0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+pico_ioc/__init__.py,sha256=AfHqcDJaXLChLJhxej_0gMClHUThUrKABFlIKYVrVtc,2198
+pico_ioc/_version.py,sha256=HVx0XJJ9OYFWBBPBCUFYb8Nm43ChPg9GZLh_dkxh9qI,22
+pico_ioc/aop.py,sha256=prFSlZC6vJYUfTbkMvlSc1T9UvvdEHr94Z0HAvjZ1fg,12985
+pico_ioc/api.py,sha256=Be3bFMPKtkFpHUuToEhDtSriVwyuBg1-b3vUs6WpsQ8,45753
+pico_ioc/config_runtime.py,sha256=z1cHDb5PbM8PMLYRFf5c2dmze8V22xwEzpWcBhtmMpA,11950
+pico_ioc/constants.py,sha256=AhIt0ieDZ9Turxb_YbNzj11wUbBbzjKfWh1BDlSx2Nw,183
+pico_ioc/container.py,sha256=5hLPwoVNY_PsN6XYbbZ6_j1I8IBnteCcahus1vCI_JY,17514
+pico_ioc/event_bus.py,sha256=E8Qb8KZ6K1CuXSbMlG0MNPHkGoWlssLLPzHq1QYdADQ,8346
+pico_ioc/exceptions.py,sha256=GT8flzyXeUWetguc8RRkB4p56waTXMdeNhSKQQ8rh4w,2468
+pico_ioc/factory.py,sha256=Q3aLwZ-MWbXKjm8unr871vlWSeVUDmzFQZ1mXzPkY5I,1557
+pico_ioc/locator.py,sha256=PBxZYO_xCOxG7aJZ0adDtINrJass_ZDNYmPD2O_oNqM,2401
+pico_ioc/scope.py,sha256=GDsDJWw7e5Vpiys-M4vQfKMJWSCiorRsT5cPo6z34Mk,5924
+pico_ioc-2.0.1.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_ioc-2.0.1.dist-info/METADATA,sha256=U6L0obv__5poIDJvadj9z9w56B1-1HWz8Q3yiCStFAI,8741
+pico_ioc-2.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-2.0.1.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-2.0.1.dist-info/RECORD,,

pico_ioc/_state.py

@@ -1,75 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from threading import RLock
-from contextvars import ContextVar
-from contextlib import contextmanager
-from typing import Optional, TYPE_CHECKING
-
-# Type-only import to avoid cycles
-if TYPE_CHECKING:
-    from .container import PicoContainer
-
-
-# ---- Task/process context for the active container ----
-
-@dataclass(frozen=True, slots=True)
-class ContainerContext:
-    """Immutable snapshot for the active container state."""
-    container: "PicoContainer"
-    fingerprint: tuple
-    root_name: Optional[str]
-
-
-# Process-wide fallback (for non-async code) guarded by a lock
-_lock = RLock()
-_current_context: Optional[ContainerContext] = None
-
-# Task-local context (for async isolation)
-_ctxvar: ContextVar[Optional[ContainerContext]] = ContextVar("pico_ioc_ctx", default=None)
-
-
-def get_context() -> Optional[ContainerContext]:
-    """Return the current context (task-local first, then process-global)."""
-    ctx = _ctxvar.get()
-    return ctx if ctx is not None else _current_context
-
-
-def set_context(ctx: Optional[ContainerContext]) -> None:
-    """Atomically set both task-local and process-global context."""
-    with _lock:
-        _ctxvar.set(ctx)
-        globals()["_current_context"] = ctx
-
-
-# Optional compatibility helpers (only used by legacy API paths)
-def get_fingerprint() -> Optional[tuple]:
-    ctx = get_context()
-    return ctx.fingerprint if ctx else None
-
-
-def set_fingerprint(fp: Optional[tuple]) -> None:
-    """Compatibility shim: setting None clears the active context."""
-    if fp is None:
-        set_context(None)
-        return
-    ctx = get_context()
-    if ctx is not None:
-        set_context(ContainerContext(container=ctx.container, fingerprint=fp, root_name=ctx.root_name))
-
-
-# ---- Scan/resolve guards (kept as-is) ----
-
-_scanning: ContextVar[bool] = ContextVar("pico_scanning", default=False)
-_resolving: ContextVar[bool] = ContextVar("pico_resolving", default=False)
-
-
-@contextmanager
-def scanning_flag():
-    """Mark scanning=True within the block."""
-    tok = _scanning.set(True)
-    try:
-        yield
-    finally:
-        _scanning.reset(tok)
-

pico_ioc/builder.py

@@ -1,210 +0,0 @@
-from __future__ import annotations
-import inspect as _inspect
-import logging
-import os
-from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple
-from typing import get_origin, get_args, Annotated
-
-from .interceptors import MethodInterceptor, ContainerInterceptor
-from .container import PicoContainer, _is_compatible
-from .policy import apply_policy, _conditional_active
-from .plugins import PicoPlugin, run_plugin_hook
-from .scanner import scan_and_configure
-from .resolver import Resolver, _get_hints
-from . import _state
-from .config import ConfigRegistry
-
-class PicoContainerBuilder:
-    def __init__(self):
-        self._scan_plan: List[Tuple[Any, Optional[Callable[[str], bool]], Tuple[PicoPlugin, ...]]] = []
-        self._overrides: Dict[Any, Any] = {}
-        self._profiles: Optional[List[str]] = None
-        self._plugins: Tuple[PicoPlugin, ...] = ()
-        self._include_tags: Optional[set[str]] = None
-        self._exclude_tags: Optional[set[str]] = None
-        self._roots: Iterable[type] = ()
-        self._providers: Dict[Any, Dict] = {}
-        self._eager: bool = True
-        self._config_registry: ConfigRegistry | None = None
-
-    def with_config(self, registry: ConfigRegistry) -> "PicoContainerBuilder":
-        self._config_registry = registry
-        return self
-
-    def with_plugins(self, plugins: Tuple[PicoPlugin, ...]) -> "PicoContainerBuilder":
-        self._plugins = plugins or ()
-        return self
-
-    def with_profiles(self, profiles: Optional[List[str]]) -> "PicoContainerBuilder":
-        self._profiles = profiles
-        return self
-
-    def add_scan_package(self, package: Any, exclude: Optional[Callable[[str], bool]] = None) -> "PicoContainerBuilder":
-        self._scan_plan.append((package, exclude, self._plugins))
-        return self
-
-    def with_overrides(self, overrides: Optional[Dict[Any, Any]]) -> "PicoContainerBuilder":
-        self._overrides = overrides or {}
-        return self
-
-    def with_tag_filters(self, include: Optional[set[str]], exclude: Optional[set[str]]) -> "PicoContainerBuilder":
-        self._include_tags = include
-        self._exclude_tags = exclude
-        return self
-
-    def with_roots(self, roots: Iterable[type]) -> "PicoContainerBuilder":
-        self._roots = roots or ()
-        return self
-
-    def with_eager(self, eager: bool) -> "PicoContainerBuilder":
-        self._eager = bool(eager)
-        return self
-
-    def build(self) -> PicoContainer:
-        requested_profiles = _resolve_profiles(self._profiles)
-        container = PicoContainer(providers=self._providers)
-        container._active_profiles = tuple(requested_profiles)
-        setattr(container, "_config_registry", self._config_registry)
-        all_infras: list[tuple[type, dict]] = []
-        for pkg, exclude, scan_plugins in self._scan_plan:
-            with _state.scanning_flag():
-                c, f, infra_decls = scan_and_configure(pkg, container, exclude=exclude, plugins=scan_plugins)
-                logging.info("Scanned '%s' (components: %d, factories: %d)", getattr(pkg, "__name__", pkg), c, f)
-                all_infras.extend(infra_decls)
-        _run_infrastructure(container=container, infra_decls=all_infras, profiles=requested_profiles)
-        binder = container.binder()
-        if self._overrides:
-            _apply_overrides(container, self._overrides)
-        run_plugin_hook(self._plugins, "after_bind", container, binder)
-        run_plugin_hook(self._plugins, "before_eager", container, binder)
-        apply_policy(container, profiles=requested_profiles)
-        _filter_by_tags(container, self._include_tags, self._exclude_tags)
-        if self._roots:
-            _restrict_to_subgraph(container, self._roots, self._overrides)
-        run_plugin_hook(self._plugins, "after_ready", container, binder)
-        if self._eager:
-            container.eager_instantiate_all()
-        logging.info("Container configured and ready.")
-        return container
-
-def _resolve_profiles(profiles: Optional[List[str]]) -> List[str]:
-    if profiles is not None:
-        return list(profiles)
-    env_val = os.getenv("PICO_PROFILE", "")
-    return [p.strip() for p in env_val.split(",") if p.strip()]
-
-def _as_provider(val):
-    if isinstance(val, tuple) and len(val) == 2 and callable(val[0]) and isinstance(val[1], bool):
-        return val[0], val[1]
-    if callable(val):
-        return val, False
-    return (lambda v=val: v), False
-
-def _apply_overrides(container: PicoContainer, overrides: Dict[Any, Any]) -> None:
-    for key, val in overrides.items():
-        provider, lazy = _as_provider(val)
-        container.bind(key, provider, lazy=lazy)
-
-def _filter_by_tags(container: PicoContainer, include_tags: Optional[set[str]], exclude_tags: Optional[set[str]]) -> None:
-    if not include_tags and not exclude_tags:
-        return
-    def _tag_ok(meta: dict) -> bool:
-        tags = set(meta.get("tags", ()))
-        if include_tags and not tags.intersection(include_tags):
-            return False
-        if exclude_tags and tags.intersection(exclude_tags):
-            return False
-        return True
-    container._providers = {k: v for k, v in container._providers.items() if _tag_ok(v)}
-
-def _compute_allowed_subgraph(container: PicoContainer, roots: Iterable[type]) -> set:
-    allowed: set[Any] = set(roots)
-    stack = list(roots or ())
-    def _add_impls_for_base(base_t):
-        for prov_key, meta in container._providers.items():
-            cls = prov_key if isinstance(prov_key, type) else None
-            if cls is not None and _is_compatible(cls, base_t):
-                if prov_key not in allowed:
-                    allowed.add(prov_key)
-                    stack.append(prov_key)
-    while stack:
-        k = stack.pop()
-        allowed.add(k)
-        if isinstance(k, type):
-            _add_impls_for_base(k)
-        cls = k if isinstance(k, type) else None
-        if cls is None or not container.has(k):
-            continue
-        try:
-            sig = _inspect.signature(cls.__init__)
-            hints = _get_hints(cls.__init__, owner_cls=cls)
-        except Exception:
-            continue
-        for pname, param in sig.parameters.items():
-            if pname == "self":
-                continue
-            ann = hints.get(pname, param.annotation)
-            origin = get_origin(ann) or ann
-            if origin in (list, tuple):
-                inner = (get_args(ann) or (object,))[0]
-                if get_origin(inner) is Annotated:
-                    inner = (get_args(inner) or (object,))[0]
-                if isinstance(inner, type):
-                    if inner not in allowed:
-                        stack.append(inner)
-                continue
-            if isinstance(ann, type) and ann not in allowed:
-                stack.append(ann)
-            elif container.has(pname) and pname not in allowed:
-                stack.append(pname)
-    return allowed
-
-def _restrict_to_subgraph(container: PicoContainer, roots: Iterable[type], overrides: Optional[Dict[Any, Any]]) -> None:
-    allowed = _compute_allowed_subgraph(container, roots)
-    keep_keys: set[Any] = allowed | (set(overrides.keys()) if overrides else set())
-    container._providers = {k: v for k, v in container._providers.items() if k in keep_keys}
-
-def _run_infrastructure(*, container: PicoContainer, infra_decls: List[tuple[type, dict]], profiles: List[str]) -> None:
-    def _active(meta: dict) -> bool:
-        profs = tuple(meta.get("profiles", ())) or ()
-        if profs and (not profiles or not any(p in profs for p in profiles)):
-            return False
-        req_env = tuple(meta.get("require_env", ())) or ()
-        if req_env:
-            import os
-            if not all(os.getenv(k) not in (None, "") for k in req_env):
-                return False
-        pred = meta.get("predicate", None)
-        if callable(pred):
-            try:
-                if not bool(pred()):
-                    return False
-            except Exception:
-                return False
-        return True
-    from .resolver import Resolver
-    from .infra import Infra
-    resolver = Resolver(container)
-    active_infras: List[tuple[int, type]] = []
-    for cls, meta in infra_decls:
-        if not _active(meta):
-            continue
-        order = int(meta.get("order", 0))
-        active_infras.append((order, cls))
-    active_infras.sort(key=lambda t: (t[0], getattr(t[1], "__qualname__", "")))
-    for _ord, cls in active_infras:
-        try:
-            inst = resolver.create_instance(cls)
-        except Exception:
-            import logging
-            logging.exception("Failed to construct infrastructure %r", cls)
-            continue
-        infra = Infra(container=container, profiles=tuple(profiles))
-        fn = getattr(inst, "configure", None)
-        if callable(fn):
-            try:
-                fn(infra)
-            except Exception:
-                import logging
-                logging.exception("Infrastructure configure() failed for %r", cls)
-