omnixys-config

Unified, type-safe configuration for Omnixys services, built on pydantic-settings. Every service setting lives in one settings tree with section-scoped environment variables, matching the conventions used across the Omnixys codebase.

Installation

pip install omnixys-config

Features

• One settings tree — AppSettings groups core, database, keycloak, security, kafka, cache, observability, and storage configuration into nested typed models.
• Environment binding — every section reads its own env_prefix (database_, keycloak_, security_, kafka_, cache_, otel_, storage_, ...); flat core settings read unprefixed variables (SERVICE_NAME, PORT, ...).
• Nested environment support — environment values are applied to nested settings models at every depth (e.g. security.jwk.keys from JWK_KEYS, kafka.topics.outbox from TOPIC_OUTBOX), something vanilla pydantic-settings does not do for nested models.
• List values — list fields parse JSON from the environment (SECURITY_PERMIT_ALL_PATHS='["/health", "/metrics"]', JWK_KEYS='["k1", "k2"]').
• Env files — a .env file is loaded automatically; a custom file can be passed to load_settings(env_file=...). Precedence is env var > env file > default.
• Computed helpers — core.is_local / is_development / is_production, keycloak.issuer / jwks_url.
• Factories — get_settings() / load_settings() return a single cached AppSettings per call site.

Quick start

from config import get_settings

settings = get_settings()

settings.core.service_name          # "orders"
settings.database.url               # "postgresql+asyncpg://localhost/omnixys"
settings.security.jwk.keys          # [..]
settings.kafka.topics.outbox        # "omnixys.outbox.event"

Wire the settings object once per service, e.g. with dishka:

from dishka import make_async_container
from config import AppSettings, get_settings

def settings_provider() -> AppSettings:
    return get_settings()

container = make_async_container(settings_provider)
settings = await container.get(AppSettings)

Settings reference

Core

Core helpers: is_local (environment == "local"), is_development (local/development), is_production (production).

Database (database_)

Keycloak (keycloak_)

Helpers: issuer ({url}/realms/{realm}), jwks_url ({issuer}/protocol/openid-connect/certs).

Security (security_)

Nested sections use their own prefixes: JWK_KEYS (jwk_), SESSION_TTL_MS (session_), RATE_LIMIT_ENABLED / RATE_LIMIT_DEFAULT_LIMIT / RATE_LIMIT_DEFAULT_WINDOW_MS (rate_limit_).

Kafka (kafka_)

Topic names use the topic_ prefix (TOPIC_DELIVERY_STATUS, TOPIC_CONVERSATION_CREATED, TOPIC_CONVERSATION_MESSAGE, TOPIC_EVENT_CREATED, TOPIC_EVENT_UPDATED, TOPIC_NOTIFICATION_SEND, TOPIC_SEAT_CHANGED, TOPIC_TICKET_ISSUED, TOPIC_AUDIT_LOG, TOPIC_OUTBOX).

Cache (cache_)

Observability (otel_)

Storage (storage_)

Precedence

Values are resolved as environment variable > env file > default. Env files are loaded with override=False, so an already-set variable always wins:

from config import load_settings

# reads /path/to/app.env for values not already present in the environment
settings = load_settings(env_file="/path/to/app.env")

Without an argument, a .env file in the working directory is loaded if it exists. All section-prefixed variables (database_, keycloak_, ...) are read from the env file as well.

Development

uv sync
uv run pytest -q
uv run ruff check .
uv run mypy src/

License

GPL-3.0-or-later