pico-ioc 1.4.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

pico_ioc/scanner.py

@@ -1,203 +0,0 @@
-# src/pico_ioc/scanner.py
-from __future__ import annotations
-
-import importlib
-import inspect
-import logging
-import pkgutil
-from types import ModuleType
-from typing import Any, Callable, Optional, Tuple, List, Iterable
-
-from .plugins import run_plugin_hook, PicoPlugin
-from .container import PicoContainer, Binder
-from .decorators import (
-    COMPONENT_FLAG,
-    COMPONENT_KEY,
-    COMPONENT_LAZY,
-    FACTORY_FLAG,
-    PROVIDES_KEY,
-    PROVIDES_LAZY,
-    COMPONENT_TAGS,
-    PROVIDES_TAGS,
-    INTERCEPTOR_META,
-)
-from .proxy import ComponentProxy
-from .resolver import Resolver
-from . import _state
-from .utils import _provider_from_class, _provider_from_callable
-from .config import is_config_component, build_component_instance, ConfigRegistry
-
-
-def scan_and_configure(
-    package_or_name: Any,
-    container: PicoContainer,
-    *,
-    exclude: Optional[Callable[[str], bool]] = None,
-    plugins: Tuple[PicoPlugin, ...] = (),
-) -> tuple[int, int, list[tuple[Any, dict]]]:
-    """
-    Scan a package, bind components/factories, and collect interceptor declarations.
-
-    Returns: (component_count, factory_count, interceptor_decls)
-      - interceptor_decls entries:
-          (cls, meta)                        for @interceptor class
-          (fn, meta)                         for @interceptor function
-          ((owner_cls, fn), meta)            for @interceptor methods
-    """
-    package = _as_module(package_or_name)
-    logging.info("Scanning in '%s'...", getattr(package, "__name__", repr(package)))
-
-    binder = Binder(container)
-    resolver = Resolver(container)
-
-    run_plugin_hook(plugins, "before_scan", package, binder)
-
-    comp_classes, factory_classes, interceptor_decls = _collect_decorated(
-        package=package,
-        exclude=exclude,
-        plugins=plugins,
-        binder=binder,
-    )
-
-    run_plugin_hook(plugins, "after_scan", package, binder)
-
-    _register_component_classes(classes=comp_classes, container=container, resolver=resolver)
-    _register_factory_classes(factory_classes=factory_classes, container=container, resolver=resolver)
-
-    return len(comp_classes), len(factory_classes), interceptor_decls
-
-
-# -------------------- helpers --------------------
-
-def _as_module(package_or_name: Any) -> ModuleType:
-    if isinstance(package_or_name, str):
-        return importlib.import_module(package_or_name)
-    if hasattr(package_or_name, "__spec__"):
-        return package_or_name  # type: ignore[return-value]
-    raise TypeError("package_or_name must be a module or importable package name (str).")
-
-
-def _iter_package_modules(package: ModuleType) -> Iterable[str]:
-    """Yield fully-qualified module names under a package (recursive)."""
-    try:
-        pkg_path = package.__path__  # type: ignore[attr-defined]
-    except Exception:
-        return
-    prefix = package.__name__ + "."
-    for _finder, name, _is_pkg in pkgutil.walk_packages(pkg_path, prefix):
-        yield name
-
-
-def _collect_decorated(
-    *,
-    package: ModuleType,
-    exclude: Optional[Callable[[str], bool]],
-    plugins: Tuple[PicoPlugin, ...],
-    binder: Binder,
-) -> Tuple[List[type], List[type], List[tuple[Any, dict]]]:
-    comps: List[type] = []
-    facts: List[type] = []
-    interceptors: List[tuple[Any, dict]] = []
-
-    def _collect_from_class(cls: type):
-        if getattr(cls, COMPONENT_FLAG, False):
-            comps.append(cls)
-        elif getattr(cls, FACTORY_FLAG, False):
-            facts.append(cls)
-
-        meta_class = getattr(cls, INTERCEPTOR_META, None)
-        if meta_class:
-            interceptors.append((cls, dict(meta_class)))
-
-        for _nm, fn in inspect.getmembers(cls, predicate=inspect.isfunction):
-            meta_m = getattr(fn, INTERCEPTOR_META, None)
-            if meta_m:
-                interceptors.append(((cls, fn), dict(meta_m)))
-
-    def _visit_module(module: ModuleType):
-        for _name, obj in inspect.getmembers(module, inspect.isclass):
-            run_plugin_hook(plugins, "visit_class", module, obj, binder)
-            _collect_from_class(obj)
-
-        for _name, fn in inspect.getmembers(module, predicate=inspect.isfunction):
-            meta = getattr(fn, INTERCEPTOR_META, None)
-            if meta:
-                interceptors.append((fn, dict(meta)))
-
-    for mod_name in _iter_package_modules(package):
-        if exclude and exclude(mod_name):
-            logging.info("Skipping module %s (excluded)", mod_name)
-            continue
-        try:
-            module = importlib.import_module(mod_name)
-        except Exception as e:
-            logging.warning("Module %s not processed: %s", mod_name, e)
-            continue
-        _visit_module(module)
-
-    if not hasattr(package, "__path__"):
-        _visit_module(package)
-
-    return comps, facts, interceptors
-
-
-def _register_component_classes(
-    *,
-    classes: List[type],
-    container: PicoContainer,
-    resolver: Resolver,
-) -> None:
-    for cls in classes:
-        key = getattr(cls, COMPONENT_KEY, cls)
-        is_lazy = bool(getattr(cls, COMPONENT_LAZY, False))
-        tags = tuple(getattr(cls, COMPONENT_TAGS, ()))
-        if is_config_component(cls):
-            registry: ConfigRegistry | None = getattr(container, "_config_registry", None)
-            def _prov(_c=cls, _reg=registry):
-                if _reg is None:
-                    raise RuntimeError(f"No config registry found to build {_c.__name__}")
-                return build_component_instance(_c, _reg)
-            provider = (lambda p=_prov: ComponentProxy(p)) if is_lazy else _prov
-        else:
-            provider = _provider_from_class(cls, resolver=resolver, lazy=is_lazy)
-        container.bind(key, provider, lazy=is_lazy, tags=tags)
-
-
-def _register_factory_classes(
-    *,
-    factory_classes: List[type],
-    container: PicoContainer,
-    resolver: Resolver,
-) -> None:
-    for fcls in factory_classes:
-        try:
-            tok_res = _state._resolving.set(True)
-            try:
-                finst = resolver.create_instance(fcls)
-            finally:
-                _state._resolving.reset(tok_res)
-        except Exception:
-            logging.exception("Error in factory %s", fcls.__name__)
-            continue
-
-        for attr_name, func in inspect.getmembers(fcls, predicate=inspect.isfunction):
-            provided_key = getattr(func, PROVIDES_KEY, None)
-            if provided_key is None:
-                continue
-
-            is_lazy = bool(getattr(func, PROVIDES_LAZY, False))
-            tags = tuple(getattr(func, PROVIDES_TAGS, ()))
-
-            bound = getattr(finst, attr_name, func.__get__(finst, fcls))
-            prov = _provider_from_callable(bound, owner_cls=fcls, resolver=resolver, lazy=is_lazy)
-
-            if isinstance(provided_key, type):
-                try:
-                    setattr(prov, "_pico_alias_for", provided_key)
-                except Exception:
-                    pass
-                unique_key = (provided_key, f"{fcls.__name__}.{attr_name}")
-                container.bind(unique_key, prov, lazy=is_lazy, tags=tags)
-            else:
-                container.bind(provided_key, prov, lazy=is_lazy, tags=tags)
-

pico_ioc/utils.py

@@ -1,25 +0,0 @@
-# src/pico_ioc/utils.py
-from typing import Any, Callable
-from .container import PicoContainer
-from .proxy import ComponentProxy
-
-def _wrap_if_lazy(provider: Callable, is_lazy: bool) -> Callable:
-    """Wraps a provider in a ComponentProxy if it's marked as lazy."""
-    return (lambda: ComponentProxy(provider)) if is_lazy else provider
-
-def _provider_from_class(cls: type, *, resolver, lazy: bool):
-    def _new():
-        return resolver.create_instance(cls)
-    return _wrap_if_lazy(_new, lazy)
-
-def _provider_from_callable(fn, *, owner_cls, resolver, lazy: bool):
-    def _invoke():
-        kwargs = resolver.kwargs_for_callable(fn, owner_cls=owner_cls)
-        return fn(**kwargs)
-    return _wrap_if_lazy(_invoke, lazy)
-        
-def create_alias_provider(container: PicoContainer, target_key: Any) -> Callable[[], Any]:
-    """Creates a provider that delegates the get() call to the container for another key."""
-    def _provider():
-        return container.get(target_key)
-    return _provider

pico_ioc-1.4.0.dist-info/METADATA

@@ -1,241 +0,0 @@
-Metadata-Version: 2.4
-Name: pico-ioc
-Version: 1.4.0
-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: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# 📦 Pico-IoC: A Minimalist 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 **tiny, zero-dependency, decorator-based IoC container for Python**.  
-It helps you build loosely-coupled, testable apps without manual wiring. Inspired by the Spring ecosystem, but minimal.
-
-> ⚠️ **Requires Python 3.10+** (uses `typing.Annotated` and `include_extras=True`).
-
----
-
-## ⚖️ Principles
-
-* **Focus & Simplicity**: A minimal core for one job: managing dependencies. It avoids accidental complexity by doing one thing well.
-* **Predictable & Explicit**: No magic. Behavior is deterministic, relying on explicit decorators and a clear resolution order.
-* **Unified Composition Root**: The application is assembled from a single entry point (`init`) which defines a clear, predictable boundary. This ensures a stable and understandable bootstrap process.
-* **Fail-Fast Bootstrap**: Catches dependency graph errors at startup, not in production. If the application runs, it's wired correctly.
-* **Testability First**: Features like `scope()` and `overrides` are first-class citizens, enabling fast and isolated testing.
-* **Extensible by Design**: Lifecycle hooks and AOP are available through a clean Plugin and Interceptor API without altering the core.
-* **Framework Agnostic**: Zero hard dependencies. It works with any Python application, from simple scripts to complex web servers.
-
----
-
-## ✨ Why Pico-IoC?
-
-`pico-ioc` exists to solve a common problem that arises as Python applications grow: managing how objects are created and connected becomes complex and brittle. This manual wiring, where a change deep in the application can cause a cascade of updates, makes the code hard to test and maintain. `pico-ioc` introduces the principle of Inversion of Control (IoC) in a simple, Pythonic way. Instead of you creating and connecting every object, you declare your components with a simple `@component` decorator, and the container automatically wires them together based on their type hints. It brings the architectural robustness and testability of mature frameworks like Spring to the Python ecosystem, but without the heavy boilerplate, allowing you to build complex, loosely-coupled applications that remain simple to manage.
-
-
-| Feature             | Manual Wiring                                     | With Pico-IoC                   |
-| :------------------ | :------------------------------------------------ | :------------------------------ |
-| **Object Creation** | `service = Service(Repo(Config()))`               | `svc = container.get(Service)`  |
-| **Testing**         | Manual replacement or monkey-patching             | `overrides={Repo: FakeRepo()}`  |
-| **Coupling**        | High (code knows about constructors)              | Low (code just asks for a type) |
-| **Maintenance**     | Brittle (changing a constructor breaks consumers) | Robust (changes are isolated)   |
-| **Learning Curve**  | Ad-hoc, implicit patterns                         | Uniform, explicit, documented   |
-
-
----
-
-## 🧩 Features
-
-### Core
-
-* **Zero dependencies** — pure Python, framework-agnostic.
-* **Single Entry Point (`init`)** — Robustly bootstrap your entire application from a single root package, enforcing a clean "Composition Root" pattern.
-* **Decorator API** — `@component`, `@factory_component`, `@provides`, `@plugin`.
-* **Fail-fast bootstrap** — eager by default; missing deps surface at startup.
-* **Opt-in lazy** — `lazy=True` wraps with `ComponentProxy`.
-* **Smart resolution order** — parameter name → type annotation → MRO → string.
-* **Overrides for testing** — inject mocks/fakes directly via `init(overrides={...})`.
-* **Public API helper** — auto-export decorated symbols in `__init__.py`.
-* **Thread/async safe** — isolation via `ContextVar`.
-
-### Advanced
-
-* **Qualifiers & collections** — `list[Annotated[T, Q]]` filters by qualifier.
-* **Flexible Scopes (`scope`)** — Create lightweight, temporary containers from multiple modules, ideal for testing, scripting, or modular tasks.
-* **Interceptors API** — observe/modify resolution, instantiation, invocation, errors.
-* **Conditional providers** — activate components by env vars or predicates.
-* **Plugins** — lifecycle hooks (`before_scan`, `after_ready`).
-
----
-
-## 📦 Installation
-
-```bash
-# Requires Python 3.10+
-pip install pico-ioc
-````
-
----
-
-## 🚀 Quick start
-
-```python
-from pico_ioc import component, init
-
-@component
-class Config:
-    url = "sqlite:///demo.db"
-
-@component
-class Repo:
-    def __init__(self, cfg: Config):
-        self.url = cfg.url
-    def fetch(self): return f"fetching from {self.url}"
-
-@component
-class Service:
-    def __init__(self, repo: Repo):
-        self.repo = repo
-    def run(self): return self.repo.fetch()
-
-# bootstrap
-import myapp
-c = init(myapp)
-svc = c.get(Service)
-print(svc.run())
-```
-
-**Output:**
-
-```
-fetching from sqlite:///demo.db
-```
----
-
-### Quick overrides for testing
-
-```python
-from pico_ioc import init
-import myapp
-
-fake = {"repo": "fake-data"}
-c = init(myapp, overrides={
-    "fast_model": fake,                  # constant instance
-    "user_service": lambda: {"id": 1},   # provider
-})
-assert c.get("fast_model") == {"repo": "fake-data"}
-```
----
-
-### Scoped subgraphs
-
-For unit tests or lightweight integration, you can bootstrap **only a subset of the graph**.
-
-```python
-from pico_ioc
-from src.runner_service import RunnerService
-from tests.fakes import FakeDocker
-import src
-
-c = pico_ioc.scope(
-    modules=[src],
-    roots=[RunnerService],  # only RunnerService and its deps
-    overrides={
-        "docker.DockerClient": FakeDocker(),
-    },
-    strict=True,   # fail if something is missing
-    lazy=True,     # instantiate on demand
-)
-svc = c.get(RunnerService)
-```
-
-This way you don’t need to bootstrap your entire app (`controllers`, `http`, …) just to test one service.
-
----
-## 📖 Documentation
-
-  * **🚀 New to pico-ioc? Start with the User Guide.**
-      * [**GUIDE.md**](.llm/GUIDE.md) — Learn with practical examples: testing, configuration, collection injection, and web framework integration.
-
-  * **🏗️ Want to understand the internals? See the Architecture.**
-      * [**ARCHITECTURE.md**](.llm/ARCHITECTURE.md) — A deep dive into the algorithms, lifecycle, and internal diagrams. Perfect for contributors.
-
-  * **🤔 Want to know *why* it's designed this way? Read the Decisions.**
-      * [**DECISIONS.md**](.llm/DECISIONS.md) — The history and rationale behind key technical decisions.
-
-  * **💡 Just need a quick summary?**
-      * [**OVERVIEW.md**](.llm/OVERVIEW.md) — What pico-ioc is and why you should use it.
----
-
-## 🧪 Development
-
-```bash
-pip install tox
-tox
-```
-
----
-
-## 📜 Overview
-
-See [OVERVIEW.md](.llm/OVERVIEW.md) Just need a quick summary?
-
----
-
-## 📜 Changelog
-
-See [CHANGELOG.md](./CHANGELOG.md) for version history.
-
----
-
-## 📜 License
-
-MIT — see [LICENSE](https://opensource.org/licenses/MIT)
-
-
-

pico_ioc-1.4.0.dist-info/RECORD

@@ -1,22 +0,0 @@
-pico_ioc/__init__.py,sha256=s_9v-pMM5X7r5vhbzaOmQQEHBLOmZCV7o6QNtRcfMAU,1282
-pico_ioc/_state.py,sha256=C98XQZIfKy98j8fzR730eUCoqSnCkRkxUS4bH7mp73c,2154
-pico_ioc/_version.py,sha256=EyMGX1ADFzN6XVXHWbJUtKPONYKeFkvWoKIFPDDB2I8,22
-pico_ioc/api.py,sha256=cc9c3db6_dIfeobP_VvFRpNV9qNIsIPbUct5X9mmW9w,8348
-pico_ioc/builder.py,sha256=ZvIpOaAzBpByw-u5V52GM5cJAMH_E_5FMDLlgyqd-g4,11379
-pico_ioc/config.py,sha256=J3k7_2vRB2HCpikzeMzT4Ut9COFM4kcydkwZorncqSk,12317
-pico_ioc/container.py,sha256=V9X0qvNPZYU80C65X3Dqifek6RWt9kgEwG0CkX1Hpow,6461
-pico_ioc/decorators.py,sha256=Jyq7PhSM3uFVfBEaCq6x_mFV9V3B5fTEK4o3I6ZvG5A,4492
-pico_ioc/interceptors.py,sha256=rBdpI7ca5L30N-zR7LKroCIc5FgfNb9M5P7OEGw-TtY,1955
-pico_ioc/plugins.py,sha256=GP7WEMshggQ-FEjiShkcuLrSMxfueUnhbY9I8PcIyPU,1039
-pico_ioc/policy.py,sha256=p7maTHNfU-zoaz3j7CY4P3ry-bYfaGxAOklcTAuF6dY,8648
-pico_ioc/proxy.py,sha256=VJA-QaO8yvejcHmX5mlXMHfyuyXFxD7cazONSzBGrf0,6308
-pico_ioc/public_api.py,sha256=E3sArCoI1xxkIw7xQBvLYAWcIoVJjcq1s0kH-0qIVDE,2383
-pico_ioc/resolver.py,sha256=clIS9wwhOKzIwzBQFXxCrmPX2gM2X2eVyS8P_VEeyDw,4798
-pico_ioc/scanner.py,sha256=TmDLkklO-e2LBoVducQD4-uuZKFDg_dMwgwO9vM8-pU,7129
-pico_ioc/scope.py,sha256=5oRCir1Dqu8Jlgl_R-q900my1u6_7zq5VUbq8ahV280,1754
-pico_ioc/utils.py,sha256=OyhOKnyepwGQ_uQKlQLt-fymEV1bQ6hCq4Me7h3dfco,1002
-pico_ioc-1.4.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
-pico_ioc-1.4.0.dist-info/METADATA,sha256=DdvaybzEQOnC-HD563NJZqMDL7zwY3SnEpLGwjPxVzU,10346
-pico_ioc-1.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-1.4.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-1.4.0.dist-info/RECORD,,