pico-ioc 0.5.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

pico_ioc/scanner.py

@@ -0,0 +1,238 @@
+# pico_ioc/scanner.py
+import importlib
+import inspect
+import logging
+import pkgutil
+from types import ModuleType
+from typing import Any, Callable, Optional, Tuple, List, Iterable
+
+from .container import PicoContainer, Binder
+from .decorators import (
+    COMPONENT_FLAG,
+    COMPONENT_KEY,
+    COMPONENT_LAZY,
+    FACTORY_FLAG,
+    PROVIDES_KEY,
+    PROVIDES_LAZY,
+)
+from .proxy import ComponentProxy
+from .resolver import Resolver
+from .plugins import PicoPlugin
+from . import _state
+
+
+def scan_and_configure(
+    package_or_name: Any,
+    container: PicoContainer,
+    *,
+    exclude: Optional[Callable[[str], bool]] = None,
+    plugins: Tuple[PicoPlugin, ...] = (),
+) -> None:
+    """
+    Scan a package, discover component classes/factories, and bind them into the container.
+
+    Args:
+        package_or_name: Package module or importable package name (str).
+        container: Target PicoContainer to receive bindings.
+        exclude: Optional predicate that receives a module name and returns True to skip it.
+        plugins: Optional lifecycle plugins that receive scan/bind events.
+    """
+    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 = _collect_decorated_classes(
+        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,
+    )
+
+
+# -------------------- Helpers (private) --------------------
+
+def _as_module(package_or_name: Any) -> ModuleType:
+    """Return a module from either a module object or an importable string name."""
+    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 _run_plugin_hook(
+    plugins: Tuple[PicoPlugin, ...],
+    hook_name: str,
+    *args,
+    **kwargs,
+) -> None:
+    """Run a lifecycle hook across all plugins, logging (but not raising) exceptions."""
+    for pl in plugins:
+        try:
+            fn = getattr(pl, hook_name, None)
+            if fn:
+                fn(*args, **kwargs)
+        except Exception:
+            logging.exception("Plugin %s failed", hook_name)
+
+
+def _iter_package_modules(
+    package: ModuleType,
+) -> Iterable[str]:
+    """
+    Yield fully qualified module names under the given package.
+
+    Requires the package to have a __path__ (i.e., be a package, not a single module).
+    """
+    try:
+        pkg_path = package.__path__  # type: ignore[attr-defined]
+    except Exception:
+        return  # not a package; nothing to iterate
+
+    prefix = package.__name__ + "."
+    for _finder, name, _is_pkg in pkgutil.walk_packages(pkg_path, prefix):
+        yield name
+
+
+def _collect_decorated_classes(
+    *,
+    package: ModuleType,
+    exclude: Optional[Callable[[str], bool]],
+    plugins: Tuple[PicoPlugin, ...],
+    binder: Binder,
+) -> Tuple[List[type], List[type]]:
+    """
+    Import modules under `package`, visit classes, and collect those marked with
+    @component or @factory_component decorators.
+    """
+    comp_classes: List[type] = []
+    factory_classes: List[type] = []
+
+    def _visit_module(module: ModuleType):
+        for _name, obj in inspect.getmembers(module, inspect.isclass):
+            # Allow plugins to inspect/transform/record classes
+            _run_plugin_hook(plugins, "visit_class", module, obj, binder)
+
+            # Collect decorated classes
+            if getattr(obj, COMPONENT_FLAG, False):
+                comp_classes.append(obj)
+            elif getattr(obj, FACTORY_FLAG, False):
+                factory_classes.append(obj)
+
+    # 1) Si es un paquete, recorrer submódulos
+    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)
+
+    # 2) Si el “paquete” raíz es un módulo (sin __path__), también hay que visitarlo.
+    if not hasattr(package, "__path__"):
+        _visit_module(package)
+
+    return comp_classes, factory_classes
+
+
+def _register_component_classes(
+    *,
+    classes: List[type],
+    container: PicoContainer,
+    resolver: Resolver,
+) -> None:
+    """
+    Register @component classes into the container.
+
+    Binding key:
+        - If the class has COMPONENT_KEY, use it; otherwise, bind by the class itself.
+    Laziness:
+        - If COMPONENT_LAZY is True, provide a proxy that defers instantiation.
+    """
+    for cls in classes:
+        key = getattr(cls, COMPONENT_KEY, cls)
+        is_lazy = bool(getattr(cls, COMPONENT_LAZY, False))
+
+        def _provider_factory(c=cls, lazy=is_lazy):
+            def _factory():
+                if lazy:
+                    return ComponentProxy(lambda: resolver.create_instance(c))
+                return resolver.create_instance(c)
+            return _factory
+
+        container.bind(key, _provider_factory(), lazy=is_lazy)
+
+
+def _register_factory_classes(
+    *,
+    factory_classes: List[type],
+    container: PicoContainer,
+    resolver: Resolver,
+) -> None:
+    """
+    Register products of @factory_component classes.
+
+    For each factory class:
+        - Instantiate the factory via the resolver.
+        - For each method with @provides:
+            - Bind the provided key to a callable that calls the factory method.
+            - If PROVIDES_LAZY is True, bind a proxy that defers the method call.
+    """
+    for fcls in factory_classes:
+        try:
+            # Durante el escaneo, permitir la resolución de dependencias de la factory
+            # elevando temporalmente el flag `_resolving` para no chocar con la guardia.
+            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))
+            # `bound` is the bound method on the instance (so it has `self`)
+            bound = getattr(finst, attr_name, func.__get__(finst, fcls))
+
+            def _make_provider(m=bound, owner=fcls, lazy=is_lazy):
+                def _factory():
+                    # Compute kwargs at call time to ensure up-to-date dependency resolution
+                    kwargs = resolver.kwargs_for_callable(m, owner_cls=owner)
+
+                    def _call():
+                        return m(**kwargs)
+
+                    return ComponentProxy(lambda: _call()) if lazy else _call()
+                return _factory
+
+            container.bind(provided_key, _make_provider(), lazy=is_lazy)
+

pico_ioc/typing_utils.py

@@ -0,0 +1,29 @@
+# pico_ioc/typing_utils.py
+
+import sys
+import typing
+
+
+def evaluated_hints(func, owner_cls=None) -> dict:
+    """Return type hints; swallow any error and return {}."""
+    try:
+        module = sys.modules.get(func.__module__)
+        globalns = getattr(module, "__dict__", {})
+        localns = vars(owner_cls) if owner_cls is not None else None
+        return typing.get_type_hints(func, globalns=globalns, localns=localns, include_extras=True)
+    except Exception:
+        return {}
+
+
+def resolve_annotation_to_type(ann, func, owner_cls=None):
+    """Best-effort evaluation of a string annotation; return original on failure."""
+    if not isinstance(ann, str):
+        return ann
+    try:
+        module = sys.modules.get(func.__module__)
+        globalns = getattr(module, "__dict__", {})
+        localns = vars(owner_cls) if owner_cls is not None else None
+        return eval(ann, globalns, localns)
+    except Exception:
+        return ann
+

pico_ioc-1.0.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: pico-ioc
+Version: 1.0.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/)
+[![DeepWiki](https://img.shields.io/badge/docs-DeepWiki-blue)](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`).
+
+---
+
+## ✨ Features
+
+- **Zero dependencies** — pure Python, framework-agnostic.
+- **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.
+- **Qualifiers & collections** — `list[Annotated[T, Q]]` filters by qualifier.
+- **Plugins** — lifecycle hooks (`before_scan`, `after_ready`).
+- **Public API helper** — auto-export decorated symbols in `__init__.py`.
+- **Thread/async safe** — isolation via `ContextVar`.
+
+---
+
+## 📦 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
+```
+
+---
+
+## 📖 Documentation
+
+* [Overview](.llm/OVERVIEW.md) — mission & concepts
+* [Guide](.llm/GUIDE.md) — practical usage & recipes
+* [Architecture](.llm/ARCHITECTURE.md) — internals & design rationale
+
+---
+
+## 🧪 Development
+
+```bash
+pip install tox
+tox
+```
+
+---
+
+## 📜 License
+
+MIT — see [LICENSE](https://opensource.org/licenses/MIT)
+
+
+

pico_ioc-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+pico_ioc/__init__.py,sha256=7EyifZ02LFfhkAR6zzAaQJvByyMI2_-qNrw49gPoJkA,633
+pico_ioc/_state.py,sha256=KHNtdPrv1s-uynfot2IsNkWotBPyORPCcM2xe9qMMPo,286
+pico_ioc/_version.py,sha256=RsZjRjMprNcDm97wqRRSk6rTLgTX8N0GyicZyZ8OsBQ,22
+pico_ioc/api.py,sha256=pvzAx725UG5Z6TPqQqiWdfytb0ddk26-cxnkTJRaK8o,3648
+pico_ioc/container.py,sha256=81Jys4Ipu57B4pM5xQuq48S5oEhuKin7Y8vEERg-4_4,5085
+pico_ioc/decorators.py,sha256=gNPxLFNEdFUFYlxILKjU76XyoPohediK0DNiv-RpK3I,1902
+pico_ioc/plugins.py,sha256=JbI-28VLGJaik7ysXi3L-YGTGxhqwJH4W5QYuWSruDE,589
+pico_ioc/proxy.py,sha256=-e3Z9z7Bc_2wxswwUJI_s8AfvCTps8f8RWUJ9RuEp7E,4606
+pico_ioc/public_api.py,sha256=E3sArCoI1xxkIw7xQBvLYAWcIoVJjcq1s0kH-0qIVDE,2383
+pico_ioc/resolver.py,sha256=PN5uq2dFEStAzzTEl0n4AEyC-k7TowqCu7-uwIDDgEk,3897
+pico_ioc/scanner.py,sha256=-iOj_qX15IBFmOAFQlP_1rIkBfamGzdqYdvIPOvq7sY,7709
+pico_ioc/typing_utils.py,sha256=JQ4bkR60pKxFs3f8JlEz41ruKDsWj-SmkKv3DLJriec,950
+pico_ioc-1.0.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_ioc-1.0.0.dist-info/METADATA,sha256=CZqjp3KYScMMGV25CGrAnDVj37ZbGw3BD9eWC9tjOxw,5434
+pico_ioc-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-1.0.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-1.0.0.dist-info/RECORD,,