qstd-config

A lightweight and flexible configuration management library for Python applications, built on top of Pydantic.
It allows you to load and validate settings from multiple sources (YAML/JSON files, environment variables, or custom loaders), merge them via strategy, and supports hot-reload as well as multiprocess-safe sharing.

---

Key Features

• Chain of loaders: load configuration from multiple sources (files, environment variables, custom loaders).
• Pydantic integration: validate the final config using a BaseModel.
• Flexible merge strategies: deep merge by default, with support for custom strategies.
• ProxyConfig: proxy object with reload(), setup() methods and model attribute access.
• Hot-reload support: update configuration at runtime without restarting the process.
• Multiprocessing storage: share configuration between processes using multiprocessing.Manager().dict().
• Extensibility: plug in custom loaders, merge strategies, and storages.

---

Documentation

• ConfigManager
• Config Proxy and Storage
• Extension

---

Install

pip install qstd-config

---

Quick start

from pydantic import BaseModel
from qstd_config import ConfigManager


class AppConfig(BaseModel):
    class DB(BaseModel):
        host: str = "localhost"
        port: int = 5432

    debug: bool = False
    db: DB


manager = ConfigManager(
    AppConfig,
    project_name="My App",
    config_paths=["./config.yaml"],
    default_config_values={"debug": False},
)
config = manager.load_config_model()

print(config.db.host, config.db.port, config.debug)

---

Environment variables

The list of supported environment variables is automatically generated based on the structure of the config model. You can override variable names explicitly via json_schema_extra in Pydantic’s Field. For example:

from pydantic import BaseModel, Field

class AppConfig(BaseModel):
    class DB(BaseModel):
        host: str = Field("localhost")
        port: int = Field(5432, json_schema_extra={'env': 'DATABASE_PORT'})

    debug: bool = False
    db: DB

Recognized environment variables:

• DEBUG
• DB_HOST
• DATABASE_PORT

If project_name="My App" is specified, variables will be prefixed:

• MY_APP_DEBUG
• MY_APP_DB_HOST
• MY_APP_DATABASE_PORT

---

Configuration paths

You can provide configuration file paths from multiple sources. The order below defines the precedence (higher overrides lower):

1. CLI argument: --config=/path/to/config.yaml
2. Environment variable: MY_APP_CONFIG=/path1.yaml;/path2.yaml
3. config_paths argument passed explicitly to the manager

---

Tests

pytest --cov=qstd_config --cov-report=term-missing

---

Compatibility

Tested on Python 3.9-3.13.

---

License

MIT License