pico-ioc 2.1.3__py3-none-any.whl → 2.2.0__py3-none-any.whl

pico_ioc/__init__.py

@@ -1,4 +1,3 @@
-# src/pico_ioc/__init__.py
 from .constants import LOGGER_NAME, LOGGER, PICO_INFRA, PICO_NAME, PICO_KEY, PICO_META
 from .exceptions import (
     PicoError,
@@ -31,6 +30,7 @@ from .container import PicoContainer
 from .event_bus import EventBus, ExecPolicy, ErrorPolicy, Event, subscribe, AutoSubscriberMixin
 from .config_runtime import JsonTreeSource, YamlTreeSource, DictSource, Discriminator, Value
 from .analysis import DependencyRequest, analyze_callable_dependencies
+from .component_scanner import CustomScanner
 
 __all__ = [
     "LOGGER_NAME",
@@ -91,4 +91,5 @@ __all__ = [
     "Value",
     "DependencyRequest",
     "analyze_callable_dependencies",
+    "CustomScanner",
 ]

pico_ioc/_version.py

@@ -1 +1 @@
-__version__ = '2.1.3'
+__version__ = '2.2.0'

pico_ioc/api.py

@@ -1,5 +1,3 @@
-# src/pico_ioc/api.py
-
 import importlib
 import pkgutil
 import logging
@@ -13,6 +11,8 @@ from .container import PicoContainer
 from .decorators import component, factory, provides, Qualifier, configure, cleanup, configured
 from .config_builder import ContextConfig, configuration
 from .registrar import Registrar
+from .aop import ContainerObserver
+from .component_scanner import CustomScanner
 
 KeyT = Union[str, type]
 Provider = Callable[[], Any]
@@ -63,7 +63,8 @@ def init(
     custom_scopes: Optional[Iterable[str]] = None,
     validate_only: bool = False,
     container_id: Optional[str] = None,
-    observers: Optional[List["ContainerObserver"]] = None,
+    observers: Optional[List[ContainerObserver]] = None,
+    custom_scanners: Optional[List[CustomScanner]] = None,
 ) -> PicoContainer:
     active = tuple(p.strip() for p in profiles if p)
     
@@ -82,6 +83,11 @@ def init(
             
     pico = PicoContainer(factory, caches, scopes, container_id=container_id, profiles=active, observers=observers or [])
     registrar = Registrar(factory, profiles=active, environ=environ, logger=logger, config=config)
+    
+    if custom_scanners:
+        for scanner in custom_scanners:
+            registrar.register_custom_scanner(scanner)
+
     for m in _iter_input_modules(modules):
         registrar.register_module(m)
         

pico_ioc/component_scanner.py

@@ -1,6 +1,6 @@
 import inspect
 import os
-from typing import Any, Callable, Dict, List, Optional, Tuple, Union, Set
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union, Set, Protocol
 from .constants import PICO_INFRA, PICO_NAME, PICO_KEY, PICO_META
 from .factory import ProviderMetadata, DeferredProvider
 from .decorators import get_return_type
@@ -10,6 +10,10 @@ from .analysis import analyze_callable_dependencies, DependencyRequest
 KeyT = Union[str, type]
 Provider = Callable[[], Any]
 
+class CustomScanner(Protocol):
+    def should_scan(self, obj: Any) -> bool: ...
+    def scan(self, obj: Any) -> Optional[Tuple[KeyT, Provider, ProviderMetadata]]: ...
+
 class ComponentScanner:
     def __init__(self, profiles: Set[str], environ: Dict[str, str], config_manager: ConfigurationManager):
         self._profiles = profiles
@@ -19,6 +23,10 @@ class ComponentScanner:
         self._on_missing: List[Tuple[int, KeyT, type]] = []
         self._deferred: List[DeferredProvider] = []
         self._provides_functions: Dict[KeyT, Callable[..., Any]] = {}
+        self._custom_scanners: List[CustomScanner] = []
+
+    def register_custom_scanner(self, scanner: CustomScanner) -> None:
+        self._custom_scanners.append(scanner)
 
     def get_scan_results(self) -> Tuple[Dict[KeyT, List[Tuple[bool, Provider, ProviderMetadata]]], List[Tuple[int, KeyT, type]], List[DeferredProvider], Dict[KeyT, Callable[..., Any]]]:
         return self._candidates, self._on_missing, self._deferred, self._provides_functions
@@ -86,7 +94,6 @@ class ComponentScanner:
         if has_instance_provides:
             factory_deps = analyze_callable_dependencies(cls.__init__)
 
-
         for name in dir(cls):
             try:
                 raw = inspect.getattr_static(cls, name)
@@ -140,27 +147,44 @@ class ComponentScanner:
         self._queue(k, provider, md)
         self._provides_functions[k] = fn
 
+    def _try_custom_scanners(self, obj: Any) -> bool:
+        for scanner in self._custom_scanners:
+            if scanner.should_scan(obj):
+                result = scanner.scan(obj)
+                if result:
+                    key, provider, md = result
+                    self._queue(key, provider, md)
+                    if isinstance(provider, DeferredProvider):
+                        self._deferred.append(provider)
+                    return True
+        return False
+
     def scan_module(self, module: Any) -> None:
         for _, obj in inspect.getmembers(module):
-            if inspect.isclass(obj):
-                meta = getattr(obj, PICO_META, {})
-                if "on_missing" in meta:
-                    sel = meta["on_missing"]["selector"]
-                    pr = int(meta["on_missing"].get("priority", 0))
-                    self._on_missing.append((pr, sel, obj))
-                    continue
-
-                infra = getattr(obj, PICO_INFRA, None)
-                if infra == "component":
-                    self._register_component_class(obj)
-                elif infra == "factory":
-                    self._register_factory_class(obj)
-                elif infra == "configured":
-                    enabled = self._enabled_by_condition(obj)
-                    reg_data = self._config_manager.register_configured_class(obj, enabled)
-                    if reg_data:
-                        self._queue(reg_data[0], reg_data[1], reg_data[2])
-
-        for _, fn in inspect.getmembers(module, predicate=inspect.isfunction):
-            if getattr(fn, PICO_INFRA, None) == "provides":
-                self._register_provides_function(fn)
+            if self._try_custom_scanners(obj):
+                continue
+
+            if inspect.isclass(obj) or getattr(obj, "_is_protocol", False):
+                if inspect.isclass(obj):
+                    meta = getattr(obj, PICO_META, {})
+                    
+                    if "on_missing" in meta:
+                        sel = meta["on_missing"]["selector"]
+                        pr = int(meta["on_missing"].get("priority", 0))
+                        self._on_missing.append((pr, sel, obj))
+                        continue
+
+                    infra = getattr(obj, PICO_INFRA, None)
+                    if infra == "component":
+                        self._register_component_class(obj)
+                    elif infra == "factory":
+                        self._register_factory_class(obj)
+                    elif infra == "configured":
+                        enabled = self._enabled_by_condition(obj)
+                        reg_data = self._config_manager.register_configured_class(obj, enabled)
+                        if reg_data:
+                            self._queue(reg_data[0], reg_data[1], reg_data[2])
+
+            elif inspect.isfunction(obj):
+                if getattr(obj, PICO_INFRA, None) == "provides":
+                    self._register_provides_function(obj)

pico_ioc/container.py

@@ -384,6 +384,10 @@ class PicoContainer:
         self.cleanup_all()
         PicoContainer._container_registry.pop(self.container_id, None)
 
+    async def ashutdown(self) -> None:
+        await self.cleanup_all_async()
+        PicoContainer._container_registry.pop(self.container_id, None)
+        
     def build_resolution_graph(self):
         return _build_resolution_graph(self._locator)
         

pico_ioc/registrar.py

@@ -15,7 +15,7 @@ from .config_runtime import TreeSource
 from .config_registrar import ConfigurationManager
 from .provider_selector import ProviderSelector
 from .dependency_validator import DependencyValidator
-from .component_scanner import ComponentScanner
+from .component_scanner import ComponentScanner, CustomScanner
 from .analysis import analyze_callable_dependencies, DependencyRequest
 from .container import PicoContainer
 
@@ -49,6 +49,8 @@ class Registrar:
         self._deferred: List[DeferredProvider] = []
         self._provides_functions: Dict[KeyT, Callable[..., Any]] = {}
 
+    def register_custom_scanner(self, scanner: CustomScanner) -> None:
+        self._scanner.register_custom_scanner(scanner)
 
     def locator(self) -> ComponentLocator:
         loc = ComponentLocator(dict(self._metadata), dict(self._indexes))
@@ -65,16 +67,13 @@ class Registrar:
                     return UnifiedComponentProxy(container=_p, object_creator=_orig, component_key=_k)
                 self._factory.bind(key, lazy_proxy_provider)
 
-
     def _bind_if_absent(self, key: KeyT, provider: Provider) -> None:
         if not self._factory.has(key):
             self._factory.bind(key, provider)
 
-
     def register_module(self, module: Any) -> None:
         self._scanner.scan_module(module)
 
-
     def _find_md_for_type(self, t: type) -> Optional[ProviderMetadata]:
         cands: List[ProviderMetadata] = []
         for md in self._metadata.values():
@@ -133,7 +132,6 @@ class Registrar:
             if md.pico_name is not None:
                 add("pico_name", md.pico_name, k)
 
-
     def finalize(self, overrides: Optional[Dict[KeyT, Any]], *, pico_instance: PicoContainer) -> None:
         candidates, on_missing, deferred_providers, provides_functions = self._scanner.get_scan_results()
         self._deferred = deferred_providers

pico_ioc/scope.py

@@ -92,10 +92,9 @@ class ScopeManager:
         return self.signature(self.names())
 
 class ScopedCaches:
-    def __init__(self, max_scopes_per_type: int = 2048) -> None:
+    def __init__(self) -> None:
         self._singleton = ComponentContainer()
         self._by_scope: Dict[str, Dict[Any, ComponentContainer]] = {}
-        self._max = int(max_scopes_per_type)
         self._no_cache = _NoCacheContainer()
         
     def _cleanup_object(self, obj: Any) -> None:

{pico_ioc-2.1.3.dist-info → pico_ioc-2.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.1.3
+Version: 2.2.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -28,7 +28,7 @@ License: MIT License
 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
+Keywords: python,ioc,dependency-injection,di-container,inversion-of-control,ioc-container,zero-dependency,minimalistic,async,asyncio,modular,pluggable,ioc-framework,ioc-containers,inversion-of-control-container
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -62,7 +62,6 @@ Dynamic: license-file
 [![Docs](https://img.shields.io/badge/Docs-pico--ioc-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-ioc/)
 [![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/learn-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.
 
@@ -97,14 +96,14 @@ Pico-IoC eliminates that friction by letting you declare how components relate
 
 ---
 
-## 🧩 Highlights (v2.0+)
+## 🧩 Highlights (v2.2+)
 
-- Unified Configuration: Use `@configured` to bind both flat (ENV-like) and tree (YAML/JSON) sources via the `configuration(...)` builder (ADR-0010).
-- Async-aware AOP system: Method interceptors via `@intercepted_by`.
-- Scoped resolution: singleton, prototype, request, session, transaction, and custom scopes.
-- `UnifiedComponentProxy`: Transparent `lazy=True` and AOP proxy supporting serialization.
-- Tree-based configuration runtime: Advanced mapping with reusable adapters and discriminators (`Annotated[Union[...], Discriminator(...)]`).
-- Observable container context: Built-in stats, health checks (`@health`), observer hooks (`ContainerObserver`), dependency graph export (`export_graph`), and async cleanup.
+- **Unified Configuration**: Use `@configured` to bind both flat (ENV-like) and tree (YAML/JSON) sources via the `configuration(...)` builder (ADR-0010).
+- **Extensible Scanning**: Use `CustomScanner` to hook into the discovery phase and register functions or custom decorators (ADR-0011).
+- **Async-aware AOP**: Method interceptors via `@intercepted_by`.
+- **Scoped resolution**: singleton, prototype, request, session, transaction, and custom scopes.
+- **Tree-based configuration**: Advanced mapping with reusable adapters (`Annotated[Union[...], Discriminator(...)]`).
+- **Observable context**: Built-in stats, health checks (`@health`), observer hooks (`ContainerObserver`), and dependency graph export.
 
 ---
 
@@ -116,20 +115,21 @@ pip install pico-ioc
 
 Optional extras:
 
-- YAML configuration support (requires PyYAML)
+  - YAML configuration support (requires PyYAML)
 
-  ```bash
-  pip install pico-ioc[yaml]
-  ```
+    ```bash
+    pip install pico-ioc[yaml]
+    ```
 
 -----
 
-### ⚠️ Important Note for v2.1.3+
+### ⚠️ Important Note
+
+**Breaking Behavior in Scope Management (v2.1.3+):**
+**Scope LRU Eviction has been removed** to guarantee data integrity.
 
-**Breaking Behavior in Custom Integrations:**
-As of version 2.1.3, **Scope LRU Eviction has been removed** to guarantee data integrity under high load.
-* **If you use `pico-fastapi`:** You are safe (the middleware handles cleanup automatically).
-* **If you perform manual scope management:** You **must** explicitly call `container._caches.cleanup_scope("scope_name", scope_id)` when a context ends. Failing to do so will result in a memory leak, as scopes are no longer automatically discarded when the container fills up.
+  * **Frameworks (pico-fastapi):** Handled automatically.
+  * **Manual usage:** You **must** explicitly call `container._caches.cleanup_scope("scope_name", scope_id)` when a context ends to prevent memory leaks.
 
 -----
 
@@ -247,12 +247,16 @@ async def main():
     container = init(modules=[__name__])
     repo = await container.aget(AsyncRepo)   # Async resolution
     print(await repo.fetch())
+    
+    # Graceful async shutdown (calls @cleanup async methods)
+    await container.ashutdown()
 
 asyncio.run(main())
 ```
 
-- `__ainit__` runs after construction if defined.
-- Use `container.aget(Type)` to resolve components that require async initialization or whose providers are async.
+  - `__ainit__` runs after construction if defined.
+  - Use `container.aget(Type)` to resolve components that require async initialization.
+  - Use `await container.ashutdown()` to close resources cleanly.
 
 -----
 
@@ -292,35 +296,26 @@ result = c.get(Demo).work()
 print(f"Result: {result}")
 ```
 
-Output:
-
-```
-→ calling Demo.work
-   Working...
-← Demo.work done (10.xxms)
-Result: ok
-```
-
 -----
 
 ## 👁️ Observability & Cleanup
 
-- Export a dependency graph in DOT format:
+  - Export a dependency graph in DOT format:
+
+    ```python
+    c = init(modules=[...])
+    c.export_graph("dependencies.dot")  # Writes directly to file
+    ```
 
-  ```python
-  c = init(modules=[...])
-  dot = c.export_graph()  # Returns DOT graph as a string
-  with open("dependencies.dot", "w") as f:
-      f.write(dot)
-  ```
+  - Health checks:
 
-- Health checks:
-  - Annotate health probes inside components with `@health` for container-level reporting.
-  - The container exposes health information that can be queried in observability tooling.
+      - Annotate health probes inside components with `@health` for container-level reporting.
+      - The container exposes health information that can be queried in observability tooling.
 
-- Container cleanup:
-  - For sync components: `container.close()`
-  - For async components/resources: `await container.aclose()`
+  - Container cleanup:
+
+      - For sync apps: `container.shutdown()`
+      - For async apps: `await container.ashutdown()`
 
 Use cleanup in application shutdown hooks to release resources deterministically.
 
@@ -330,14 +325,14 @@ Use cleanup in application shutdown hooks to release resources deterministically
 
 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`
-- Cookbook (Patterns): `docs/cookbook/README.md`
-- Architecture: `docs/architecture/README.md`
-- API Reference: `docs/api-reference/README.md`
-- ADR Index: `docs/adr/README.md`
+  - 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`
+  - Cookbook (Patterns): `docs/cookbook/README.md`
+  - Architecture: `docs/architecture/README.md`
+  - API Reference: `docs/api-reference/README.md`
+  - ADR Index: `docs/adr/README.md`
 
 -----
 
@@ -352,10 +347,11 @@ tox
 
 ## 🧾 Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) — Significant redesigns and features in v2.0+.
+See [CHANGELOG.md](https://www.google.com/search?q=./CHANGELOG.md) — Significant redesigns and features in v2.0+.
 
 -----
 
 ## 📜 License
 
 MIT — [LICENSE](https://opensource.org/licenses/MIT)
+

{pico_ioc-2.1.3.dist-info → pico_ioc-2.2.0.dist-info}/RECORD

@@ -1,14 +1,14 @@
-pico_ioc/__init__.py,sha256=i25Obx7aH_Oy5b6yjjnCswDgni7InIjrGEcG6vLAw6I,2414
-pico_ioc/_version.py,sha256=hgD1miBO_f3fboq1GKyV4DdK_igCLGJFnZRD7l9oNRs,22
+pico_ioc/__init__.py,sha256=MDneoBBB0JHD_o0_xzkOUeW4e3XjDJSaGMNTb5miBqw,2453
+pico_ioc/_version.py,sha256=Vyf6P6UCZKFeQtRzYujPmFfdlqSfnc01VEMWE3O0ZrA,22
 pico_ioc/analysis.py,sha256=cxlg3F3bwRIb-kVIqHp1RLYj-sk-GuIgCChE-pf0a7c,4189
 pico_ioc/aop.py,sha256=VkmLzoztPbFjLIqBmXohcCNd4w6UC9ZrqYOE8DsMQ7I,14417
-pico_ioc/api.py,sha256=0pcRFHzhDcX8ijd67xAsVrTejwXuJKz7kTKRUrIuX2s,6161
-pico_ioc/component_scanner.py,sha256=S-9XNxrgyq_JFdc4Uqn2bEb-HxafSgIWylIurxyN_UA,7955
+pico_ioc/api.py,sha256=KlZjI_4pJfD_1T32DgmOykii6L1V-5Xtcynd5d57YIA,6400
+pico_ioc/component_scanner.py,sha256=rRZSQbJ7SkssJ5SJBr_m2ih-lpFvVnDQpt-JrYH5Xsg,8999
 pico_ioc/config_builder.py,sha256=7kcYIq1Yrb46Tic7uLeaCDvLA-Sa_p1PIoGF00mivso,2848
 pico_ioc/config_registrar.py,sha256=34iNQY1TUEPTXbb-QV1T-c5VKAn18hBcNt5MLhzDSfY,8456
 pico_ioc/config_runtime.py,sha256=qdPIbGMXOf6KWMM7cva6W-hhbhybEY0swZN01R1emCg,12756
 pico_ioc/constants.py,sha256=AhIt0ieDZ9Turxb_YbNzj11wUbBbzjKfWh1BDlSx2Nw,183
-pico_ioc/container.py,sha256=SEEJCUHIOUz4Dghdmac2rDrv65Zlm2wiBKZt4WbZoDc,21354
+pico_ioc/container.py,sha256=ipTpMwtCYuYfmJCjd7dfEtFFVR1PG0C1lZQp-wJ_UHw,21512
 pico_ioc/decorators.py,sha256=ru_YeqyJ3gbfb6M8WeJZlBxfcBBEuGDvxpHJGzU6FIs,6412
 pico_ioc/dependency_validator.py,sha256=BIR6pKntACiabF6CjNZ3m00RMnet9BPK1_9y1iCJ5KQ,4144
 pico_ioc/event_bus.py,sha256=NSfmFPX6Zm2OmMJz16gJFYMhh65iI0n9UlC9M8GmO0c,8428
@@ -16,10 +16,10 @@ pico_ioc/exceptions.py,sha256=FBuajj5g29hAGODt2tAWuy2sG5mQojdSddaqFzim-aY,2383
 pico_ioc/factory.py,sha256=oJXx_BYJuvV8oxYzs5I3gx9WM6uLYZ8GCc43gukNanc,1671
 pico_ioc/locator.py,sha256=JD6psgdGGsBoCwov-G76BrmTfKUoJ22sdwa6wVdmQV8,5064
 pico_ioc/provider_selector.py,sha256=pU7NbI5vifvUlJEjlRJmvveQUZVD47T24QmiP0CHRw0,1213
-pico_ioc/registrar.py,sha256=O22FYrMXQ4TvBf25b0CB1wwu9tjL-5e00n9Ubd8suNs,8394
-pico_ioc/scope.py,sha256=JmFJPSb9uG2oRSZ7YreCozOgqDHfYsYLcyCpqVI4luU,6427
-pico_ioc-2.1.3.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
-pico_ioc-2.1.3.dist-info/METADATA,sha256=-PWHmvXzShw_t9D-_vbGBN24aG7afVchr3ZFyGR0TrQ,12910
-pico_ioc-2.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-2.1.3.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-2.1.3.dist-info/RECORD,,
+pico_ioc/registrar.py,sha256=0abgnJMJrEvEyqsvxBNTi6wl0iJHHjSaw75IuqGk56c,8531
+pico_ioc/scope.py,sha256=TFchqFE9ooDCtYV_9YaLdeJDMtmLdNbB63nbZp-AqI8,6349
+pico_ioc-2.2.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_ioc-2.2.0.dist-info/METADATA,sha256=HnQ9xsjsyPFA7zCIkzkkHLSngVut4bZQUjHHBsk9PXI,12901
+pico_ioc-2.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-2.2.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-2.2.0.dist-info/RECORD,,