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
| Reuse the same application code in APIs, CLIs, workers, and scripts without rewriting your wiring. | If the container starts, your dependency graph is valid. Wireup checks for missing or misconfigured dependencies to avoid surprises at runtime. See What Wireup Validates | Native integrations for FastAPI, Django, Flask, Starlette, Celery, Click, Typer, and more. |
| Resolve singleton constructor dependencies once at startup in FastAPI and AIOHTTP class-based handlers, not per request. | Go beyond simple constructor injection with reusable bundles, explicit scope context sharing, collection injection, and more using plain Python. | Override dependencies with context managers, keep tests isolated, and restore the original graph automatically. |
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.
pip install wireupWireup works anywhere, in APIs, CLIs, workers, scripts. Here's what it looks like in FastAPI:
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.
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
Provide entire modules or packages to register all at once, or export explicit injectable lists from each package when you want a more visible composition root in larger applications.
import app
import wireup
container = wireup.create_sync_container(
injectables=[
app.services,
app.repositories,
app.factories
]
)Instead of separate registration APIs for services, factories, resources, and async resources, Wireup's @injectable API uses standard Python constructs to determine how a dependency behaves.
# Class → dependency
@injectable
class UserService: ...
# Dataclass → dependency (auto-generated __init__)
@injectable
@dataclass
class OrderProcessor:
payment_gateway: PaymentGateway
inventory_service: InventoryService
# Function → factory
@injectable
def make_client() -> Client:
return Client()
# Generator → resource with cleanup
@injectable
def database() -> Iterator[Database]:
db = Database()
try:
yield db
finally:
db.close()
# Async generator → async resource with cleanup
@injectable
async def database() -> AsyncIterator[Database]:
async with Database() as db:
yield dbThese modifiers compose. A request-scoped async resource with cleanup is just:
@injectable(lifetime="scoped") # Scoped lifetime.
# async def → async dependency
async def make_foo() -> AsyncIterator[Foo]:
async with Foo() as foo:
yield foo # yield → cleanupNo separate provider type needed. Change the function signature and the registration evolves with it. Learn one API and use it everywhere.
Wireup keeps the API small, but it is built for larger application graphs.
| Need | Wireup |
|---|---|
| One shared instance | @injectable / lifetime="singleton" |
| Per request, job, command, handler, or WebSocket | @injectable(lifetime="scoped") |
| Fresh instance each resolution | @injectable(lifetime="transient") |
| Setup and cleanup | yield from a sync or async factory |
| Configuration | Both Inject(config=...) values and injectable settings objects |
| Register an already-created object | wireup.instance(...) |
| Dynamic function injection and injectable lookup | Inject the root or active scoped container |
| Interfaces and protocols | as_type=... or factory return annotations |
| Multiple implementations | Qualifiers |
| All implementations | Sequence[T] or Mapping[Hashable, T] |
| Isolated scopes with explicit context sharing (batch jobs, fan-out tasks, multi-tenant processing) | container.enter_scope({...}) |
| Environment-specific graph | Conditional registration with normal Python |
| Generic repositories/services | Generic dependencies |
| Modular or parametrized registration | Reusable bundles |
| Optional or conditional dependencies | Params with defaults are skipped when unregistered; factories can return T | None |
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:
...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)Wireup has three lifetimes: singleton, scoped, and transient, plus explicit scope forking from root for unit-of-work patterns like batch jobs or fan-out tasks.
# Singleton: one instance per application (default)
@injectable
class Settings:
pass
# Async singleton with cleanup
@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 for the duration of the current scope.
# In a web request, that's the request. In a WebSocket, the connection.
# In a CLI command, the command lifetime. In a worker job, the job.
@injectable(lifetime="scoped")
class RequestContext:
def __init__(self) -> None:
self.request_id = uuid4()
# Transient: fresh instance every time
@injectable(lifetime="transient")
class OrderProcessor:
passWireup enforces lifetime rules at startup to prevent scope leakage, such as an application-wide singleton accidentally holding request-scoped state.
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()When multiple implementations exist, distinguish them with qualifiers:
@injectable
def primary_database(settings: Settings) -> Database:
return Database(url=settings.db.primary_dsn)
@injectable(qualifier="readonly")
def readonly_database(settings: Settings) -> Database:
return Database(url=settings.db.replica_dsn)
# Primary (no qualifier) and replica (qualifier) in one service
@injectable
class ReportService:
def __init__(
self,
db: Database,
replica: Annotated[Database, Inject(qualifier="readonly")],
) -> None:
self.db = db
self.replica = replicaSee Interfaces & Qualifiers for collection injection (Sequence[T], Mapping[K, T]) and more.
Wireup uses isolated scopes with explicit context sharing rather than nested scope inheritance. Each worker scope gets exactly the context it needs without implicit leakage of the parent's full graph.
The container is injectable too, so you never need a global reference or app.state to create child scopes.
@app.post("/batch")
async def process_batch(
doc_ids: list[str],
container: Injected[wireup.AsyncContainer],
ctx: Injected[TenantContext],
) -> list[Result]:
# TenantContext is shared while everything else is isolated per worker.
async def process_one(doc_id: str) -> Result:
async with container.enter_scope({TenantContext: ctx}) as scope:
# DocumentService and all its dependencies (db connections, transactions, etc.)
# are isolated per worker
document_service = await scope.get(DocumentService)
return await process_document(document_service, doc_id)
return await asyncio.gather(*[process_one(doc_id) for doc_id in doc_ids])Because child scopes don't silently inherit the parent graph, parallel workers can't accidentally share state through the container.
See Lifetimes & Scopes for the full model.
Wireup validates the dependency graph when the container is created. See What Wireup Validates for the full rules and limits.
# 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.
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")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.