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

{pico_ioc-0.5.2 → pico_ioc-1.0.0}/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.8", "3.9", "3.10", "3.11", "3.12", "3.13" ]
+        python-version: [ "3.10", "3.11", "3.12", "3.13" ]
 
     steps:
       - name: Checkout

pico_ioc-1.0.0/.llm/ARCHITECTURE.md

@@ -0,0 +1,282 @@
+# pico-ioc — Architecture
+
+> Scope: internal model, wiring algorithm, lifecycle, and design trade-offs.  
+> Non-goals: user tutorials or recipes (see `GUIDE.md`), product pitch (see `OVERVIEW.md`).
+
+> ⚠️ **Requires Python 3.10+** (uses `typing.Annotated` and `include_extras=True`).
+
+---
+
+## 1) Design goals & non-goals
+
+**Goals**
+
+* **Tiny, predictable DI** for Python apps (CLIs, Flask/FastAPI, services).
+* **Fail fast** at bootstrap; deterministic resolution.
+* **Ergonomic**: annotate constructors, avoid runtime reflection tricks.
+* **Framework-agnostic**: no hard dependency on Flask/FastAPI/etc.
+* **Safe by default**: thread/async friendly, no global mutable singletons.
+
+**Non-goals**
+
+* Full Spring-like feature set (AOP, complex scopes, bean post-processors).
+* Runtime reconfiguration or hot-swap of graphs.
+* Magical auto-imports across the filesystem.
+
+---
+
+## 2) High-level model
+
+* **Component**: class marked with `@component`. Instantiated by the container.
+* **Factory component**: class marked with `@factory_component` that owns one or more **providers** declared via `@provides(key=TypeOrToken)`. Providers return *externals* (e.g., `Flask`, clients, engines).
+* **Container**: built by `pico_ioc.init(module_or_list)`; resolves dependencies with `container.get(KeyOrType)`.
+
+### Bootstrap sequence (simplified)
+
+```mermaid
+sequenceDiagram
+    participant App as Your package(s)
+    participant IOC as pico-ioc Container
+    App->>IOC: init([app, overrides?])
+    IOC->>App: scan decorators (@component, @factory_component)
+    IOC->>IOC: register providers (key -> factory)
+    IOC->>IOC: validate graph (constructor types, duplicates)
+    App->>IOC: get(Service)
+    IOC->>IOC: resolve deps (Repo, Config, ...)
+    IOC-->>App: instance(Service)
+````
+
+---
+
+## 3) Discovery & registration
+
+1. **Scan inputs** passed to `init(...)`: a module or list of modules/packages.
+2. **Collect**:
+
+   * `@component` classes → registered by **type** (the class itself).
+   * `@factory_component` classes → introspected for `@provides(key=...)` methods.
+   * `@plugin` classes → collected if explicitly passed to `init(…, plugins=(…))`.
+3. **Registry** (immutable after bootstrap):
+
+   * `key -> provider` map. Keys are usually **types**. String tokens are supported but discouraged.
+
+> **Invariant:** A key has **at most one** active provider; the **last registration wins**.
+> This enables test overrides by ordering `init([app, test_overrides])`.
+
+---
+
+## 4) Resolution algorithm (deterministic)
+
+When constructing a component `C`:
+
+1. Inspect `__init__(self, ...)` and collect **type-annotated** parameters (excluding `self`).
+2. For each parameter `p: T` resolve **by key** using this order:
+
+   1. **Exact type** `T`
+   2. **MRO walk**: first registered base class or protocol
+   3. **String key** (only if `@provides(key="token")` was used)
+3. Instantiate dependencies depth-first; memoize singletons.
+4. Construct `C` with resolved instances.
+
+**Failure modes**
+
+* No provider for a required key → **bootstrap error** (fail fast).
+* Ambiguous/incompatible registrations → **bootstrap error** with a precise hint.
+
+### 4b) Collection resolution
+
+If a constructor requests `list[T]` or `list[Annotated[T, Q]]`:
+
+* The container resolves **all** registered providers compatible with `T`.
+* If qualifiers are present (`Q`), only matching components are returned.
+* Order is stable by discovery/registration; no implicit sorting.
+* Empty list if no matches.
+
+---
+
+## 5) Lifecycles & scopes
+
+* **Singleton per container** (default): each key is created once and cached.
+* **Lazy proxies (optional)**: `@component(lazy=True)` defers instantiation until first use. Use sparingly; prefer eager to surface errors early.
+
+> **Why singleton:** It matches typical app composition (config, DB clients, HTTP apps) and keeps DI simple and fast.
+
+---
+
+## 6) Factories & providers
+
+Use `@factory_component` to integrate **externals**:
+
+```python
+from pico_ioc import factory_component, provides
+from flask import Flask
+
+@factory_component
+class AppFactory:
+    @provides(key=Flask)
+    def provide_flask(self) -> Flask:
+        app = Flask(__name__)
+        app.config["JSON_AS_ASCII"] = False
+        return app
+```
+
+* **Providers** should be **pure constructors** (no long-running work).
+* Prefer **typed keys** (e.g., `Flask`) over string tokens.
+
+---
+
+## 7) Concurrency model
+
+* Container state is **immutable after init**.
+* Resolution cache is **thread/async safe** via internal isolation (no global singletons).
+* Instances you create **must** be thread-safe if shared (container can’t fix non-safe libs).
+
+---
+
+## 8) Error handling & diagnostics
+
+* **Bootstrap phase**:
+
+  * Missing providers → raise with the exact parameter/type.
+  * Duplicate keys → last wins; log/trace retains registration order for debugging.
+  * Type annotation mismatch → explicit error naming the offending `__init__` param.
+* **Runtime**:
+
+  * Exceptions bubble from provider/constructor; container stack traces include the dependency chain (key path).
+
+Tip: Keep constructors **cheap** (I/O at the edges, e.g., in start/serve methods).
+
+---
+
+## 9) Configuration
+
+* Treat config as a **component**:
+
+```python
+@component
+class Config:
+    WORKERS: int = int(os.getenv("WORKERS", "4"))
+    DEBUG: bool = os.getenv("DEBUG", "0") == "1"
+```
+
+* Inject `Config` wherever needed; do not read `os.getenv` scattered across the codebase.
+
+---
+
+## 10) Extensibility & overrides
+
+* **Test overrides**: register a factory after the app module.
+
+```python
+@factory_component
+class TestOverrides:
+    @provides(key=Repo)   # same key as production
+    def provide_repo(self) -> Repo:
+        return FakeRepo()
+```
+
+Then:
+
+```python
+c = init([app, test_overrides])  # overrides win by order
+```
+
+* **Multi-env composition**: define `app.prod`, `app.dev`, `app.test` packages that import different provider sets, then `init([app.prod])` etc.
+
+### Plugins
+
+Classes decorated with `@plugin` and implementing `PicoPlugin` can observe lifecycle events:
+
+* `before_scan(package, binder)`
+* `after_ready(container, binder)`
+
+They are passed explicitly to `init(..., plugins=(MyPlugin(),))`.
+
+---
+
+## 11) Performance notes
+
+* **O(1)** provider lookup by key; no reflection at call sites after bootstrap.
+* Eager construction surfaces failures early and warms caches.
+* Keep providers idempotent and cheap; push heavy I/O to runtime methods.
+
+---
+
+## 12) Security & boundaries
+
+* The container **does not** open sockets/files or spawn threads by itself.
+* Side effects belong to **your components**. Keep providers deterministic.
+* Avoid storing secrets in code; pass secrets via your own config component.
+
+---
+
+## 13) Reference diagrams
+
+### Registry & resolution (class diagram)
+
+```mermaid
+classDiagram
+    class Container {
+      +get(key) instance
+      -registry: Map[key, Provider]
+      -cache: Map[key, instance]
+    }
+    class Provider {
+      +create() instance
+      +key
+    }
+    class ComponentProvider
+    class FactoryProvider
+    Container "1" --> "*" Provider
+    Provider <|-- ComponentProvider
+    Provider <|-- FactoryProvider
+```
+
+### Resolution flow (activity)
+
+```mermaid
+flowchart TD
+  A[Request instance for Type T] --> B{Cached?}
+  B -- yes --> Z[Return cached]
+  B -- no --> C[Find provider for T (type→MRO→token)]
+  C -- none --> E[Raise bootstrap error]
+  C -- found --> D[Resolve constructor args recursively]
+  D --> F[Instantiate]
+  F --> G[Cache instance]
+  G --> Z[Return instance]
+```
+
+---
+
+## 14) Rationale & trade-offs
+
+* **Typed keys first** → better ergonomics, editor support, less foot-guns than strings.
+* **Singleton scope** → keeps mental model simple; Python apps rarely need per-request scoping at the container level (push that to frameworks).
+* **No global state** → explicit container ownership clarifies boundaries and testability.
+* **Fail fast** → configuration/graph problems are caught at start, not mid-request.
+
+---
+
+## 15) Appendix: FAQs (architecture-level)
+
+* *Why not metaclass magic to auto-wire everything?*
+  Determinism and debuggability. Explicit decorators and typed constructors win.
+
+* *Can I lazy-load everything?*
+  You can, but you shouldn’t. Lazy only where it truly reduces cost without hiding errors.
+
+* *How do I integrate with Flask/FastAPI?*
+  Provide the app/client via a factory (`@provides(key=Flask)`), then `container.get(Flask)` in your bootstrap. See `GUIDE.md`.
+
+### Public API helper
+
+`export_public_symbols_decorated` builds `__getattr__`/`__dir__` for a package’s `__init__.py`,
+auto-exporting all `@component`, `@factory_component`, and `@plugin` classes, plus any `__all__`.
+
+---
+
+**TL;DR**
+`pico-ioc` builds a **deterministic dependency graph** at startup from decorated components, factories, and plugins.
+It resolves by **type**, supports **collection injection with qualifiers**, memoizes singletons, and fails fast — so your app wiring stays **predictable, testable, and framework-agnostic**.
+
+

pico_ioc-1.0.0/.llm/DECISIONS.md

@@ -0,0 +1,118 @@
+# DECISIONS.md — pico-ioc
+
+This document records **technical and architectural decisions** made for pico-ioc.  
+Each entry has a rationale and implications. If a decision is revoked, it should be marked as **[REVOKED]** with a link to the replacement.
+
+---
+
+## ✅ Current Decisions
+
+### 1. Minimum Python version: **3.10**
+- **Decision**: Drop support for Python 3.8 and 3.9. Require Python **3.10+**.
+- **Rationale**:  
+  * Uses `typing.Annotated` and `typing.get_type_hints(..., include_extras=True)`.  
+  * Simplifies code paths and avoids backports/conditionals.  
+  * Encourages modern typing practices.
+- **Implications**:  
+  * Users on older runtimes must upgrade.  
+  * CI/CD matrix only tests Python 3.10+.
+
+---
+
+### 2. Resolution order: **name-first**
+- **Decision**: Parameter name has precedence over type annotation.  
+- **Order**: **param name → exact type → MRO fallback → string token**.
+- **Rationale**:  
+  * Matches ergonomic use-cases (config by name).  
+  * Keeps deterministic behavior and avoids ambiguity.
+- **Implications**:  
+  * Breaking change from earlier versions (<0.5.0).  
+  * Documented in README and GUIDE.
+
+---
+
+### 3. Lifecycle: **singleton per container**
+- **Decision**: Every provider produces exactly one instance per container.  
+- **Rationale**:  
+  * Matches common Python app architecture (config, DB clients, service classes).  
+  * Simple mental model, cheap lookups.  
+- **Implications**:  
+  * No per-request or session scopes at the IoC level (delegate that to frameworks).  
+  * Lazy proxies supported via `lazy=True`.
+
+---
+
+### 4. Fail-fast bootstrap
+- **Decision**: All eager components are instantiated immediately after `init()`.  
+- **Rationale**:  
+  * Surfaces missing dependencies early.  
+  * Avoids hidden runtime errors deep into request handling.  
+- **Implications**:  
+  * Slower startup if many components are eager.  
+  * Recommended to keep constructors cheap.
+
+---
+
+### 5. Plugins: **explicit registration**
+- **Decision**: Plugins must be passed explicitly to `init(..., plugins=(...))`.  
+- **Rationale**:  
+  * Keeps scanning predictable and avoids magical discovery.  
+  * Encourages explicit boundaries in app wiring.
+- **Implications**:  
+  * More verbose in user code, but safer and testable.  
+  * `@plugin` decorator only marks, does not auto-register.
+
+---
+
+### 6. Public API helper (`export_public_symbols_decorated`)
+- **Decision**: Auto-export all decorated classes/components/plugins via `__getattr__`/`__dir__`.  
+- **Rationale**:  
+  * Reduces `__init__.py` boilerplate.  
+  * Encourages convention-over-configuration.  
+- **Implications**:  
+  * Explicit imports may be replaced by dynamic export.  
+  * Errors in scanning are suppressed (non-fatal).
+
+---
+
+## ❌ Won’t-Do Decisions
+
+### 1. Alternative scopes (request/session)
+- **Decision**: no additional scopes beyond *singleton per container* will be implemented.  
+- **Rationale**:  
+  * The simplicity of the current model (one instance per container) is a core value of pico-ioc.  
+  * Web frameworks (Flask, FastAPI, etc.) already manage request/session lifecycles.  
+  * Adding scopes would introduce unnecessary complexity and ambiguity about object ownership.  
+
+---
+
+### 2. Asynchronous providers
+- **Decision**: no support for `async def` components or asynchronous resolution inside the container.  
+- **Rationale**:  
+  * Keeping the library **100% synchronous** preserves the current API (`container.get(...)` is always immediate).  
+  * Async support would require event-loop integration, `await` semantics, and multiple runtime strategies → breaking simplicity.  
+  * If a dependency needs async initialization, it should be handled inside the component itself, not by the container.  
+
+---
+
+### 3. Hot reload / dynamic re-scan
+- **Decision**: no hot reload or dynamic re-scan of modules will be supported.  
+- **Rationale**:  
+  * Contradicts the **fail-fast** philosophy (surface errors at startup).  
+  * Breaks the **determinism** guarantee (container is immutable after `init()`).  
+  * Makes debugging harder: old instances may linger, state may become inconsistent, resources may leak.  
+  * Development-time hot reload is already handled by frameworks (`uvicorn --reload`, etc.).  
+
+---
+
+📌 **Summary:** pico-ioc stays **simple, deterministic, and fail-fast**.  
+Features that add complexity (alternative scopes, async providers, hot reload) are intentionally excluded. 
+
+---
+
+## 📜 Changelog of Decisions
+
+- **2025-08**: Dropped Python 3.8/3.9 support, minimum 3.10.  
+- **2025-08**: Clarified resolution order as *name-first*.  
+- **2025-08**: Documented lifecycle, plugins, and fail-fast policy.  
+

pico_ioc-1.0.0/.llm/GUIDE.md

@@ -0,0 +1,296 @@
+# GUIDE.md — pico-ioc
+
+> **Mission:** make dependency wiring trivial so you can ship faster and shorten feedback cycles.  
+> ⚠️ **Requires Python 3.10+** (uses `typing.Annotated` and `include_extras=True`).
+
+This guide shows how to structure a Python app with **pico-ioc**: define components, provide dependencies, bootstrap a container, and run web/CLI code predictably.
+
+---
+
+## 1) Core concepts
+
+* **Component**: a class managed by the container. Use `@component`.
+* **Factory component**: a class that *provides* concrete instances (e.g., `Flask()`, clients). Use `@factory_component`.
+* **Provider**: a method on a factory that returns a dependency and declares its **key** (usually a type). Use `@provides(key=Type)` so consumers can request by type.
+* **Container**: built via `pico_ioc.init(package_or_module)`. Resolve with `container.get(TypeOrClass)`.
+
+Resolution rule of thumb: **ask by type** (e.g., `container.get(Flask)` or inject `def __init__(..., app: Flask)`).
+
+---
+
+## 2) Quick start (Hello DI)
+
+```python
+# app/config.py
+from pico_ioc import component
+
+@component
+class Config:
+    DB_URL = "sqlite:///demo.db"
+````
+
+```python
+# app/repo.py
+from pico_ioc import component
+from .config import Config
+
+@component
+class Repo:
+    def __init__(self, cfg: Config):
+        self._url = cfg.DB_URL
+    def fetch(self) -> str:
+        return f"fetching from {self._url}"
+```
+
+```python
+# app/service.py
+from pico_ioc import component
+from .repo import Repo
+
+@component
+class Service:
+    def __init__(self, repo: Repo):
+        self.repo = repo
+    def run(self) -> str:
+        return self.repo.fetch()
+```
+
+```python
+# main.py
+from pico_ioc import init
+import app
+
+container = init(app)          # build the container from the package
+svc = container.get(app.service.Service)
+print(svc.run())               # -> "fetching from sqlite:///demo.db"
+```
+
+Run:
+
+```bash
+python main.py
+```
+
+---
+
+## 3) Web example (Flask)
+
+```python
+# app/app_factory.py
+from pico_ioc import factory_component, provides
+from flask import Flask
+
+@factory_component
+class AppFactory:
+    @provides(key=Flask)
+    def provide_flask(self) -> Flask:
+        app = Flask(__name__)
+        app.config["JSON_AS_ASCII"] = False
+        return app
+```
+
+```python
+# app/api.py
+from pico_ioc import component
+from flask import Flask, jsonify
+
+@component
+class ApiApp:
+    def __init__(self, app: Flask):
+        self.app = app
+        self._routes()
+
+    def _routes(self):
+        @self.app.get("/health")
+        def health():
+            return jsonify(status="ok")
+```
+
+```python
+# web.py
+from pico_ioc import init
+from flask import Flask
+import app
+
+c = init(app)
+flask_app = c.get(Flask)
+
+if __name__ == "__main__":
+    flask_app.run(host="0.0.0.0", port=5000)
+```
+
+Run:
+
+```bash
+python web.py
+# GET http://localhost:5000/health -> {"status":"ok"}
+```
+
+---
+
+## 4) Configuration patterns
+
+**Environment-backed config:**
+
+```python
+# app/config.py
+import os
+from pico_ioc import component
+
+@component
+class Config:
+    WORKERS: int = int(os.getenv("WORKERS", "4"))
+    DEBUG: bool = os.getenv("DEBUG", "0") == "1"
+```
+
+**Inject where needed** (constructor injection keeps code testable):
+
+```python
+@component
+class Runner:
+    def __init__(self, cfg: Config):
+        self._debug = cfg.DEBUG
+```
+
+---
+
+## 5) Testing & overrides
+
+Define a **test factory** that provides fakes using the same keys:
+
+```python
+# tests/test_overrides.py
+from pico_ioc import factory_component, provides
+from app.repo import Repo
+
+class FakeRepo(Repo):
+    def fetch(self) -> str:
+        return "fake-data"
+
+@factory_component
+class TestOverrides:
+    @provides(key=Repo)
+    def provide_repo(self) -> Repo:
+        return FakeRepo()
+```
+
+Build the container for tests with both packages (app + overrides):
+
+```python
+# tests/test_service.py
+from pico_ioc import init
+import app
+from tests import test_overrides
+
+def test_service_fetch():
+    c = init([app, test_overrides])   # pass a list (composition root for tests)
+    svc = c.get(app.service.Service)
+    assert svc.run() == "fake-data"
+```
+
+> Pattern: use a **composition module** per environment (prod/test) and call `init([...])` with the modules that declare your providers. Providers registered later override earlier ones for the same key.
+
+---
+
+## 5b) Qualifiers & collection injection
+
+```python
+from typing import Protocol, Annotated
+from pico_ioc import component, Qualifier, qualifier
+
+class Handler(Protocol):
+    def handle(self, s: str) -> str: ...
+
+PAYMENTS = Qualifier("payments")
+
+@component
+@qualifier(PAYMENTS)
+class StripeHandler(Handler): ...
+
+@component
+@qualifier(PAYMENTS)
+class PaypalHandler(Handler): ...
+
+@component
+class Orchestrator:
+    def __init__(self, handlers: list[Annotated[Handler, PAYMENTS]]):
+        self.handlers = handlers
+
+    def run(self, s: str) -> list[str]:
+        return [h.handle("ok") for h in self.handlers]
+```
+
+If you request `list[Handler]` you get **all** implementations.
+If you request `list[Annotated[Handler, PAYMENTS]]`, you only get the tagged ones.
+
+---
+
+## 5c) Plugins & Public API helper
+
+```python
+from pico_ioc import plugin
+from pico_ioc.plugins import PicoPlugin
+
+@plugin
+class TracingPlugin(PicoPlugin):
+    def before_scan(self, package, binder):
+        print(f"Scanning {package}")
+    def after_ready(self, container, binder):
+        print("Container ready")
+```
+
+Register explicitly:
+
+```python
+from pico_ioc import init
+import app
+
+c = init(app, plugins=(TracingPlugin(),))
+```
+
+And to expose your app’s API cleanly:
+
+```python
+# app/__init__.py
+from pico_ioc.public_api import export_public_symbols_decorated
+__getattr__, __dir__ = export_public_symbols_decorated("app", include_plugins=True)
+```
+
+Now you can import directly:
+
+```python
+from app import Service, Config, TracingPlugin
+```
+
+---
+
+## 6) Tips & guardrails
+
+* **Ask by type**: inject `Flask`, `Config`, `Repo` instead of strings.
+* **Keep constructors cheap**: do not perform I/O in `__init__`.
+* **Small components**: one responsibility per component; wire them in service classes.
+* **Factories provide externals**: frameworks, clients, DB engines belong in `@factory_component` providers.
+* **Fail fast**: build the container at startup and crash early if a dependency is missing.
+* **No globals**: let the container own lifecycle; fetch via `container.get(...)` only at the edges (bootstrap).
+
+---
+
+## 7) Troubleshooting
+
+* **“No provider for X”**
+  Ensure a `@provides(key=X)` exists in a module passed to `init(...)`, and your constructor type annotation is exactly `X`.
+
+* **Wrong instance injected**
+  Check for duplicate providers for the same key. The last registered wins; control order via the list passed to `init([module_a, module_b])`.
+
+* **Circular imports**
+  Split components or move heavy imports into providers. Keep modules acyclic where possible.
+
+* **Flask not found**
+  Verify `from flask import Flask` and that your factory uses `@provides(key=Flask)`. Resolve it with `container.get(Flask)`.
+
+---
+
+**TL;DR**
+Decorate components, provide externals by type, `init()` once, and let the container do the wiring—so you can **run tests, serve web apps, or batch jobs with minimal glue**.
+