Settings Reference¶

Configuration reference for cosalette applications. Settings are managed by pydantic-settings and can be set via constructor arguments, environment variables, or .env files.

Root Settings¶

Settings(**data: Any)

MQTT__HOST=broker.local
MQTT__PORT=1883
MQTT__USERNAME=user
MQTT__PASSWORD=secret
LOGGING__LEVEL=DEBUG
LOGGING__FORMAT=text

class MyAppSettings(Settings):
    model_config = SettingsConfigDict(
        env_prefix="MYAPP_",
        env_nested_delimiter="__",
        env_file=".env",
        env_file_encoding="utf-8",
    )

347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372

def __init__(self, **data: Any) -> None:
    # Pop before super().__init__ so pydantic doesn't treat it as a field value
    config_file = data.pop("_config_file", _UNSET)
    token = _config_file_override.set(config_file)
    try:
        super().__init__(**data)
    except SettingsError as exc:
        # Without an env_prefix the reserved root names (MQTT, LOGGING,
        # SCHEMA) are read from the whole process environment; a bare
        # non-JSON variable of that name (e.g. SCHEMA=public set by CI or
        # DB tooling) makes complex-field parsing fail with an opaque
        # error. Translate it into actionable guidance (CWE-15) only when
        # the error actually originates from those reserved fields.
        _RESERVED = ("mqtt", "logging", "schema")
        if any(name in str(exc).lower() for name in _RESERVED):
            raise SettingsError(
                f"{exc} [hint: cosalette reads the reserved root environment "
                "variables MQTT, LOGGING and SCHEMA (complex fields expecting "
                "JSON, plus nested MQTT__*/LOGGING__*/SCHEMA__* names). A "
                "same-named non-JSON variable in your environment collides "
                "with them — unset/rename it, or set env_prefix in your "
                "Settings subclass.]"
            ) from exc
        raise
    finally:
        _config_file_override.reset(token)

model_config = SettingsConfigDict(
    env_nested_delimiter="__",
    env_file=".env",
    env_file_encoding="utf-8",
    extra="ignore",
)

MQTT Settings¶

MQTT__HOST=broker.local
MQTT__PORT=1883
MQTT__USERNAME=user
MQTT__PASSWORD=secret
MQTT__TOPIC_PREFIX=myapp

Logging Settings¶

Environment Variables¶

All settings can be overridden via environment variables using the nested __ separator convention from pydantic-settings.

Nested Delimiter Convention¶

Pydantic-settings uses __ (double underscore) as the nested delimiter: MQTT__HOST maps to settings.mqtt.host. When a subclass adds env_prefix="MYAPP_", the prefix prepends the entire path: MYAPP_MQTT__HOST → settings.mqtt.host.

# Base variables (no prefix, base Settings class)
export MQTT__HOST=broker.local
export MQTT__PORT=1883
export LOGGING__LEVEL=DEBUG

# Prefixed variables (subclass with env_prefix="GAS2MQTT_")
export GAS2MQTT_MQTT__HOST=broker.local
export GAS2MQTT_LOGGING__LEVEL=INFO

.env File Loading¶

A .env file in the working directory is loaded automatically by pydantic-settings when env_file=".env" appears in model_config. The file path can be overridden at runtime with the --env-file CLI flag:

myapp --env-file /etc/myapp/production.env

MQTT¶

Logging¶

The app.settings Property¶

App.__init__ eagerly instantiates the settings_class passed to the constructor. The resulting instance is exposed as the read-only app.settings property.

Because the instance is created at construction time — before any decorators run — you can use it in decorator arguments:

app = cosalette.App(
    name="gas2mqtt",
    version="1.0.0",
    settings_class=Gas2MqttSettings,
)

@app.telemetry("counter", interval=app.settings.poll_interval)
async def counter() -> dict[str, object]:
    return {"impulses": 42}

Environment variables and .env files are read when settings_class() is called inside App.__init__, so app.settings.poll_interval reflects the actual runtime value.

The extra="ignore" Behaviour¶

The base Settings class sets extra="ignore" in its model_config:

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_nested_delimiter="__",
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
    )

Why: The base class has no env_prefix, so pydantic-settings reads every environment variable in the process. The BaseSettings default of extra="forbid" would reject unrelated variables (PATH, HOME, GH_TOKEN, etc.) as validation errors.

extra="ignore" silently discards unknown variables, making the base class work in any environment.

Settings Injection¶

Settings are automatically injected into device handlers and adapter factory callables that declare a parameter annotated with Settings (or a subclass).

See the Adapters guide for examples of settings injection in factory callables.