pico-ioc 2.0.4__py3-none-any.whl → 2.1.0__py3-none-any.whl

{pico_ioc-2.0.4.dist-info → pico_ioc-2.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 2.0.4
+Version: 2.1.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -68,13 +68,13 @@ It brings *Inversion of Control* and *dependency injection* to Python in a deter
 
 ## ⚖️ Core Principles
 
--   **Single Purpose** – Do one thing: dependency management.
--   **Declarative** – Use simple decorators (`@component`, `@factory`, `@configuration`) instead of config files or YAML magic.
--   **Deterministic** – No hidden scanning or side-effects; everything flows from an explicit `init()`.
--   **Async-Native** – Fully supports async providers, async lifecycle hooks, and async interceptors.
--   **Fail-Fast** – Detects missing bindings and circular dependencies at bootstrap.
--   **Testable by Design** – Use `overrides` and `profiles` to swap components instantly.
--   **Zero Core Dependencies** – Built entirely on the Python standard library. Optional features may require external packages (see Installation).
+- **Single Purpose** – Do one thing: dependency management.
+- **Declarative** – Use simple decorators (`@component`, `@factory`, `@provides`, `@configured`) instead of complex config files.
+- **Deterministic** – No hidden scanning or side-effects; everything flows from an explicit `init()`.
+- **Async-Native** – Fully supports async providers, async lifecycle hooks (`__ainit__`), and async interceptors.
+- **Fail-Fast** – Detects missing bindings and circular dependencies at bootstrap (`init()`).
+- **Testable by Design** – Use `overrides` and `profiles` to swap components instantly.
+- **Zero Core Dependencies** – Built entirely on the Python standard library. Optional features may require external packages (see Installation).
 
 ---
 
@@ -83,25 +83,24 @@ It brings *Inversion of Control* and *dependency injection* to Python in a deter
 As Python systems evolve, wiring dependencies by hand becomes fragile and unmaintainable.
 **Pico-IoC** eliminates that friction by letting you declare how components relate — not how they’re created.
 
-| Feature        | Manual Wiring              | With Pico-IoC                   |
-| :------------- | :------------------------- | :------------------------------ |
-| Object creation| `svc = Service(Repo(Config()))` | `svc = container.get(Service)`  |
-| Replacing deps | Monkey-patch               | `overrides={Repo: FakeRepo()}`  |
-| Coupling       | Tight                      | Loose                           |
-| Testing        | Painful                    | Instant                         |
-| Async support  | Manual                     | Built-in                        |
+| Feature         | Manual Wiring              | With Pico-IoC                     |
+| :-------------- | :------------------------- | :-------------------------------- |
+| Object creation | `svc = Service(Repo(Config()))` | `svc = container.get(Service)`    |
+| Replacing deps  | Monkey-patch               | `overrides={Repo: FakeRepo()}`    |
+| Coupling        | Tight                      | Loose                             |
+| Testing         | Painful                    | Instant                           |
+| Async support   | Manual                     | Built-in (`aget`, `__ainit__`, ...) |
 
 ---
 
-## 🧩 Highlights (v2.0.0)
+## 🧩 Highlights (v2.0+)
 
--   **Full redesign:** unified architecture with simpler, more powerful APIs.
--   **Async-aware AOP system** — method interceptors via `@intercepted_by`.
--   **Typed configuration** — dataclasses with JSON/YAML/env sources.
--   **Scoped resolution** — singleton, prototype, request, session, transaction.
--   **UnifiedComponentProxy** — transparent lazy/AOP proxy supporting serialization.
--   **Tree-based configuration runtime** with reusable adapters and discriminators.
--   **Observable container context** with stats, health checks, and async cleanup.
+- **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.
 
 ---
 
@@ -109,7 +108,7 @@ As Python systems evolve, wiring dependencies by hand becomes fragile and unmain
 
 ```bash
 pip install pico-ioc
-```
+````
 
 For optional features, you can install extras:
 
@@ -121,50 +120,68 @@ For optional features, you can install extras:
 
     (Requires `PyYAML`)
 
-  * **Dependency Graph Export:**
+  * **Dependency Graph Export (Rendering):**
 
     ```bash
-    pip install pico-ioc[graphviz]
+    # You still need Graphviz command-line tools installed separately
+    # This extra is currently not required by the code,
+    # as export_graph generates the .dot file content directly.
+    # pip install pico-ioc[graphviz] # Consider removing if not used by code
     ```
 
-    (Requires the `graphviz` Python package and the Graphviz command-line tools)
-
 -----
 
-## ⚙️ Quick Example
+## ⚙️ Quick Example (Unified Configuration)
 
 ```python
+import os
 from dataclasses import dataclass
-from pico_ioc import component, configuration, init
+from pico_ioc import component, configured, configuration, init, EnvSource
 
-@configuration
+# 1. Define configuration with @configured
+@configured(prefix="APP_", mapping="auto") # Auto-detects flat mapping
 @dataclass
 class Config:
     db_url: str = "sqlite:///demo.db"
 
+# 2. Define components
 @component
 class Repo:
-    def __init__(self, cfg: Config):
+    def __init__(self, cfg: Config): # Inject config
         self.cfg = cfg
     def fetch(self):
         return f"fetching from {self.cfg.db_url}"
 
 @component
 class Service:
-    def __init__(self, repo: Repo):
+    def __init__(self, repo: Repo): # Inject Repo
         self.repo = repo
     def run(self):
         return self.repo.fetch()
 
-container = init(modules=[__name__])
+# --- Example Setup ---
+os.environ['APP_DB_URL'] = 'postgresql://user:pass@host/db'
+
+# 3. Build configuration context
+config_ctx = configuration(
+    EnvSource(prefix="") # Read APP_DB_URL from environment
+)
+
+# 4. Initialize container
+container = init(modules=[__name__], config=config_ctx) # Pass context via 'config'
+
+# 5. Get and use the service
 svc = container.get(Service)
 print(svc.run())
+
+# --- Cleanup ---
+del os.environ['APP_DB_URL']
 ```
 
 **Output:**
 
 ```
-fetching from sqlite:///demo.db
+fetching from postgresql://user:pass@host/db
 ```
 
 -----
@@ -175,7 +192,16 @@ fetching from sqlite:///demo.db
 class FakeRepo:
     def fetch(self): return "fake-data"
 
-container = init(modules=[__name__], overrides={Repo: FakeRepo()})
+# Build configuration context (might be empty or specific for test)
+test_config_ctx = configuration()
+
+# Use overrides during init
+container = init(
+    modules=[__name__],
+    config=test_config_ctx,
+    overrides={Repo: FakeRepo()} # Replace Repo with FakeRepo
+)
+
 svc = container.get(Service)
 assert svc.run() == "fake-data"
 ```
@@ -185,23 +211,46 @@ assert svc.run() == "fake-data"
 ## 🩺 Lifecycle & AOP
 
 ```python
-from pico_ioc import intercepted_by, MethodInterceptor, MethodCtx
+import time # For example
+from pico_ioc import component, init, intercepted_by, MethodInterceptor, MethodCtx
 
+# Define an interceptor component
+@component
 class LogInterceptor(MethodInterceptor):
     def invoke(self, ctx: MethodCtx, call_next):
-        print(f"→ calling {ctx.name}")
-        res = call_next(ctx)
-        print(f"← {ctx.name} done")
-        return res
+        print(f"→ calling {ctx.cls.__name__}.{ctx.name}")
+        start = time.perf_counter()
+        try:
+            res = call_next(ctx)
+            duration = (time.perf_counter() - start) * 1000
+            print(f"← {ctx.cls.__name__}.{ctx.name} done ({duration:.2f}ms)")
+            return res
+        except Exception as e:
+            duration = (time.perf_counter() - start) * 1000
+            print(f"← {ctx.cls.__name__}.{ctx.name} failed ({duration:.2f}ms): {e}")
+            raise
 
 @component
 class Demo:
-    @intercepted_by(LogInterceptor)
+    @intercepted_by(LogInterceptor) # Apply the interceptor
     def work(self):
+        print("   Working...")
+        time.sleep(0.01)
         return "ok"
 
+# Initialize container (must scan module containing interceptor too)
 c = init(modules=[__name__])
-c.get(Demo).work()
+result = c.get(Demo).work()
+print(f"Result: {result}")
+```
+
+**Output:**
+
+```
+→ calling Demo.work
+   Working...
+← Demo.work done (10.xxms)
+Result: ok
 ```
 
 -----
@@ -233,7 +282,7 @@ tox
 
 ## 🧾 Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) — *Full redesign for v2.0.0.*
+See [CHANGELOG.md](./CHANGELOG.md) — *Significant redesigns and features in v2.0+.*
 
 -----
 

pico_ioc-2.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+pico_ioc/__init__.py,sha256=pxYvrunT9cFAXxGbow5TRlzRXDVvm4E7L6PT1UkPeUw,2394
+pico_ioc/_version.py,sha256=LbU43-7hsLmdXWI0wTAl3y6D3Tr7CbJiDOLXwl7clj8,22
+pico_ioc/analysis.py,sha256=k49R-HcDyvpSNid8mxv7Fc6fPHnDu1C_b4HxrGLNF2g,2780
+pico_ioc/aop.py,sha256=r8JCPsTTF1hmrQMtnj-_Lj99fIy5J97RAJjiR2LjVPQ,12769
+pico_ioc/api.py,sha256=tR0pm6YEnDTA62EIT_Cpw1EaPfdnBFY9Dvpc38ypP-o,5061
+pico_ioc/component_scanner.py,sha256=S-9XNxrgyq_JFdc4Uqn2bEb-HxafSgIWylIurxyN_UA,7955
+pico_ioc/config_builder.py,sha256=ROBvbnm2Zv8apRdtZJHtebp-2cOMiuENFyiqaX1T2Ik,2918
+pico_ioc/config_registrar.py,sha256=8Xpl-CNRFny3EIRlcNx6oMJQldXkj_jdaPbC17qk2Ec,7803
+pico_ioc/config_runtime.py,sha256=Q8jVFQ1b6h1ZOkdacm70u0Q7TlEiUGENFkG-YWRkBxA,12133
+pico_ioc/constants.py,sha256=AhIt0ieDZ9Turxb_YbNzj11wUbBbzjKfWh1BDlSx2Nw,183
+pico_ioc/container.py,sha256=1gRjHH5kq_lOlnGUh5QYA4vUHF3ScQpwXoT9PWiyJ2g,18352
+pico_ioc/decorators.py,sha256=qrx4oMjRmmgwqT4cdp6FxBoqex3L1yNGlCUxO865z14,6347
+pico_ioc/dependency_validator.py,sha256=BIR6pKntACiabF6CjNZ3m00RMnet9BPK1_9y1iCJ5KQ,4144
+pico_ioc/event_bus.py,sha256=E8Qb8KZ6K1CuXSbMlG0MNPHkGoWlssLLPzHq1QYdADQ,8346
+pico_ioc/exceptions.py,sha256=FBuajj5g29hAGODt2tAWuy2sG5mQojdSddaqFzim-aY,2383
+pico_ioc/factory.py,sha256=oJXx_BYJuvV8oxYzs5I3gx9WM6uLYZ8GCc43gukNanc,1671
+pico_ioc/locator.py,sha256=UDyXl3oSK-sZ8ouOlhsDM91shMP0atMxyMoQlaSYvfE,4885
+pico_ioc/provider_selector.py,sha256=pU7NbI5vifvUlJEjlRJmvveQUZVD47T24QmiP0CHRw0,1213
+pico_ioc/registrar.py,sha256=cexXFDsuxBwM8FvW7mwmuyqcTcOkSP6ELecwklcs0F4,7625
+pico_ioc/scope.py,sha256=GDsDJWw7e5Vpiys-M4vQfKMJWSCiorRsT5cPo6z34Mk,5924
+pico_ioc-2.1.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_ioc-2.1.0.dist-info/METADATA,sha256=lYR54Lhdwmn5tDXol2M5ReJxBsXpdZ9bH0KrcYOlq2s,10672
+pico_ioc-2.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-2.1.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-2.1.0.dist-info/RECORD,,

pico_ioc-2.0.4.dist-info/RECORD

@@ -1,17 +0,0 @@
-pico_ioc/__init__.py,sha256=x7Sg0i4P0aXN3L5WH9IoTkyELPk-NQBdaRq8GuoZqO4,2294
-pico_ioc/_version.py,sha256=YuAuFLBrpl-SUl_UsvW1U1NTjqnldfuD1xUmSLmtaRw,22
-pico_ioc/aop.py,sha256=prFSlZC6vJYUfTbkMvlSc1T9UvvdEHr94Z0HAvjZ1fg,12985
-pico_ioc/api.py,sha256=vcmdU_7HHlsHR50N6230ICICIO-AhQ6M0xs2AzYMVVk,47476
-pico_ioc/config_runtime.py,sha256=z1cHDb5PbM8PMLYRFf5c2dmze8V22xwEzpWcBhtmMpA,11950
-pico_ioc/constants.py,sha256=AhIt0ieDZ9Turxb_YbNzj11wUbBbzjKfWh1BDlSx2Nw,183
-pico_ioc/container.py,sha256=-0o3T2uiKCnYVHTXP4MnUnA-atNeITjz0CtvUc_rY_E,17237
-pico_ioc/event_bus.py,sha256=E8Qb8KZ6K1CuXSbMlG0MNPHkGoWlssLLPzHq1QYdADQ,8346
-pico_ioc/exceptions.py,sha256=PnIY60r8O-eYXEVk7XPghz-hHNx_012ZLw9ikDwQhqQ,3019
-pico_ioc/factory.py,sha256=RMJJrD91HJdb7R3C6y48Fnia7YRQnQuMuYTC2cIAm34,1579
-pico_ioc/locator.py,sha256=PBxZYO_xCOxG7aJZ0adDtINrJass_ZDNYmPD2O_oNqM,2401
-pico_ioc/scope.py,sha256=GDsDJWw7e5Vpiys-M4vQfKMJWSCiorRsT5cPo6z34Mk,5924
-pico_ioc-2.0.4.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
-pico_ioc-2.0.4.dist-info/METADATA,sha256=tvJtJVxclklqQcQ9_k4cB4VPtsog2tWfngm_-z8TEa4,8741
-pico_ioc-2.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-2.0.4.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-2.0.4.dist-info/RECORD,,