Konfig

Settings management, pluggable secrets, and run-scoped logging for Python applications.

Konfig provides three foundational capabilities every Python application needs, with an optional lightweight app lifecycle context manager that ties them together. It is a clean-sheet replacement for dtPyAppFramework.

Features

• Layered settings with system/user/env/runtime precedence and persistent writes
• Pluggable secrets with OS keyring, AES-encrypted file, and AWS Secrets Manager backends
• Run-scoped logging with historical retention, structured JSON mode, and stdio-safe output
• Platform-aware defaults for config, data, and log directories (macOS, Linux, Windows)
• Optional app lifecycle via a sync/async context manager — no inheritance required
• Python 3.10+

Installation

pip install konfig

For AWS Secrets Manager support:

pip install konfig[aws]

Secrets

AWS Secrets Manager (designated secret)

Point konfig at a single AWS secret that holds a JSON bundle of your secrets (the secret must already exist):

export KONFIG_AWS_SECRETS_MANAGER=arn:aws:secretsmanager:eu-west-1:123456789012:secret:myapp/secrets-AbCdEf

from konfig import Secrets

secrets = Secrets()               # env var selects the AWS bundle backend
api_key = secrets.get("api_key")
secrets.set("api_key", "sk-new")  # read-modify-write back to the bundle

Requires pip install konfig[aws].

Running the LocalStack integration test

The AWS bundle backend has an opt-in integration test that runs against a local LocalStack container (no AWS account needed). It auto-skips when LocalStack is not running, so it never affects the normal test run.

docker compose up -d         # start LocalStack
pip install -e ".[dev,aws]"  # boto3 + dev tools
pytest -m localstack         # run only the integration test
docker compose down          # stop LocalStack

Quick Start

from konfig import AppContext

with AppContext(
    name="My Application",
    version="1.0.0",
    config_file="config.yaml",
    env_prefix="MYAPP",
) as ctx:
    host = ctx.settings.get("database.host", "localhost")
    api_key = ctx.secrets.get("api_key")
    ctx.logger.info("Starting with host=%s", host)

For async applications:

async with AppContext(name="My Server", version="2.0.0") as ctx:
    await run_server(ctx.settings)

Config file format

The config file format is chosen by the KONFIG_CONFIG_FORMAT environment variable (yaml, json, or sqlite). When unset, the format is detected from the file extension, defaulting to YAML. Reading, updating, and creating settings work in every format. (TOML config files are still supported by extension detection, but are read-only and cannot be selected via KONFIG_CONFIG_FORMAT.)

export KONFIG_CONFIG_FORMAT=sqlite   # store settings in a SQLite database file

from konfig import Settings

settings = Settings(config_file="config.db")
settings.set("database.host", "localhost", persist="user")  # written to SQLite
settings.set("debug", True)                                  # omit persist: in-memory only
host = settings.get("database.host")

Each subsystem (Settings, Secrets, LogManager) can also be used independently. See the full documentation in the docs/ directory:

• Settings Guide
• Secrets Guide
• Logging Guide
• AppContext Guide
• Platform Paths
• Configuration Reference
• API Reference

Samples

Working examples are provided in the samples/ directory:

Development

pip install -e ".[dev]"
pytest
pytest --cov=konfig
mypy src/konfig
black src/ tests/
isort src/ tests/

License

MIT License. See LICENSE for details.