liblaf-conf 0.2.0

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 for one conversion path shared by environment values and direct assignments.
• 🔄 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

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(
        factory=lambda: ["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. Mutable defaults are copied when first read in each context; use a factory when constructing the value needs more than a copy.

Semantics

load_env(), set(), and override() affect only the active contextvars context. Child async tasks inherit values when they are created; existing tasks and threads keep their own context. to_dict() and to_namespace() read one active-context view and include active overrides. They allocate new container objects but do not deep-copy mutable field values.

For a field with an environment variable, load_env() is deterministic: a present variable is converted and installed; an absent variable clears the current value, so the next read uses a fresh declared default or factory value. Conversion errors always propagate. Direct set() and override() use that same field converter, rather than bypassing validation.

⌨️ 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.