servicewright

One Host, many Entrypoints — a batteries-optional microservice runtime for async Python.

Describe a service once as an AppSpec (DI container, lifecycle, observability, warmup, health) and run it through any number of pluggable entrypoints — HTTP, gRPC, scheduler, background daemon, one-shot batch — under one unified lifecycle. The "API vs worker" distinction does not exist at the core: a cron job and an HTTP request are the same thing — one unit of work in a fresh DI scope.

This is the model behind .NET Generic Host, Spring SmartLifecycle and go-kratos transport.Server, adapted to async Python.

Why

• One lifecycle for every archetype: Bootstrap → Warmup → Ready → Serve → Drain → Cleanup. Kubernetes-correct shutdown out of the box: readiness flips to false before draining, every entrypoint finishes in-flight work within a grace window, the DI scope closes last, and a service that dies mid-serve exits non-zero instead of looking like a graceful stop.
• DI-agnostic two-tier scopes: the core depends on no DI library. AppScope holds process-lifetime singletons; a fresh UnitScope wraps every request / RPC / job / message. A dishka adapter ships in the box; any container fits by implementing two methods.
• Pluggable observability add-ons: metrics / tracing / logging / error-tracking are protocols in the kernel with selectable, extra-gated backends (prometheus, OpenTelemetry, Sentry, structlog). Adding a backend = one module + one register_sink call, zero core changes.
• One error taxonomy, every transport: a ServiceError raised in business code renders as an RFC 9457 problem document over HTTP and as the mapped grpc.StatusCode over gRPC, with one masking rule for non-public details and a pluggable renderer when you own the wire format.
• Zero hard dependencies: pip install servicewright brings pure Python. Every framework binding lives behind an extra; the kernel never imports an SDK, a vendor, or a transport.

Installation

pip install servicewright                    # pure kernel, zero dependencies
pip install "servicewright[fastapi]"         # + FastAPI/uvicorn entrypoint
pip install "servicewright[grpc]"            # + gRPC entrypoint
pip install "servicewright[apscheduler4]"    # + cron/scheduler entrypoint
pip install "servicewright[metrics,observability,sentry]"  # + prometheus, otel+structlog, sentry
pip install "servicewright[uvloop]"          # + uvloop, picked up by run_sync(loop="auto")
pip install "servicewright[all]"             # everything except the conflicting [apscheduler3]

Requirements: Python 3.12+

Quick start — HTTP API + cron in ONE process

from servicewright import AppSpec, ObsConfig, ObservabilityManager, Service, run_sync
from servicewright.adapters.apscheduler4 import ScheduledJob, SchedulerEntrypoint
from servicewright.adapters.fastapi import FastApiEntrypoint


def build_service() -> Service:
    spec = AppSpec(
        service_name="orders-service",
        create_container=build_container,   # your DI container factory
        observability=ObservabilityManager(
            ObsConfig(metrics="prometheus", tracing="otel", logging="structlog"),
        ),
    )

    http = FastApiEntrypoint(routers=(router,))          # kind="http"
    cron = SchedulerEntrypoint(jobs=[                    # kind="scheduler"
        ScheduledJob(id="sweep", func=sweep_expired_orders, trigger=interval_trigger),
    ])
    return Service(spec, entrypoints=[http, cron])


if __name__ == "__main__":
    run_sync(build_service(), Settings())   # loop="auto": uvloop when installed, asyncio otherwise

Both entrypoints share one DI container, one observability setup and one graceful shutdown. Scaling the worker separately later = the same AppSpec in a second process with a different entrypoint list.

Entrypoints

Writing your own entrypoint = implementing four methods (bind, serve, drain, stop) with nothing installed.

What's inside

The kernel is core/; everything that touches a third-party SDK is an extra-gated adapter. An import-linter contract enforces the direction in CI: deleting adapters/ leaves core/ importable.

Optional dependencies

Examples

Runnable, self-contained scripts (each exits 0):

• examples/minimal_service.py — the smallest real service, narrating every lifecycle phase in order.
• examples/http_service.py — a real uvicorn server with dishka DI, per-request scopes, health probes, an RFC 9457 error on the wire and a graceful drain.
• examples/errors_and_context.py — the error taxonomy, a custom renderer, masking, and the correlation store with outbound propagation.
• examples/warmup_and_health.py — warmup priority groups, fail-fast, and health checks driving readiness.

Documentation

Full documentation: bedrock-python.github.io/servicewright

The design source-of-truth lives in ARCHITECTURE.md.

License

Apache 2.0 — see LICENSE.