pepelats 0.1.0a3

Opinionated framework for async web services

Small Opinionated framework for async web services in Python — compose on a fluent builder with DI, configuration, observability, and lifecycle built in.

---

Apps compose on WebHostBuilder or FastAPIHostBuilder: register services, mount routes or APIs, run background workers. Starlette is the HTTP layer; FastAPI is optional.

Features

• Compose and run an async web service from a single builder
• Inject services and configuration into handlers and constructors
• Load typed settings from TOML or JSON with environment overlays
• Structured logging, tracing, and metrics
• Run background work alongside the HTTP server
• Optional FastAPI for REST APIs and OpenAPI (pepelats[fastapi])

Installation

uv add pepelats
uv add "pepelats[fastapi]"

Configuration

Pass a config_dir to the builder. Pepelats loads, in order:

1. appsettings.toml or appsettings.json (required)
2. appsettings.{Environment}.* when present
3. .env, then process environment variables (highest priority)

The environment name comes from ENVIRONMENT, the environment key in the base file, or defaults to Local. That name selects the overlay file (e.g. appsettings.Staging.toml).

config/appsettings.toml:

environment = "Local"

[service]
service_name = "my-service"
service_version = "1.0.0"

[logging]
log_level = "INFO"
sinks = ["console"]

[logging.console]
json_logs = false

[host]
bind = "127.0.0.1"
port = 8000

[observability]
enabled = false
otlp_endpoint = ""

[greeting]
punctuation = "!"
shout = false

Overlay example (config/appsettings.Staging.toml):

[host]
port = 8080

Environment variables override file values. Nested keys use __:

ENVIRONMENT=Production
HOST__PORT=9001
LOGGING__LOG_LEVEL=DEBUG

Host bootstrap requires [service], [logging], [host], and [observability]. Set observability.enabled = true only with a non-empty otlp_endpoint.

App settings use Pydantic models registered with add_configuration. By default, {Name}Config maps to a [name] section in snake_case (LoggingConfig → logging, MessageBusConfig → message_bus). This works when each word is PascalCase with a single leading capital. Otherwise, pass section= to set the section name yourself.

from pydantic import BaseModel

from pepelats.configuration import Configuration
from pepelats.dependency_injection import ServiceCollection


class GreetingConfig(BaseModel):
    punctuation: str
    shout: bool


class HealthService:
    def __init__(self, config: GreetingConfig) -> None:
        self._config = config

    def status(self) -> str:
        message = "ok"
        if self._config.shout:
            message = message.upper()
        return message + self._config.punctuation


def register(services: ServiceCollection, configuration: Configuration) -> None:
    services.add_configuration(GreetingConfig)
    services.add_singleton(HealthService)

Examples

Runnable apps live under examples/. Each folder has a short README and a main.py you can run from the repo root:

uv run python examples/starlette-basic/main.py
uv run python examples/fastapi-basic/main.py
uv run python examples/background-worker/main.py
uv run python examples/observability/main.py

Example	What it shows
starlette-basic/	Generic host, manual DI with request_services
fastapi-basic/	FastAPI host, Inject[T] on routes
background-worker/	BackgroundService with a status route
observability/	Structured logging and spans on a request

Shared wiring for the greeting examples is in examples/shared/. Smoke tests: tests/example_smoke/.

See examples/README.md for per-example notes.

Dependencies

Pepelats uses:

• Starlette and Uvicorn — ASGI application and server
• Dishka — dependency injection
• Dynaconf and Pydantic — configuration
• structlog — structured logging
• OpenTelemetry — tracing and metrics

Optional:

• FastAPI — API layer (pepelats[fastapi])

License

Apache-2.0 — see LICENSE.