Wireup
Performant, concise, and easy-to-use dependency injection container for Python 3.8+.
Ask AI about Wireup
Powered by Claude Β· Grounded in docs
I know everything about Wireup. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Wireup
Type-driven dependency injection for Python. Wireup is battle-tested in production, thread-safe, no-GIL (PEP 703) ready, and fail-fast by design: if the container starts, it works.
Quick Start Β· Docs Β· Benchmarks Β· Migrate to Wireup
Why Wireup?
π Define Once, Use AnywhereReuse the same application code in APIs, CLIs, workers, and scripts without rewriting your wiring. |
β Correct by DefaultIf the container starts, your dependency graph is valid. Wireup checks for missing or misconfigured dependencies to avoid surprises at runtime. |
π Framework-ReadyNative integrations for FastAPI, Django, Flask, Starlette, Celery, Click, Typer, and more. |
β‘ Zero-Overhead HandlersResolve singleton constructor dependencies once at startup in FastAPI and AIOHTTP class-based handlers, not per request. |
π§© Advanced WiringProvider-style wiring and explicit scope context sharing using plain Python. |
π§ͺ Easy to testOverride dependencies with context managers, keep tests isolated, and restore the original graph automatically. |
Benchmarks
Dense dependency graph resolved per request in FastAPI + Uvicorn
(Requests per second, higher is better. Manual Wiring represents the upper bound.)
Full methodology and reproducibility: benchmarks.
Installation
pip install wireup
Quick Start
import fastapi
import wireup
import wireup.integration.fastapi
from wireup import Injected, injectable
@injectable
class Database:
def query(self, sql: str) -> list[str]: ...
@injectable
class UserService:
def __init__(self, db: Database) -> None:
self.db = db
def get_users(self) -> list[str]:
return self.db.query("SELECT name FROM users")
app = fastapi.FastAPI()
@app.get("/users")
def get_users(service: Injected[UserService]) -> list[str]:
return service.get_users()
container = wireup.create_async_container(injectables=[Database, UserService])
wireup.integration.fastapi.setup(container, app)
For a full end-to-end walkthrough, start with the Getting Started guide.
Basic Usage
Wireup also supports config injection, decorator-free domain models, and package-level registration.
1. Inject Configuration
Inject configuration alongside dependencies. No need to write factories just to pass a config value.
@injectable
class Database:
def __init__(self, url: Annotated[str, Inject(config="db_url")]) -> None:
self.engine = sqlalchemy.create_engine(url)
container = wireup.create_sync_container(
injectables=[Database],
config={"db_url": os.environ["DB_URL"]}
)
2. Clean Architecture
Need strict boundaries? Use factories to wire pure domain objects and integrate external libraries like Pydantic.
# 1. No Wireup imports
class Database:
def __init__(self, url: str) -> None:
self.engine = create_engine(url)
# 2. Configuration (Pydantic)
class Settings(BaseModel):
db_url: str = "sqlite://"
# 3. Wireup factories
@injectable
def make_settings() -> Settings:
return Settings()
@injectable
def make_database(settings: Settings) -> Database:
return Database(url=settings.db_url)
container = wireup.create_sync_container(injectables=[make_settings, make_database])
3. Package-level registration
No need to list every injectable manually. Provide entire modules or packages to register all at once.
import app
import wireup
container = wireup.create_sync_container(
injectables=[
app.services,
app.repositories,
app.factories
]
)
More Features
π― Function Injection
Inject dependencies into CLI commands, background tasks, event handlers, or any standalone function that needs container access.
@inject_from_container(container)
def migrate_database(db: Injected[Database], settings: Injected[Settings]) -> None:
...
π Interfaces & Abstractions
Bind implementations to interfaces using Protocols or ABCs.
class Notifier(Protocol):
def notify(self) -> None: ...
@injectable(as_type=Notifier)
class SlackNotifier:
def notify(self) -> None: ...
# SlackNotifier is injected wherever Notifier is requested
@app.post("/notify")
def send_notification(notifier: Injected[Notifier]) -> None:
notifier.notify()
π Factories & Resources
Defer instantiation to specialized factories when complex initialization or cleanup is required. Full support for sync, async, and generator factories. Wireup handles cleanup at the right time based on lifetime.
class WeatherClient:
def __init__(self, client: requests.Session) -> None:
self.client = client
@injectable
def weather_client_factory() -> Iterator[WeatherClient]:
with requests.Session() as session:
yield WeatherClient(client=session)
Async example
class WeatherClient:
def __init__(self, client: aiohttp.ClientSession) -> None:
self.client = client
@injectable
async def weather_client_factory() -> AsyncIterator[WeatherClient]:
async with aiohttp.ClientSession() as session:
yield WeatherClient(client=session)
π Lifetimes & Scopes
Declare dependencies as singleton, scoped, or transient to control reuse explicitly.
# Singleton: one instance per application (default)
@injectable
class Settings:
pass
# Async singleton with cleanup β no lru_cache, no app.state
@injectable
async def database_factory(settings: Settings) -> AsyncIterator[AsyncConnection]:
async with create_async_engine(settings.db_url).connect() as connection:
yield connection
# Scoped: one instance per request, shared within that request
@injectable(lifetime="scoped")
class RequestContext:
def __init__(self) -> None:
self.request_id = uuid4()
# Transient: fresh instance every time
@injectable(lifetime="transient")
class OrderProcessor:
pass
π‘οΈ Startup Validation
Wireup validates the dependency graph when the container is created.
# Missing dependencies: caught at startup, not at runtime
@injectable
class Foo:
def __init__(self, unknown: NotManagedByWireup) -> None: ...
container = wireup.create_sync_container(injectables=[Foo])
# β Parameter 'unknown' of 'Foo' depends on an unknown injectable 'NotManagedByWireup'.
It also catches circular dependencies, duplicate registrations, misconfigured lifetimes, and missing config at startup.
π§ͺ Testing
Wireup decorators only collect metadata. Injectables are plain classes and functions, so you can test them directly with no special setup.
Swap dependencies during tests with container.override:
with container.override.injectable(target=Database, new=in_memory_database):
# Injectables that depend on Database will receive in_memory_database
# for the duration of this context manager
response = client.get("/users")
π Documentation
See the docs for integrations, lifetimes, factories, testing, and more advanced patterns.
https://maldoinc.github.io/wireup
If Wireup is useful to you, a star on GitHub helps others find it.
