ADR 12: Tier-0 Packaging, PEP 562 Lazy Front Door, and Zero-Overhead Observability
Summary
Lightweight base install, named extras, lazy frontdoor loading, and no-op tracing.
Context
A core framework should not force users to install heavy database drivers (psycopg, asyncpg, aiosqlite), message broker clients (kafka-python, pika, redis), or tracing collectors (opentelemetry) if they only need in-memory or domain modeling.
Decision
- Tier-0 core packaging: base
eventsourceinstall requires only pure dependencies (pydantic,sqlalchemy). - All infrastructure drivers live behind explicit optional extras (
postgres,sqlite,kafka,rabbitmq,redis,telemetry). - PEP 562 lazy dynamic loading in
eventsource/__init__.py: bareimport eventsourceis lightning fast and does not trigger backend imports. - Top-level
__all__is byte-identical across lazy execution and static type checking. - Distributed tracing via OpenTelemetry is completely no-op by default with zero performance overhead when disabled.
Consequences
- Minimal package footprint and ultra-fast application startup.
- Clean dependency tree without silent transitive bloat.
- Enterprise-grade OpenTelemetry observability without forced dependencies.