How to wire dependencies with Inject[T]
Connect services, repositories, and external clients automatically using IoC and Annotated injection.
ZCore eliminates verbose Depends(...) chains. It provides automatic constructor auto-wiring for classes, and the dynamic Inject[T] marker for FastAPI route handlers.
Register External Clients (Singleton or Transient)
If you have external clients (e.g., an EmailClient or third-party SDK), register them in ZCore's IoC container during startup:
# main.py or plugins
from zcore.kernel.di import container
class EmailClient:
def send_email(self, to: str, message: str) -> None:
print(f"Sending email to {to}: {message}")
# Register as a shared singleton
container.register_singleton(EmailClient, EmailClient())Constructor Auto-Wiring (Service-to-Service)
Inside your classes and services, you do not need any decorators or helpers. Simply declare your dependencies in the __init__ method using standard Python type hints:
# services.py
from .clients import EmailClient
class NotificationService:
# ZCore automatically inspects type hints and injects EmailClient
def __init__(self, email_client: EmailClient):
self.email_client = email_client
async def notify(self, user_email: str) -> None:
self.email_client.send_email(user_email, "Welcome to ZCore!")Use Inject[T] in FastAPI Routes
To inject any container-managed dependency into a FastAPI route, annotate the parameter with Inject[T]:
# routers.py
from fastapi import APIRouter
from zcore import Inject
from .services import NotificationService
router = APIRouter()
@router.post("/notify")
async def send_notification(service: Inject[NotificationService]):
await service.notify("[email protected]")
return {"status": "sent"}How Inject[T] Works: Under the hood, Inject[NotificationService] resolves to Annotated[NotificationService, Depends(Injector(NotificationService))]. It seamlessly bridges FastAPI's dependency injection with ZCore's IoC container lifecycle.
How to use CLI commands
Master the ZCore interactive CLI for project scaffolding, domain app generation, environment management, and advanced server orchestration.
How to register Singleton vs Scoped services
Understand when to use global singletons, request-scoped instances, and transient dependencies.