pico-ioc 0.2.0__tar.gz → 0.3.0__tar.gz

{pico_ioc-0.2.0 → pico_ioc-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 0.2.0
+Version: 0.3.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 Project-URL: Homepage, https://github.com/dperezcabrera/pico-ioc
@@ -226,8 +226,3 @@ tox -e py311
 ## 📜 License
 
 MIT — see [LICENSE](https://opensource.org/licenses/MIT)
-
----
-
-¿Quieres que también te prepare **un ejemplo completo en el README** con `fast_model` y `BaseChatModel` para que quede documentado el nuevo orden de resolución? Así quedaría clarísimo para cualquiera que lo use.
-

{pico_ioc-0.2.0 → pico_ioc-0.3.0}/README.md

@@ -203,8 +203,3 @@ tox -e py311
 ## 📜 License
 
 MIT — see [LICENSE](https://opensource.org/licenses/MIT)
-
----
-
-¿Quieres que también te prepare **un ejemplo completo en el README** con `fast_model` y `BaseChatModel` para que quede documentado el nuevo orden de resolución? Así quedaría clarísimo para cualquiera que lo use.
-

{pico_ioc-0.2.0 → pico_ioc-0.3.0}/src/pico_ioc/__init__.py

@@ -1,7 +1,6 @@
-# src/pico_ioc/__init__.py
-
-import functools, inspect, pkgutil, importlib, logging, sys
-from typing import Callable, Any, Iterator, Optional, AsyncIterator
+import functools, inspect, pkgutil, importlib, logging
+from typing import Callable, Any, Optional
+from contextvars import ContextVar
 
 try:
     # written at build time by setuptools-scm
@@ -11,6 +10,15 @@ except Exception:  # pragma: no cover
 
 __all__ = ["__version__"]
 
+# ------------------------------------------------------------------------------
+# Re-entrancy guards
+# ------------------------------------------------------------------------------
+# True while init/scan is running. Blocks userland container access during scan.
+_scanning: ContextVar[bool] = ContextVar("pico_scanning", default=False)
+
+# True while the container is resolving deps for a component (internal use allowed).
+_resolving: ContextVar[bool] = ContextVar("pico_resolving", default=False)
+
 # ==============================================================================
 # --- 1. Container and Chameleon Proxy (Framework-Agnostic) ---
 # ==============================================================================
@@ -26,6 +34,16 @@ class PicoContainer:
         return key in self._providers or key in self._singletons
 
     def get(self, key: Any) -> Any:
+        # Forbid user code calling container.get() while the scanner is importing modules.
+        # Allow only internal calls performed during dependency resolution.
+        if _scanning.get() and not _resolving.get():
+            raise RuntimeError(
+                "pico-ioc: re-entrant container access during scan. "
+                "Avoid calling init()/get() at import time (e.g., in a module body). "
+                "Move resolution to runtime (e.g., under if __name__ == '__main__':) "
+                "or delay it until pico-ioc init completes."
+            )
+
         if key in self._singletons:
             return self._singletons[key]
         if key in self._providers:
@@ -143,13 +161,17 @@ def _resolve_param(container: PicoContainer, p: inspect.Parameter) -> Any:
     if p.name == 'self' or p.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
         raise RuntimeError("Invalid param for resolution")
 
+    # 1) NAME
     if container.has(p.name):
         return container.get(p.name)
 
     ann = p.annotation
+
+    # 2) TYPE
     if ann is not inspect._empty and container.has(ann):
         return container.get(ann)
 
+    # 3) TYPE MRO
     if ann is not inspect._empty:
         try:
             for base in getattr(ann, "__mro__", ())[1:]:
@@ -160,10 +182,11 @@ def _resolve_param(container: PicoContainer, p: inspect.Parameter) -> Any:
         except Exception:
             pass
 
+    # 4) str(NAME)
     if container.has(str(p.name)):
         return container.get(str(p.name))
 
-    key = p.name if not (ann and ann is not inspect._empty) else ann
+    key = p.name if ann is inspect._empty else ann
     return container.get(key)
 
 
@@ -175,21 +198,22 @@ def _scan_and_configure(
     package = importlib.import_module(package_or_name) if isinstance(package_or_name, str) else package_or_name
     logging.info(f"🚀 Scanning in '{package.__name__}'...")
     component_classes, factory_classes = [], []
+
     for _, name, _ in pkgutil.walk_packages(package.__path__, package.__name__ + '.'):
-        # Skip excluded modules (used by auto_exclude_caller and custom excludes)
         if exclude and exclude(name):
             logging.info(f"  ⏭️ Skipping module {name} (excluded)")
             continue
         try:
             module = importlib.import_module(name)
             for _, obj in inspect.getmembers(module, inspect.isclass):
-                if hasattr(obj, '_is_component'):
+                if getattr(obj, '_is_component', False):
                     component_classes.append(obj)
-                elif hasattr(obj, '_is_factory_component'):
+                elif getattr(obj, '_is_factory_component', False):
                     factory_classes.append(obj)
         except Exception as e:
             logging.warning(f"  ⚠️ Module {name} not processed: {e}")
 
+    # Register factories
     for factory_cls in factory_classes:
         try:
             sig = inspect.signature(factory_cls.__init__)
@@ -200,28 +224,39 @@ def _scan_and_configure(
         except Exception as e:
             logging.error(f"  ❌ Error in factory {factory_cls.__name__}: {e}", exc_info=True)
 
+    # Register components
     for component_cls in component_classes:
         key = getattr(component_cls, '_component_key', component_cls)
+
         def create_component(cls=component_cls):
             sig = inspect.signature(cls.__init__)
             deps = {}
-            for p in sig.parameters.values():
-                if p.name == 'self' or p.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
-                    continue
-                deps[p.name] = _resolve_param(container, p)
+            tok = _resolving.set(True)
+            try:
+                for p in sig.parameters.values():
+                    if p.name == 'self' or p.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                        continue
+                    deps[p.name] = _resolve_param(container, p)
+            finally:
+                _resolving.reset(tok)
             return cls(**deps)
+
         container.bind(key, create_component)
 
 _container = None
 
 def init(root_package, *, exclude: Optional[Callable[[str], bool]] = None, auto_exclude_caller: bool = True):
+    """
+    Initialize the global container and scan the given root package/module.
+    While scanning, re-entrant userland access to container.get() is blocked
+    to avoid import-time side effects.
+    """
     global _container
     if _container:
         return _container
 
     combined_exclude = exclude
     if auto_exclude_caller:
-        # módulo que invoca a init()
         try:
             caller_frame = inspect.stack()[1].frame
             caller_module = inspect.getmodule(caller_frame)
@@ -240,7 +275,13 @@ def init(root_package, *, exclude: Optional[Callable[[str], bool]] = None, auto_
 
     _container = PicoContainer()
     logging.info("🔌 Initializing 'pico-ioc'...")
-    _scan_and_configure(root_package, _container, exclude=combined_exclude)
+
+    tok = _scanning.set(True)
+    try:
+        _scan_and_configure(root_package, _container, exclude=combined_exclude)
+    finally:
+        _scanning.reset(tok)
+
     logging.info("✅ Container configured and ready.")
     return _container
 
@@ -252,19 +293,26 @@ def factory_component(cls):
     return cls
 
 def provides(key: Any, *, lazy: bool = True):
+    """
+    Declare that a factory method provides a component under 'key'.
+    By default, returns a LazyProxy that instantiates upon first real use.
+    """
     def decorator(func):
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
             return LazyProxy(lambda: func(*args, **kwargs)) if lazy else func(*args, **kwargs)
-        # mantenemos compat con _provides_name (por si alguien lo usa)
-        setattr(wrapper, '_provides_name', key)
+        setattr(wrapper, '_provides_name', key)  # legacy-compatible storage
         return wrapper
     return decorator
 
 def component(cls=None, *, name: str = None):
-    def decorator(cls):
-        setattr(cls, '_is_component', True)
-        setattr(cls, '_component_key', name if name is not None else cls)
-        return cls
+    """
+    Mark a class as a component. Registered by class type by default,
+    or by 'name' if provided.
+    """
+    def decorator(c):
+        setattr(c, '_is_component', True)
+        setattr(c, '_component_key', name if name is not None else c)
+        return c
     return decorator(cls) if cls else decorator
 

pico_ioc-0.3.0/src/pico_ioc/_version.py

@@ -0,0 +1 @@
+__version__ = '0.3.0'

{pico_ioc-0.2.0 → pico_ioc-0.3.0}/src/pico_ioc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 0.2.0
+Version: 0.3.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 Project-URL: Homepage, https://github.com/dperezcabrera/pico-ioc
@@ -226,8 +226,3 @@ tox -e py311
 ## 📜 License
 
 MIT — see [LICENSE](https://opensource.org/licenses/MIT)
-
----
-
-¿Quieres que también te prepare **un ejemplo completo en el README** con `fast_model` y `BaseChatModel` para que quede documentado el nuevo orden de resolución? Así quedaría clarísimo para cualquiera que lo use.
-

{pico_ioc-0.2.0 → pico_ioc-0.3.0}/tests/test_pico_ioc.py

@@ -1,5 +1,6 @@
 import pytest
 import sys
+import logging
 import pico_ioc
 
 # --- Test Environment Setup Fixture ---
@@ -24,13 +25,7 @@ def test_project(tmp_path):
     package_dir.mkdir()
     (package_dir / "__init__.py").touch()
 
-    # Components:
-    # - SimpleService                          (no deps)
-    # - AnotherService                         (depends on SimpleService by type)
-    # - CustomNameService                      (registered by custom name)
-    # - NeedsByName                            (depends by name only)
-    # - NeedsNameVsType                        (name should win over type)
-    # - NeedsTypeFallback                      (fallback to base type via MRO)
+    # Components
     (package_dir / "components.py").write_text(
         """
 from pico_ioc import component
@@ -81,10 +76,7 @@ class MissingDep:
 """
     )
 
-    # Factories:
-    # - complex_service (lazy via LazyProxy; counter to assert laziness)
-    # - fast_model      (by NAME)
-    # - base_interface  (by TYPE: BaseInterface)
+    # Factories
     (package_dir / "factories.py").write_text(
         """
 from pico_ioc import factory_component, provides
@@ -106,7 +98,7 @@ class ServiceFactory:
     @provides(key="fast_model")
     def create_fast_model(self):
         FAST_COUNTER["value"] += 1
-        return {"who": "fast"}  # any object; dict is convenient for identity checks
+        return {"who": "fast"}
 
     @provides(key=BaseInterface)
     def create_base_interface(self):
@@ -115,23 +107,25 @@ class ServiceFactory:
 """
     )
 
-    # Optional module that calls init() at import-time:
-    # used to test auto-exclude of the caller (to prevent re-entrancy).
+    # Module that triggers re-entrant access: init() + get() at import-time
     (project_root / "entry.py").write_text(
         """
 import pico_ioc
 import test_project
+from test_project.services.components import SimpleService
 
-# If auto-exclude-caller is on AND _scan_and_configure() honors 'exclude',
-# importing this module during scanning should NOT recurse infinitely.
+# This runs at import-time when the scanner imports this module.
+# init() returns the (global) container set by the outer scan,
+# then get() is attempted while scanning is still in progress -> guard should raise.
 ioc = pico_ioc.init(test_project)
+ioc.get(SimpleService)  # should raise RuntimeError due to re-entrant access during scan
 """
     )
 
-    # Yield the root package name used by pico_ioc.init()
+    # Yield root package name used by pico_ioc.init()
     yield "test_project"
 
-    # Teardown: remove path, reset container, purge modules from cache
+    # Teardown
     sys.path.pop(0)
     pico_ioc._container = None
     mods_to_del = [m for m in list(sys.modules.keys()) if m == "test_project" or m.startswith("test_project.")]
@@ -153,10 +147,7 @@ def test_simple_component_retrieval(test_project):
 
 
 def test_dependency_injection_by_type_hint(test_project):
-    """
-    When a constructor parameter has a type hint and no provider is bound by name,
-    the container should resolve it by TYPE.
-    """
+    """Type-hinted dependency resolves by TYPE when no NAME-bound provider exists."""
     from test_project.services.components import SimpleService, AnotherService
 
     container = pico_ioc.init(test_project)
@@ -167,9 +158,7 @@ def test_dependency_injection_by_type_hint(test_project):
 
 
 def test_components_are_singletons_by_default(test_project):
-    """
-    Providers bound by the scanner are singletons: get() returns the same instance.
-    """
+    """Providers registered by the scanner behave as singletons."""
     from test_project.services.components import SimpleService
 
     container = pico_ioc.init(test_project)
@@ -181,9 +170,7 @@ def test_components_are_singletons_by_default(test_project):
 
 
 def test_get_unregistered_component_raises_error(test_project):
-    """
-    Requesting a key with no provider must raise NameError with a helpful message.
-    """
+    """Requesting an unknown key raises NameError."""
     container = pico_ioc.init(test_project)
 
     class Unregistered: ...
@@ -192,50 +179,36 @@ def test_get_unregistered_component_raises_error(test_project):
 
 
 def test_factory_provides_component_by_name(test_project):
-    """
-    A factory method annotated with @provides(key="...") is bound by NAME and is retrievable.
-    """
+    """Factory-provided component is retrievable by key; proxy behaves like real value."""
     container = pico_ioc.init(test_project)
     svc = container.get("complex_service")
-
-    # Proxy must behave like the real string for equality
     assert svc == "This is a complex service"
 
 
 def test_factory_instantiation_is_lazy_and_singleton(test_project):
-    """
-    Factory methods with default lazy=True return a LazyProxy. The real object is created on first use.
-    Also, container should cache the created instance (singleton per key).
-    """
+    """LazyProxy creates real object on first use and remains singleton per key."""
     from test_project.services.factories import CREATION_COUNTER
 
     container = pico_ioc.init(test_project)
-
     assert CREATION_COUNTER["value"] == 0
 
     proxy = container.get("complex_service")
-    # Accessing attributes/methods of the proxy should trigger creation exactly once
     assert CREATION_COUNTER["value"] == 0
     up = proxy.upper()
     assert up == "THIS IS A COMPLEX SERVICE"
     assert CREATION_COUNTER["value"] == 1
 
-    # Re-accessing via the same proxy does not create again
     _ = proxy.lower()
     assert CREATION_COUNTER["value"] == 1
 
-    # Getting the same key again should return the same singleton instance (no extra creations)
     again = container.get("complex_service")
-    assert again is proxy  # same object returned by container
+    assert again is proxy
     _ = again.strip()
     assert CREATION_COUNTER["value"] == 1
 
 
 def test_component_with_custom_name(test_project):
-    """
-    A component registered by custom name is retrievable by that name,
-    and NOT by its class.
-    """
+    """Component registered by custom name is retrievable by that name, not by class."""
     from test_project.services.components import CustomNameService
 
     container = pico_ioc.init(test_project)
@@ -247,27 +220,20 @@ def test_component_with_custom_name(test_project):
 
 
 def test_resolution_prefers_name_over_type(test_project):
-    """
-    If both a NAME-bound provider and a TYPE-bound provider exist, resolution MUST
-    prefer the NAME (parameter name) over the TYPE hint.
-    """
+    """If NAME and TYPE providers exist, NAME must win."""
     from test_project.services.components import NeedsNameVsType
     from test_project.services.factories import FAST_COUNTER, BASE_COUNTER
 
     container = pico_ioc.init(test_project)
     comp = container.get(NeedsNameVsType)
 
-    # "fast_model" name must win → uses the fast provider
     assert comp.model == {"who": "fast"}
     assert FAST_COUNTER["value"] == 1
-    # Base provider should NOT be used for this resolution
     assert BASE_COUNTER["value"] == 0
 
 
 def test_resolution_by_name_only(test_project):
-    """
-    When a ctor parameter has NO type hint, the container must resolve strictly by NAME.
-    """
+    """Ctor param without type hint resolves strictly by NAME."""
     from test_project.services.components import NeedsByName
     from test_project.services.factories import FAST_COUNTER
 
@@ -279,25 +245,19 @@ def test_resolution_by_name_only(test_project):
 
 
 def test_resolution_fallback_to_type_mro(test_project):
-    """
-    When there is no provider for the parameter NAME nor the exact TYPE,
-    the container must try TYPE's MRO and use the first available provider.
-    """
+    """If neither NAME nor exact TYPE match, fallback via TYPE MRO."""
     from test_project.services.components import NeedsTypeFallback
     from test_project.services.factories import BASE_COUNTER
 
     container = pico_ioc.init(test_project)
     comp = container.get(NeedsTypeFallback)
 
-    # Resolved via MRO to BaseInterface provider
     assert comp.impl == {"who": "base"}
     assert BASE_COUNTER["value"] == 1
 
 
 def test_missing_dependency_raises_clear_error(test_project):
-    """
-    If no provider exists for NAME nor TYPE nor MRO, resolution must raise NameError.
-    """
+    """Missing dep across NAME/TYPE/MRO raises NameError."""
     from test_project.services.components import MissingDep
 
     container = pico_ioc.init(test_project)
@@ -305,17 +265,23 @@ def test_missing_dependency_raises_clear_error(test_project):
         container.get(MissingDep)
 
 
-@pytest.mark.skipif(
-    not hasattr(pico_ioc, "init"),
-    reason="init not available"
-)
-def test_auto_exclude_caller_prevents_reentrant_scan(test_project):
+def test_reentrant_access_is_blocked_and_container_still_initializes(test_project, caplog):
     """
-    Smoke test: importing a module that calls pico_ioc.init(root) at import-time
-    should not cause re-entrant scans if init() auto-excludes the caller AND
-    _scan_and_configure honors the 'exclude' predicate.
+    Importing a module that calls init() and then container.get() at import-time should:
+      - raise a RuntimeError from the guard (caught as a warning by the scanner),
+      - NOT prevent the container from finishing initialization,
+      - allow normal component retrieval afterwards.
     """
-    # If the library correctly auto-excludes the caller and passes 'exclude'
-    # into the scanner (which must skip excluded modules), this import should be safe.
-    __import__("test_project.entry")
+    caplog.set_level(logging.INFO)
+
+    container = pico_ioc.init(test_project)
+
+    assert any(
+        "re-entrant container access during scan" in rec.message
+        for rec in caplog.records
+    ), "Expected a warning about re-entrant access during scan"
+
+    from test_project.services.components import SimpleService
+    svc = container.get(SimpleService)
+    assert isinstance(svc, SimpleService)
 

pico_ioc-0.2.0/src/pico_ioc/_version.py

@@ -1 +0,0 @@
-__version__ = '0.2.0'