liblaf-conf 0.1.2

Descriptor-based Python configuration models with environment loading and context-local overrides.

Explore the docs »

Changelog · Report Bug · Request Feature

liblaf-conf lets Python applications define typed configuration once, load it from environment variables, and apply scoped runtime overrides with contextvars.

✨ Features

• 🧩 Descriptor-based config models: Build config objects from BaseConfig, Field, and group() instead of wiring ad hoc globals or nested dicts.
• 🌱 Environment-ready defaults: Bind fields to derived or explicit environment variable names and refresh a whole config tree with load_env().
• 🎯 Typed helper factories: Reach for field_bool, field_json, field_path, and the temporal helpers when you want built-in string parsing.
• 🔄 Context-local overrides: Use Var.override() or BaseConfig.override() to change values temporarily without leaking across contexts.
• 🪺 Nested serialization helpers: Compose related sections and export the active state with to_dict() or to_namespace().

📦 Installation

[!NOTE] liblaf-conf supports Python 3.12 and newer.

uv add liblaf-conf

🚀 Quick Start

from liblaf import conf


class DatabaseConfig(conf.BaseConfig):
    url: conf.Field[str] = conf.field_str(default="sqlite:///app.db")


class AppConfig(conf.BaseConfig):
    debug: conf.Field[bool] = conf.field_bool(default=False)
    allowed_hosts: conf.Field[list[str]] = conf.field_list_str(default=["localhost"])
    database: conf.Group[DatabaseConfig] = conf.group(DatabaseConfig)


cfg = AppConfig()
cfg.set(database={"url": "sqlite:///dev.db"})

cfg.load_env()
cfg.debug.set(True)

with cfg.override(debug=False):
    assert cfg.debug.get() is False

assert cfg.to_dict() == {
    "debug": True,
    "allowed_hosts": ["localhost"],
    "database": {"url": "sqlite:///dev.db"},
}

BaseConfig subclasses are cached singletons, so AppConfig() returns the same config object each time while each field still stores its active value in a ContextVar.

⌨️ Local Development

Clone the repository and use the maintained task surfaces:

git clone https://github.com/liblaf/conf.git
cd conf
mise install
mise run lint
nox --tags test
mise run docs:serve

mise provides the primary setup, lint, and docs commands in this repository. nox drives the Python test matrix used by CI.

🤝 Contributing

Issues and pull requests are welcome, especially when they improve the public API, typed converter helpers, or documentation examples.

🔗 Links

• Documentation
• PyPI
• Source Code
• Release Notes

---

📝 License

Copyright © 2026 liblaf.
This project is MIT licensed.