pico-ioc 1.2.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

{pico_ioc-1.2.0.dist-info → pico_ioc-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-ioc
-Version: 1.2.0
+Version: 1.4.0
 Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -61,19 +61,55 @@ It helps you build loosely-coupled, testable apps without manual wiring. Inspire
 
 ---
 
-## ✨ Features
+## ⚖️ Principles
 
-- **Zero dependencies** — pure Python, framework-agnostic.
-- **Decorator API** — `@component`, `@factory_component`, `@provides`, `@plugin`.
-- **Fail-fast bootstrap** — eager by default; missing deps surface at startup.
-- **Opt-in lazy** — `lazy=True` wraps with `ComponentProxy`.
-- **Smart resolution order** — parameter name → type annotation → MRO → string.
-- **Qualifiers & collections** — `list[Annotated[T, Q]]` filters by qualifier.
-- **Plugins** — lifecycle hooks (`before_scan`, `after_ready`).
-- **Public API helper** — auto-export decorated symbols in `__init__.py`.
-- **Thread/async safe** — isolation via `ContextVar`.
-- **Overrides for testing** — inject mocks/fakes directly via `init(overrides={...})`.
-- **Scoped subgraph for tests** — `scope(modules=…, roots=…, overrides=…, strict=…, lazy=…, include_tags=…, exclude_tags=…)` to load only what you need.
+* **Focus & Simplicity**: A minimal core for one job: managing dependencies. It avoids accidental complexity by doing one thing well.
+* **Predictable & Explicit**: No magic. Behavior is deterministic, relying on explicit decorators and a clear resolution order.
+* **Unified Composition Root**: The application is assembled from a single entry point (`init`) which defines a clear, predictable boundary. This ensures a stable and understandable bootstrap process.
+* **Fail-Fast Bootstrap**: Catches dependency graph errors at startup, not in production. If the application runs, it's wired correctly.
+* **Testability First**: Features like `scope()` and `overrides` are first-class citizens, enabling fast and isolated testing.
+* **Extensible by Design**: Lifecycle hooks and AOP are available through a clean Plugin and Interceptor API without altering the core.
+* **Framework Agnostic**: Zero hard dependencies. It works with any Python application, from simple scripts to complex web servers.
+
+---
+
+## ✨ Why Pico-IoC?
+
+`pico-ioc` exists to solve a common problem that arises as Python applications grow: managing how objects are created and connected becomes complex and brittle. This manual wiring, where a change deep in the application can cause a cascade of updates, makes the code hard to test and maintain. `pico-ioc` introduces the principle of Inversion of Control (IoC) in a simple, Pythonic way. Instead of you creating and connecting every object, you declare your components with a simple `@component` decorator, and the container automatically wires them together based on their type hints. It brings the architectural robustness and testability of mature frameworks like Spring to the Python ecosystem, but without the heavy boilerplate, allowing you to build complex, loosely-coupled applications that remain simple to manage.
+
+
+| Feature             | Manual Wiring                                     | With Pico-IoC                   |
+| :------------------ | :------------------------------------------------ | :------------------------------ |
+| **Object Creation** | `service = Service(Repo(Config()))`               | `svc = container.get(Service)`  |
+| **Testing**         | Manual replacement or monkey-patching             | `overrides={Repo: FakeRepo()}`  |
+| **Coupling**        | High (code knows about constructors)              | Low (code just asks for a type) |
+| **Maintenance**     | Brittle (changing a constructor breaks consumers) | Robust (changes are isolated)   |
+| **Learning Curve**  | Ad-hoc, implicit patterns                         | Uniform, explicit, documented   |
+
+
+---
+
+## 🧩 Features
+
+### Core
+
+* **Zero dependencies** — pure Python, framework-agnostic.
+* **Single Entry Point (`init`)** — Robustly bootstrap your entire application from a single root package, enforcing a clean "Composition Root" pattern.
+* **Decorator API** — `@component`, `@factory_component`, `@provides`, `@plugin`.
+* **Fail-fast bootstrap** — eager by default; missing deps surface at startup.
+* **Opt-in lazy** — `lazy=True` wraps with `ComponentProxy`.
+* **Smart resolution order** — parameter name → type annotation → MRO → string.
+* **Overrides for testing** — inject mocks/fakes directly via `init(overrides={...})`.
+* **Public API helper** — auto-export decorated symbols in `__init__.py`.
+* **Thread/async safe** — isolation via `ContextVar`.
+
+### Advanced
+
+* **Qualifiers & collections** — `list[Annotated[T, Q]]` filters by qualifier.
+* **Flexible Scopes (`scope`)** — Create lightweight, temporary containers from multiple modules, ideal for testing, scripting, or modular tasks.
+* **Interceptors API** — observe/modify resolution, instantiation, invocation, errors.
+* **Conditional providers** — activate components by env vars or predicates.
+* **Plugins** — lifecycle hooks (`before_scan`, `after_ready`).
 
 ---
 
@@ -163,10 +199,17 @@ This way you don’t need to bootstrap your entire app (`controllers`, `http`,
 ---
 ## 📖 Documentation
 
-* [Overview](.llm/OVERVIEW.md) — mission & concepts
-* [Guide](.llm/GUIDE.md) — practical usage & recipes
-* [Architecture](.llm/ARCHITECTURE.md) — internals & design rationale
+  * **🚀 New to pico-ioc? Start with the User Guide.**
+      * [**GUIDE.md**](.llm/GUIDE.md) — Learn with practical examples: testing, configuration, collection injection, and web framework integration.
+
+  * **🏗️ Want to understand the internals? See the Architecture.**
+      * [**ARCHITECTURE.md**](.llm/ARCHITECTURE.md) — A deep dive into the algorithms, lifecycle, and internal diagrams. Perfect for contributors.
 
+  * **🤔 Want to know *why* it's designed this way? Read the Decisions.**
+      * [**DECISIONS.md**](.llm/DECISIONS.md) — The history and rationale behind key technical decisions.
+
+  * **💡 Just need a quick summary?**
+      * [**OVERVIEW.md**](.llm/OVERVIEW.md) — What pico-ioc is and why you should use it.
 ---
 
 ## 🧪 Development
@@ -178,6 +221,12 @@ tox
 
 ---
 
+## 📜 Overview
+
+See [OVERVIEW.md](.llm/OVERVIEW.md) Just need a quick summary?
+
+---
+
 ## 📜 Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history.

pico_ioc-1.4.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+pico_ioc/__init__.py,sha256=s_9v-pMM5X7r5vhbzaOmQQEHBLOmZCV7o6QNtRcfMAU,1282
+pico_ioc/_state.py,sha256=C98XQZIfKy98j8fzR730eUCoqSnCkRkxUS4bH7mp73c,2154
+pico_ioc/_version.py,sha256=EyMGX1ADFzN6XVXHWbJUtKPONYKeFkvWoKIFPDDB2I8,22
+pico_ioc/api.py,sha256=cc9c3db6_dIfeobP_VvFRpNV9qNIsIPbUct5X9mmW9w,8348
+pico_ioc/builder.py,sha256=ZvIpOaAzBpByw-u5V52GM5cJAMH_E_5FMDLlgyqd-g4,11379
+pico_ioc/config.py,sha256=J3k7_2vRB2HCpikzeMzT4Ut9COFM4kcydkwZorncqSk,12317
+pico_ioc/container.py,sha256=V9X0qvNPZYU80C65X3Dqifek6RWt9kgEwG0CkX1Hpow,6461
+pico_ioc/decorators.py,sha256=Jyq7PhSM3uFVfBEaCq6x_mFV9V3B5fTEK4o3I6ZvG5A,4492
+pico_ioc/interceptors.py,sha256=rBdpI7ca5L30N-zR7LKroCIc5FgfNb9M5P7OEGw-TtY,1955
+pico_ioc/plugins.py,sha256=GP7WEMshggQ-FEjiShkcuLrSMxfueUnhbY9I8PcIyPU,1039
+pico_ioc/policy.py,sha256=p7maTHNfU-zoaz3j7CY4P3ry-bYfaGxAOklcTAuF6dY,8648
+pico_ioc/proxy.py,sha256=VJA-QaO8yvejcHmX5mlXMHfyuyXFxD7cazONSzBGrf0,6308
+pico_ioc/public_api.py,sha256=E3sArCoI1xxkIw7xQBvLYAWcIoVJjcq1s0kH-0qIVDE,2383
+pico_ioc/resolver.py,sha256=clIS9wwhOKzIwzBQFXxCrmPX2gM2X2eVyS8P_VEeyDw,4798
+pico_ioc/scanner.py,sha256=TmDLkklO-e2LBoVducQD4-uuZKFDg_dMwgwO9vM8-pU,7129
+pico_ioc/scope.py,sha256=5oRCir1Dqu8Jlgl_R-q900my1u6_7zq5VUbq8ahV280,1754
+pico_ioc/utils.py,sha256=OyhOKnyepwGQ_uQKlQLt-fymEV1bQ6hCq4Me7h3dfco,1002
+pico_ioc-1.4.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_ioc-1.4.0.dist-info/METADATA,sha256=DdvaybzEQOnC-HD563NJZqMDL7zwY3SnEpLGwjPxVzU,10346
+pico_ioc-1.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_ioc-1.4.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
+pico_ioc-1.4.0.dist-info/RECORD,,

pico_ioc/typing_utils.py

@@ -1,29 +0,0 @@
-# pico_ioc/typing_utils.py
-
-import sys
-import typing
-
-
-def evaluated_hints(func, owner_cls=None) -> dict:
-    """Return type hints; swallow any error and return {}."""
-    try:
-        module = sys.modules.get(func.__module__)
-        globalns = getattr(module, "__dict__", {})
-        localns = vars(owner_cls) if owner_cls is not None else None
-        return typing.get_type_hints(func, globalns=globalns, localns=localns, include_extras=True)
-    except Exception:
-        return {}
-
-
-def resolve_annotation_to_type(ann, func, owner_cls=None):
-    """Best-effort evaluation of a string annotation; return original on failure."""
-    if not isinstance(ann, str):
-        return ann
-    try:
-        module = sys.modules.get(func.__module__)
-        globalns = getattr(module, "__dict__", {})
-        localns = vars(owner_cls) if owner_cls is not None else None
-        return eval(ann, globalns, localns)
-    except Exception:
-        return ann
-

pico_ioc-1.2.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-pico_ioc/__init__.py,sha256=JTLiySlYUTAnWODEdilS2rUz4swaqMxrQw_p6IRu-S0,653
-pico_ioc/_state.py,sha256=KHNtdPrv1s-uynfot2IsNkWotBPyORPCcM2xe9qMMPo,286
-pico_ioc/_version.py,sha256=U3f_Jgr3zpgiYG2kLcvcT05TQsVzN9Kktg_f3Q9OZFA,22
-pico_ioc/api.py,sha256=GD16DejaBW6pAH0djU8xCirvkgAla5Ags3sGuhkd7oo,9250
-pico_ioc/container.py,sha256=akjtF9Qo09lsR65a5_8UDnEB6Vvsyuq2BloceJjWpnI,5281
-pico_ioc/decorators.py,sha256=orVMdmGgMYCtNq6fjqEYGZxSuv5qdVqf8J6xoUiUQgs,2173
-pico_ioc/plugins.py,sha256=JbI-28VLGJaik7ysXi3L-YGTGxhqwJH4W5QYuWSruDE,589
-pico_ioc/proxy.py,sha256=-e3Z9z7Bc_2wxswwUJI_s8AfvCTps8f8RWUJ9RuEp7E,4606
-pico_ioc/public_api.py,sha256=E3sArCoI1xxkIw7xQBvLYAWcIoVJjcq1s0kH-0qIVDE,2383
-pico_ioc/resolver.py,sha256=RVVpqnp2UqcKwkKMYBzrTetnZW-ZTY7XwDOslBAWPxI,4911
-pico_ioc/scanner.py,sha256=cSa33lE7dKwUpj2RNpH1SC4wjiaJ9MifS5ecORtW1xM,7645
-pico_ioc/typing_utils.py,sha256=JQ4bkR60pKxFs3f8JlEz41ruKDsWj-SmkKv3DLJriec,950
-pico_ioc-1.2.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
-pico_ioc-1.2.0.dist-info/METADATA,sha256=XmSjbjeocTk7V1TIHb2irV5tzJd37zepVKEfWIsDvFM,6719
-pico_ioc-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pico_ioc-1.2.0.dist-info/top_level.txt,sha256=_7_RLu616z_dtRw16impXn4Mw8IXe2J4BeX5912m5dQ,9
-pico_ioc-1.2.0.dist-info/RECORD,,