PyIV Documentation
A Guice-style dependency injection library for Python. Register bindings, inject by type, and swap production implementations for test doubles without mocking the world.
Key Features
Type-based injection
Constructor injection from type annotations. Register an interface once; the injector builds the graph.
Scopes
Per-injector and process-wide singletons, plus an extensible Scope API for custom lifecycles.
Keys and Binder
Named/qualified bindings for multiple implementations of one type, and a fluent Binder API.
Reflection
Discover interface implementations in a package instead of listing every class by hand.
Test doubles
Clock, Filesystem, Console, and DateTimeService ship with in-memory implementations for tests.
Zero dependencies
Runtime is the Python standard library only. No extra packages to pin or audit.
Installation
pip install pyiv
Requires Python 3.8 or newer. Unreleased main:
pip install git+https://github.com/rl337/pyiv.git
Quick Start
from pyiv import Config, get_injector
class Database:
pass
class PostgreSQL(Database):
pass
class Logger:
pass
class FileLogger(Logger):
pass
class MyConfig(Config):
def configure(self):
self.register(Database, PostgreSQL)
self.register(Logger, FileLogger, singleton=True)
injector = get_injector(MyConfig)
db = injector.inject(Database) # PostgreSQL
logger = injector.inject(Logger) # shared per injector
User Guide
Binder vs register, scopes, qualified keys, and swapping Clock /
Filesystem / Console / DateTimeService in tests:
User guide
API Reference
The left navigation lists every public module. Pages are generated from
docstrings in the pyiv package; doctests in those docstrings are run in CI.
Discovery
Test doubles
Integrations
Reference