| Name | pico-ioc JSON |
| Version |
1.3.0
JSON |
| download |
| home_page | None |
| Summary | A minimalist, zero-dependency Inversion of Control (IoC) container for Python. |
| upload_time | 2025-09-15 18:29:10 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 David Pérez Cabrera
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
ioc
di
dependency injection
inversion of control
decorator
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
# 📦 Pico-IoC: A Minimalist IoC Container for Python
[](https://pypi.org/project/pico-ioc/)
[](https://deepwiki.com/dperezcabrera/pico-ioc)
[](https://opensource.org/licenses/MIT)
[](https://codecov.io/gh/dperezcabrera/pico-ioc)
[](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
[](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
[](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
**pico-ioc** is a **tiny, zero-dependency, decorator-based IoC container for Python**.
It helps you build loosely-coupled, testable apps without manual wiring. Inspired by the Spring ecosystem, but minimal.
> ⚠️ **Requires Python 3.10+** (uses `typing.Annotated` and `include_extras=True`).
---
## ⚖️ Principles
* **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`).
---
## 📦 Installation
```bash
# Requires Python 3.10+
pip install pico-ioc
````
---
## 🚀 Quick start
```python
from pico_ioc import component, init
@component
class Config:
url = "sqlite:///demo.db"
@component
class Repo:
def __init__(self, cfg: Config):
self.url = cfg.url
def fetch(self): return f"fetching from {self.url}"
@component
class Service:
def __init__(self, repo: Repo):
self.repo = repo
def run(self): return self.repo.fetch()
# bootstrap
import myapp
c = init(myapp)
svc = c.get(Service)
print(svc.run())
```
**Output:**
```
fetching from sqlite:///demo.db
```
---
### Quick overrides for testing
```python
from pico_ioc import init
import myapp
fake = {"repo": "fake-data"}
c = init(myapp, overrides={
"fast_model": fake, # constant instance
"user_service": lambda: {"id": 1}, # provider
})
assert c.get("fast_model") == {"repo": "fake-data"}
```
---
### Scoped subgraphs
For unit tests or lightweight integration, you can bootstrap **only a subset of the graph**.
```python
from pico_ioc
from src.runner_service import RunnerService
from tests.fakes import FakeDocker
import src
c = pico_ioc.scope(
modules=[src],
roots=[RunnerService], # only RunnerService and its deps
overrides={
"docker.DockerClient": FakeDocker(),
},
strict=True, # fail if something is missing
lazy=True, # instantiate on demand
)
svc = c.get(RunnerService)
```
This way you don’t need to bootstrap your entire app (`controllers`, `http`, …) just to test one service.
---
## 📖 Documentation
* **🚀 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
```bash
pip install tox
tox
```
---
## 📜 Changelog
See [CHANGELOG.md](./CHANGELOG.md) for version history.
---
## 📜 License
MIT — see [LICENSE](https://opensource.org/licenses/MIT)
Raw data
{
"_id": null,
"home_page": null,
"name": "pico-ioc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ioc, di, dependency injection, inversion of control, decorator",
"author": null,
"author_email": "David Perez Cabrera <dperezcabrera@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6f/0e/94f079deb243fe8be6966494bc1cf8cbd84a78fe53f960fc754cbe6e2c3f/pico_ioc-1.3.0.tar.gz",
"platform": null,
"description": "# \ud83d\udce6 Pico-IoC: A Minimalist IoC Container for Python\n\n[](https://pypi.org/project/pico-ioc/)\n[](https://deepwiki.com/dperezcabrera/pico-ioc)\n[](https://opensource.org/licenses/MIT)\n\n[](https://codecov.io/gh/dperezcabrera/pico-ioc)\n[](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)\n[](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)\n[](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)\n\n**pico-ioc** is a **tiny, zero-dependency, decorator-based IoC container for Python**. \nIt helps you build loosely-coupled, testable apps without manual wiring. Inspired by the Spring ecosystem, but minimal.\n\n> \u26a0\ufe0f **Requires Python 3.10+** (uses `typing.Annotated` and `include_extras=True`).\n\n---\n\n## \u2696\ufe0f Principles\n\n* **Focus & Simplicity**: A minimal core for one job: managing dependencies. It avoids accidental complexity by doing one thing well.\n* **Predictable & Explicit**: No magic. Behavior is deterministic, relying on explicit decorators and a clear resolution order.\n* **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.\n* **Fail-Fast Bootstrap**: Catches dependency graph errors at startup, not in production. If the application runs, it's wired correctly.\n* **Testability First**: Features like `scope()` and `overrides` are first-class citizens, enabling fast and isolated testing.\n* **Extensible by Design**: Lifecycle hooks and AOP are available through a clean Plugin and Interceptor API without altering the core.\n* **Framework Agnostic**: Zero hard dependencies. It works with any Python application, from simple scripts to complex web servers.\n\n---\n\n## \u2728 Why Pico-IoC?\n\n`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.\n\n\n| Feature | Manual Wiring | With Pico-IoC |\n| :------------------ | :------------------------------------------------ | :------------------------------ |\n| **Object Creation** | `service = Service(Repo(Config()))` | `svc = container.get(Service)` |\n| **Testing** | Manual replacement or monkey-patching | `overrides={Repo: FakeRepo()}` |\n| **Coupling** | High (code knows about constructors) | Low (code just asks for a type) |\n| **Maintenance** | Brittle (changing a constructor breaks consumers) | Robust (changes are isolated) |\n| **Learning Curve** | Ad-hoc, implicit patterns | Uniform, explicit, documented |\n\n\n---\n\n## \ud83e\udde9 Features\n\n### Core\n\n* **Zero dependencies** \u2014 pure Python, framework-agnostic.\n* **Single Entry Point (`init`)** \u2014 Robustly bootstrap your entire application from a single root package, enforcing a clean \"Composition Root\" pattern.\n* **Decorator API** \u2014 `@component`, `@factory_component`, `@provides`, `@plugin`.\n* **Fail-fast bootstrap** \u2014 eager by default; missing deps surface at startup.\n* **Opt-in lazy** \u2014 `lazy=True` wraps with `ComponentProxy`.\n* **Smart resolution order** \u2014 parameter name \u2192 type annotation \u2192 MRO \u2192 string.\n* **Overrides for testing** \u2014 inject mocks/fakes directly via `init(overrides={...})`.\n* **Public API helper** \u2014 auto-export decorated symbols in `__init__.py`.\n* **Thread/async safe** \u2014 isolation via `ContextVar`.\n\n### Advanced\n\n* **Qualifiers & collections** \u2014 `list[Annotated[T, Q]]` filters by qualifier.\n* **Flexible Scopes (`scope`)** \u2014 Create lightweight, temporary containers from multiple modules, ideal for testing, scripting, or modular tasks.\n* **Interceptors API** \u2014 observe/modify resolution, instantiation, invocation, errors.\n* **Conditional providers** \u2014 activate components by env vars or predicates.\n* **Plugins** \u2014 lifecycle hooks (`before_scan`, `after_ready`).\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\n# Requires Python 3.10+\npip install pico-ioc\n````\n\n---\n\n## \ud83d\ude80 Quick start\n\n```python\nfrom pico_ioc import component, init\n\n@component\nclass Config:\n url = \"sqlite:///demo.db\"\n\n@component\nclass Repo:\n def __init__(self, cfg: Config):\n self.url = cfg.url\n def fetch(self): return f\"fetching from {self.url}\"\n\n@component\nclass Service:\n def __init__(self, repo: Repo):\n self.repo = repo\n def run(self): return self.repo.fetch()\n\n# bootstrap\nimport myapp\nc = init(myapp)\nsvc = c.get(Service)\nprint(svc.run())\n```\n\n**Output:**\n\n```\nfetching from sqlite:///demo.db\n```\n---\n\n### Quick overrides for testing\n\n```python\nfrom pico_ioc import init\nimport myapp\n\nfake = {\"repo\": \"fake-data\"}\nc = init(myapp, overrides={\n \"fast_model\": fake, # constant instance\n \"user_service\": lambda: {\"id\": 1}, # provider\n})\nassert c.get(\"fast_model\") == {\"repo\": \"fake-data\"}\n```\n---\n\n### Scoped subgraphs\n\nFor unit tests or lightweight integration, you can bootstrap **only a subset of the graph**.\n\n```python\nfrom pico_ioc\nfrom src.runner_service import RunnerService\nfrom tests.fakes import FakeDocker\nimport src\n\nc = pico_ioc.scope(\n modules=[src],\n roots=[RunnerService], # only RunnerService and its deps\n overrides={\n \"docker.DockerClient\": FakeDocker(),\n },\n strict=True, # fail if something is missing\n lazy=True, # instantiate on demand\n)\nsvc = c.get(RunnerService)\n```\n\nThis way you don\u2019t need to bootstrap your entire app (`controllers`, `http`, \u2026) just to test one service.\n\n---\n## \ud83d\udcd6 Documentation\n\n * **\ud83d\ude80 New to pico-ioc? Start with the User Guide.**\n * [**GUIDE.md**](.llm/GUIDE.md) \u2014 Learn with practical examples: testing, configuration, collection injection, and web framework integration.\n\n * **\ud83c\udfd7\ufe0f Want to understand the internals? See the Architecture.**\n * [**ARCHITECTURE.md**](.llm/ARCHITECTURE.md) \u2014 A deep dive into the algorithms, lifecycle, and internal diagrams. Perfect for contributors.\n\n * **\ud83e\udd14 Want to know *why* it's designed this way? Read the Decisions.**\n * [**DECISIONS.md**](.llm/DECISIONS.md) \u2014 The history and rationale behind key technical decisions.\n\n * **\ud83d\udca1 Just need a quick summary?**\n * [**OVERVIEW.md**](.llm/OVERVIEW.md) \u2014 What pico-ioc is and why you should use it.\n---\n\n## \ud83e\uddea Development\n\n```bash\npip install tox\ntox\n```\n\n---\n\n## \ud83d\udcdc Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for version history.\n\n---\n\n## \ud83d\udcdc License\n\nMIT \u2014 see [LICENSE](https://opensource.org/licenses/MIT)\n\n\n\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 David P\u00e9rez Cabrera\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A minimalist, zero-dependency Inversion of Control (IoC) container for Python.",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/dperezcabrera/pico-ioc",
"Issue Tracker": "https://github.com/dperezcabrera/pico-ioc/issues",
"Repository": "https://github.com/dperezcabrera/pico-ioc"
},
"split_keywords": [
"ioc",
" di",
" dependency injection",
" inversion of control",
" decorator"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3e3381490071031126bc2b21f40b3798cb82814a5dbbad265ee5d426ad6a1705",
"md5": "b1facb60f520ede77e6e5f1b5e159cbd",
"sha256": "3797d63984f0897528c0e2199a4c85cd4fbbd16842935e654a4611cf361bf03f"
},
"downloads": -1,
"filename": "pico_ioc-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b1facb60f520ede77e6e5f1b5e159cbd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 28547,
"upload_time": "2025-09-15T18:29:09",
"upload_time_iso_8601": "2025-09-15T18:29:09.029096Z",
"url": "https://files.pythonhosted.org/packages/3e/33/81490071031126bc2b21f40b3798cb82814a5dbbad265ee5d426ad6a1705/pico_ioc-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6f0e94f079deb243fe8be6966494bc1cf8cbd84a78fe53f960fc754cbe6e2c3f",
"md5": "10af254a005598f550122775b551263a",
"sha256": "c6c4822b3ebc5f0e1c1f3006ddb29196639cee4c073517de7b12e92a9e7caec5"
},
"downloads": -1,
"filename": "pico_ioc-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "10af254a005598f550122775b551263a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 50341,
"upload_time": "2025-09-15T18:29:10",
"upload_time_iso_8601": "2025-09-15T18:29:10.045401Z",
"url": "https://files.pythonhosted.org/packages/6f/0e/94f079deb243fe8be6966494bc1cf8cbd84a78fe53f960fc754cbe6e2c3f/pico_ioc-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-15 18:29:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dperezcabrera",
"github_project": "pico-ioc",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "pico-ioc"
}
