secret-backed-settings 0.1.0

Tiny Pydantic settings base class for quiet local and Docker file secrets

secret-backed-settings

Tiny Pydantic settings base class for projects that use environment variables plus local or Docker file secrets.

The package is intentionally small. It is not a configuration framework; it is a single BaseSettings subclass with a stable source-order contract.

Install

uv add secret-backed-settings

or:

pip install secret-backed-settings

For local ContentShuttle workspace development with uv, use the workspace source configured by the consuming project.

Usage

from pydantic_settings import SettingsConfigDict
from secret_backed_settings import SecretBackedSettings


class AppSettings(SecretBackedSettings):
    model_config = SettingsConfigDict(
        env_prefix="APP_",
        case_sensitive=False,
        extra="ignore",
    )

    api_key: str
    base_url: str

Environment variables use the configured prefix:

$env:APP_API_KEY = "env-token"
$env:APP_BASE_URL = "https://example.com"

File secrets use unprefixed field names:

.secrets/api_key
.secrets/base_url

Precedence

Values are loaded in this order:

1. Explicit constructor values.
2. Existing file secrets.
3. Environment variables.
4. Dotenv values.
5. Field defaults.

Default secret directories are .secrets and /run/secrets. Missing default directories are ignored so local development and tests do not warn when Docker secrets are absent. Later directories override earlier directories, so /run/secrets wins over .secrets when both exist.

Pass _secrets_dir when a caller needs a different path:

settings = AppSettings(_secrets_dir="/path/to/secrets")