pico-ioc 0.5.2__tar.gz → 0.6.0__tar.gz

{pico_ioc-0.5.2 → pico_ioc-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 0.5.2
+Version: 0.6.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -156,10 +156,10 @@ print(COUNTER["value"])               # 1
 
 Starting with **v0.5.0**, Pico-IoC enforces **name-first resolution**:
 
-1. **Parameter name** (highest priority)
-2. **Exact type annotation**
-3. **MRO fallback** (walk base classes)
-4. **String(name)**
+1. **Parameter name** (highest priority)  
+2. **Exact type annotation**  
+3. **MRO fallback** (walk base classes)  
+4. **String(name)**  
 
 This means that if a dependency could match both by name and type, **the name match wins**.
 
@@ -185,6 +185,18 @@ class NameVsTypeFactory:
 container = init(__name__)
 assert container.get("choose") == "by-name"
 ```
+---
+
+## 📝 Notes on Annotations (PEP 563)
+
+Pico-IoC fully supports **postponed evaluation of annotations**
+(`from __future__ import annotations`, a.k.a. **PEP 563**) in Python 3.8–3.10.
+
+* Type hints are evaluated with `typing.get_type_hints` and safely resolved.
+* Missing dependencies always raise a **`NameError`**, never a `TypeError`.
+* Behavior is consistent across Python 3.8+ and Python 3.11+ (where PEP 563 is no longer default).
+
+This means you can freely use either direct type hints or string-based annotations in your components and factories, without breaking dependency injection.
 
 ---
 

{pico_ioc-0.5.2 → pico_ioc-0.6.0}/README.md

@@ -109,10 +109,10 @@ print(COUNTER["value"])               # 1
 
 Starting with **v0.5.0**, Pico-IoC enforces **name-first resolution**:
 
-1. **Parameter name** (highest priority)
-2. **Exact type annotation**
-3. **MRO fallback** (walk base classes)
-4. **String(name)**
+1. **Parameter name** (highest priority)  
+2. **Exact type annotation**  
+3. **MRO fallback** (walk base classes)  
+4. **String(name)**  
 
 This means that if a dependency could match both by name and type, **the name match wins**.
 
@@ -138,6 +138,18 @@ class NameVsTypeFactory:
 container = init(__name__)
 assert container.get("choose") == "by-name"
 ```
+---
+
+## 📝 Notes on Annotations (PEP 563)
+
+Pico-IoC fully supports **postponed evaluation of annotations**
+(`from __future__ import annotations`, a.k.a. **PEP 563**) in Python 3.8–3.10.
+
+* Type hints are evaluated with `typing.get_type_hints` and safely resolved.
+* Missing dependencies always raise a **`NameError`**, never a `TypeError`.
+* Behavior is consistent across Python 3.8+ and Python 3.11+ (where PEP 563 is no longer default).
+
+This means you can freely use either direct type hints or string-based annotations in your components and factories, without breaking dependency injection.
 
 ---
 

pico_ioc-0.6.0/doc4llm/architecture-pico-ioc.md

@@ -0,0 +1,288 @@
+# Pico-IoC Architecture & LLM Guide
+
+## What is Pico-IoC?
+
+Pico-IoC is a tiny, zero-dependency Inversion of Control (IoC) container for Python.  
+It discovers components via decorators, wires dependencies automatically, and instantiates everything eagerly by default (fail-fast).  
+You can opt into lazy creation via a lightweight proxy.
+
+Target Python: 3.8+  
+Core design goals: minimal API, predictable resolution, easy testing, framework-agnostic.
+
+---
+
+## Core Concepts (Glossary)
+
+* **Container (`PicoContainer`)**
+  Holds bindings (providers) and singletons. Keys may be classes or strings.
+
+* **Binder (`Binder`)**
+  A thin façade for plugins to `bind/has/get` during scan & lifecycle hooks.
+
+* **Decorators**
+  * `@component(cls=None, *, name=None, lazy=False)` → register a class.  
+    - Key: class type by default, or `name` (string) if provided.  
+    - `lazy=True` returns a `ComponentProxy` until first real use.
+  * `@factory_component` → register a factory class whose methods can provide components.
+  * `@provides(key, *, lazy=False)` → mark a factory method as a provider for `key` (string or type).
+
+* **Factory DI**
+  * Constructor of a `@factory_component` receives DI like regular components.
+  * Each `@provides` method can also have DI in its parameters (by name/type).
+  * Defaulted params are **optional**: if not bound, the method uses its default.
+
+* **Resolution Order**
+  1. **parameter name**, 2) type annotation, 3) MRO fallback, 4) `str(name)`.
+
+* **ComponentProxy**
+  A transparent proxy for lazy components that defers creation until first actual interaction.  
+  Forwards common dunder methods (e.g., `__len__`, `__getitem__`, `__iter__`, `__bool__`, operators, context managers, etc.).
+
+* **Re-entrancy Guard**
+  Accessing `container.get(...)` during package scanning raises a clear error (prevents re-entrant use).
+
+---
+
+## Lifecycle
+
+1. **init(root, …)**
+   * Scans `root` package (string/module).
+   * Auto-excludes the calling module by default (`auto_exclude_caller=True`).
+   * Calls plugin hooks (`before_scan`, `visit_class`, `after_scan`, `after_bind`, `before_eager`, `after_ready`).
+   * **Binding order**: components first, then factories.
+   * **Blueprint**: eagerly instantiate all non-lazy bindings. Errors fail startup.
+
+2. **get(key)**
+   Returns the singleton instance for `key` (creates if needed).  
+   For lazy bindings, returns a proxy first.
+
+---
+
+## How Pico-IoC Resolves Dependencies
+
+Given a constructor or provider method parameter `p`:
+
+* If a binding exists for the **parameter name**, use it.
+* Else if the **type annotation** is bound, use it.
+* Else try **MRO** (walk base classes) and use the first bound base type.
+* Else if `str(name)` is bound, use that.
+* Else: raise `NameError("No provider found for key: …")`.
+
+**Optional defaulted params**: If resolution fails and the param has a default (e.g., `hint: T = None`), the resolver **omits the argument** so Python uses the default.
+
+---
+
+## Quick Recipes
+
+### 1) Basic components
+```python
+from pico_ioc import component, init
+
+@component
+class Config:
+    url = "postgresql://…"
+
+@component
+class Repo:
+    def __init__(self, config: Config):  # type-based DI
+        self.url = config.url
+
+c = init(__name__)
+repo = c.get(Repo)
+````
+
+### 2) Inject by name
+
+```python
+from pico_ioc import component
+
+@component(name="fast_model")
+class Model:
+    pass
+
+@component
+class NeedsByName:
+    def __init__(self, fast_model):  # name-based DI (highest priority)
+        self.m = fast_model
+```
+
+### 3) Factory with lazy provider and provider-param DI
+
+```python
+from pico_ioc import factory_component, provides, component
+
+@component
+class Counter:
+    def __init__(self): self.value = 0
+
+@factory_component
+class Factory:
+    @provides("dataset", lazy=True)
+    def make_dataset(self, counter: Counter):  # DI into provider method
+        return list(range(counter.value, counter.value + 3))
+```
+
+### 4) Static/class methods as providers
+
+```python
+@factory_component
+class F:
+    @staticmethod
+    @provides("static_result", lazy=True)
+    def make_static():
+        return "ok"
+
+    @classmethod
+    @provides("class_result")
+    def make_class(cls):
+        return "ok"
+```
+
+---
+
+## Error Messages & What They Mean
+
+* **`NameError: No provider found for key: ...`**
+  A dependency couldn’t be resolved. Check the key being looked up:
+
+  * For name-based DI: ensure a binding with that exact name exists (`@component(name=...)` or `@provides("name")`).
+  * For type-based DI: ensure that class (or a base in its MRO) is provided.
+
+* **`RuntimeError: pico-ioc: re-entrant container access during scan.`**
+  Something called `get()` while scanning modules (e.g., at import time).
+  Move that call out of module top-level or mark the dependent thing `lazy=True` and defer access.
+
+---
+
+## Plugins & Extensions
+
+* Implement any subset of:
+
+  * `before_scan(package, binder)`
+  * `visit_class(module, cls, binder)`
+  * `after_scan(package, binder)`
+  * `after_bind(container, binder)`
+  * `before_eager(container, binder)`
+  * `after_ready(container, binder)`
+
+* The `Binder` lets you register extra bindings, e.g.:
+
+```python
+class MarkerPlugin:
+    def visit_class(self, module, cls, binder):
+        if cls.__name__ == "SpecialService" and not binder.has("marker"):
+            binder.bind("marker", lambda: {"ok": True}, lazy=False)
+```
+
+* Public helpers (also useful for plugins):
+
+  * `create_instance(cls, container)` – construct with DI & precedence rules.
+  * `resolve_param(container, inspect.Parameter)` – resolve a single param.
+
+---
+
+## Internals (Stable Behaviors)
+
+* **Singletons**: All components/providers default to singletons (first creation cached).
+* **Binding Order**: Components are bound **before** factories so factory constructors can be injected.
+* **Eager by default**: `lazy=False` (default) is instantiated at the end of `init()`.
+* **Lazy**: `lazy=True` yields a `ComponentProxy`; realization occurs on first real interaction.
+* **Provider DI**: Provider methods can declare DI params; defaults make them optional.
+* **Thread safety**: Scanning and resolution use `ContextVar`, isolating state per thread/async task.
+
+---
+
+## Troubleshooting Playbook (for an LLM)
+
+When a user asks for help:
+
+1. **Identify binding key**
+
+   * If they mention a quoted name, assume **string key**.
+   * If they mention a class, assume **type key**.
+
+2. **Check resolution path**
+
+   * Name → Type → MRO → `str(name)`.
+
+3. **Suggest fixes**
+
+   * For missing name: `@component(name="…")` or a `@provides("…")`.
+   * For type: ensure class is scanned or provided by a factory.
+   * For optional hint (`param: T = None`): remind that defaults are optional.
+
+4. **Re-entrancy**
+
+   * If errors mention “re-entrant during scan”, move `get()` out of import time.
+
+5. **Factories**
+
+   * Factory constructor and provider params both support DI.
+   * Lazy provider builds only on first use; eager builds at `init()`.
+
+6. **Testing advice**
+
+   * For missing dep scenarios, mark component/provider `lazy=True` and force realization in the test.
+
+---
+
+## Anti-Patterns to Avoid
+
+* Calling `container.get(...)` at module import time in scanned packages.
+* Expecting type-based injection when a **name** binding exists (name wins).
+* Providers that create new instances each call (Pico-IoC expects singletons; use callables if you need factories).
+
+---
+
+## Example: Minimal App Layout
+
+```
+myapp/
+  __init__.py
+  services/
+    __init__.py
+    components.py     # @component classes
+    factories.py      # @factory_component classes + @provides methods
+```
+
+```python
+# bootstrap.py
+import myapp
+from pico_ioc import init
+
+container = init(myapp)
+svc = container.get("heavy_service")
+```
+
+---
+
+## FAQ (short)
+
+* **Can I bind primitives or dicts?** Yes, via `@provides("name")` returning e.g. a dict.
+* **Thread safety?** Yes. Singletons are created once per container. ContextVar ensures safe state isolation.
+* **How do I exclude modules from scanning?** Use `init(root, exclude=callable)`.
+* **Can I scan by module string?** Yes: `init("myapp.services")`.
+
+---
+
+## Version Notes Relevant to LLM Answers
+
+* **v0.6.0**: `ComponentProxy` made fully transparent — supports operators, context managers, and more dunder methods.
+* **v0.5.2**: Name-first resolution; defaulted params in constructors and provider methods are optional.
+* Earlier versions: basic DI without name-first precedence.
+
+---
+
+## How to “Think” When Explaining Usage (LLM prompting tips)
+
+* Be explicit about the **binding key** (type vs string).
+* Map constructor/provider params to resolution rules.
+* Show tiny, runnable snippets (no external deps).
+* Prefer **lazy** for failure demos; prefer **eager** for production.
+* If user hits `NameError`, propose concrete fixes (name, type, factory).
+* Don’t promise async/background work — stick to code-level fixes.
+
+---
+
+End of document.
+

pico_ioc-0.6.0/doc4llm/usage-patterns.md

@@ -0,0 +1,198 @@
+# Usage Patterns for pico-ioc (LLM Guidance)
+
+This document provides examples of typical questions and answers an LLM should handle when assisting developers with **pico-ioc**.
+The goal is to give consistent, concise, and technically accurate responses.
+
+---
+
+## 1. General Questions
+
+**Q:** What is pico-ioc?
+**A:** pico-ioc is a lightweight Inversion of Control (IoC) and Dependency Injection (DI) container for Python.
+It uses decorators (`@component`, `@factory_component`, `@provides`) to register dependencies and automatically resolve them at runtime.
+It is inspired by frameworks like Spring (Java) but designed to be minimal, fast, and Pythonic.
+
+---
+
+## 2. How to Start
+
+**Q:** How do I initialize pico-ioc in my project?
+**A:**
+
+```python
+import pico_ioc
+import myapp
+
+container = pico_ioc.init(myapp)
+service = container.get(MyService)
+```
+
+This scans the `myapp` package for components and wires them automatically.
+
+---
+
+## 3. Registering Components
+
+**Q:** How do I register a class as a component?
+**A:**
+
+```python
+from pico_ioc import component
+
+@component
+class MyService:
+    def greet(self):
+        return "Hello from MyService!"
+```
+
+---
+
+## 4. Using Factories
+
+**Q:** How do I create instances using a factory?
+**A:**
+
+```python
+from pico_ioc import factory_component, provides
+
+class MyService:
+    def greet(self):
+        return "Hello!"
+
+@factory_component
+class MyFactory:
+    @provides("my_service")
+    def build_service(self) -> MyService:
+        return MyService()
+```
+
+Factories let you encapsulate creation logic. Each `@provides` method binds a key to the produced object.
+
+---
+
+## 5. Providing Interfaces
+
+**Q:** How do I bind an interface to an implementation?
+**A:**
+
+```python
+from pico_ioc import provides
+
+class Storage:
+    ...
+
+class FileStorage(Storage):
+    ...
+
+@provides(Storage)
+def provide_storage() -> Storage:
+    return FileStorage()
+```
+
+Now any class that requires `Storage` will receive a `FileStorage`.
+
+---
+
+## 6. Resolving Dependencies
+
+**Q:** How are constructor parameters injected?
+**A:** pico-ioc inspects type hints in constructors and provides the required dependencies.
+
+```python
+@component
+class UserService:
+    def __init__(self, storage: Storage):
+        self.storage = storage
+```
+
+When `UserService` is requested, pico-ioc automatically injects a `Storage`.
+
+---
+
+## 7. Thread Safety
+
+**Q:** Is pico-ioc thread-safe?
+**A:** Yes. Dependency resolution and scanning states are tracked using `ContextVar`, which isolates these flags per thread and per async task. This ensures safe operation in multithreaded and asynchronous environments without shared-state conflicts.
+
+---
+
+## 8. Lazy vs. Eager Components
+
+By default, bindings are **eager** (instantiated immediately).
+If `lazy=True` is passed, pico-ioc returns a `ComponentProxy` instead. The proxy defers creation until the first real use.
+
+```python
+from pico_ioc import component
+
+@component(lazy=True)
+class HeavyService:
+    def __init__(self):
+        print("Expensive init...")
+        self.value = 42
+
+container = pico_ioc.init(__name__)
+svc = container.get(HeavyService)  # not yet created
+print(svc.value)                   # triggers creation
+```
+
+**Note (since v0.6.0):** `ComponentProxy` fully forwards operators, attribute access, context manager protocols, etc., making lazy components behave transparently like the real object.
+
+---
+
+## 9. Best Practices
+
+* Always use type hints so dependencies can be resolved correctly.
+* Prefer `@component` for classes and `@provides` for interfaces.
+* Use factories (`@factory_component` + `@provides`) for advanced creation logic.
+* Avoid global state; let the container manage lifecycle.
+* Use `init(package)` at the root of your application to wire everything automatically.
+* Consider `lazy=True` for heavy or rarely used services.
+
+---
+
+## 10. Example Flow
+
+```python
+import pico_ioc
+from pico_ioc import component
+
+@component
+class Repo:
+    def fetch(self):
+        return "data"
+
+@component
+class Service:
+    def __init__(self, repo: Repo):
+        self.repo = repo
+
+    def run(self):
+        return f"Service using {self.repo.fetch()}"
+
+# Bootstrap
+import myapp
+container = pico_ioc.init(myapp)
+svc = container.get(Service)
+print(svc.run())
+```
+
+**Expected output:**
+
+```
+Service using data
+```
+
+---
+
+## 11. Troubleshooting
+
+* **Error:** "Cannot resolve parameter" → Add proper type hints.
+* **Error:** "No provider found" → Ensure the class/function is decorated with `@component` or `@provides`.
+* **Unexpected singleton reuse** → Check if you intended a new instance vs. a shared one.
+* **Lazy service not instantiated** → Remember: `lazy=True` returns a proxy, actual creation happens only on first real usage.
+
+---
+
+✅ With these usage patterns, an LLM should be able to explain **how pico-ioc works**, provide **practical examples**, and help users debug typical problems.
+**New in v0.6.0:** transparent `ComponentProxy` support for all Python protocols, making lazy components nearly indistinguishable from eager ones.
+

pico_ioc-0.6.0/src/pico_ioc/__init__.py

@@ -0,0 +1,27 @@
+from ._version import __version__
+from .container import PicoContainer, Binder
+from .decorators import component, factory_component, provides
+from .plugins import PicoPlugin
+from .resolver import Resolver
+from .api import init, reset
+from .proxy import ComponentProxy
+
+try:
+    from ._version import __version__
+except Exception:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "__version__",
+    "PicoContainer",
+    "Binder",
+    "PicoPlugin",
+    "init",
+    "reset", 
+    "component",
+    "factory_component",
+    "provides",
+    "resolve_param",
+    "create_instance",
+]
+

pico_ioc-0.6.0/src/pico_ioc/_state.py

@@ -0,0 +1,8 @@
+# pico_ioc/_state.py
+from contextvars import ContextVar
+
+_scanning: ContextVar[bool] = ContextVar("pico_scanning", default=False)
+_resolving: ContextVar[bool] = ContextVar("pico_resolving", default=False)
+
+_container = None
+

pico_ioc-0.6.0/src/pico_ioc/_version.py

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

pico_ioc-0.6.0/src/pico_ioc/api.py

@@ -0,0 +1,74 @@
+import inspect
+import logging
+from typing import Callable, Optional, Tuple
+from .container import PicoContainer, Binder
+from .plugins import PicoPlugin
+from .scanner import scan_and_configure
+from . import _state
+
+
+def reset() -> None:
+    _state._container = None
+
+
+def init(
+    root_package,
+    *,
+    exclude: Optional[Callable[[str], bool]] = None,
+    auto_exclude_caller: bool = True,
+    plugins: Tuple[PicoPlugin, ...] = (),
+    reuse: bool = True,
+) -> PicoContainer:
+    if reuse and _state._container:
+        return _state._container
+
+    combined_exclude = exclude
+    if auto_exclude_caller:
+        try:
+            caller_frame = inspect.stack()[1].frame
+            caller_module = inspect.getmodule(caller_frame)
+            caller_name = getattr(caller_module, "__name__", None)
+        except Exception:
+            caller_name = None
+        if caller_name:
+            if combined_exclude is None:
+                def combined_exclude(mod: str, _caller=caller_name):
+                    return mod == _caller
+            else:
+                prev = combined_exclude
+                def combined_exclude(mod: str, _caller=caller_name, _prev=prev):
+                    return mod == _caller or _prev(mod)
+
+    container = PicoContainer()
+    binder = Binder(container)
+    logging.info("Initializing pico-ioc...")
+
+    tok = _state._scanning.set(True)
+    try:
+        scan_and_configure(root_package, container, exclude=combined_exclude, plugins=plugins)
+    finally:
+        _state._scanning.reset(tok)
+
+    for pl in plugins:
+        try:
+            getattr(pl, "after_bind", lambda *a, **k: None)(container, binder)
+        except Exception:
+            logging.exception("Plugin after_bind failed")
+    for pl in plugins:
+        try:
+            getattr(pl, "before_eager", lambda *a, **k: None)(container, binder)
+        except Exception:
+            logging.exception("Plugin before_eager failed")
+
+    container.eager_instantiate_all()
+
+    for pl in plugins:
+        try:
+            getattr(pl, "after_ready", lambda *a, **k: None)(container, binder)
+        except Exception:
+            logging.exception("Plugin after_ready failed")
+
+    logging.info("Container configured and ready.")
+    _state._container = container
+    return container
+