dc-options 0.2.0

Dataclass-driven configuration helpers with metadata, validation, path access, argparse integration, and documentation generation.

dc_options

Dataclass-first configuration helpers with validation, metadata, argparse wiring, and documentation export. dc_options lets you describe nested option trees using familiar dataclasses while automatically generating CLIs, enforcing constraints, and producing Markdown/reference docs.

Features

• Declarative configuration via dataclasses and an option() helper carrying labels, ranges, choices, and UI hints.
• Strict loading/saving from JSON using dacite with metadata validation baked in.
• Path-based getters/setters (cfg.get("training.lr")) for ergonomic CLI or scripting overrides.
• Argparse integration that maps metadata to command-line flags.
• Documentation export using Jinja2 templates so UI teams and docs stay synced with code.

Project Layout

dc_options/         Core package (Options base class, metadata helper, docs template)
examples/           Minimal usage sample for experimentation
tests/              Pytest suites covering dump, path helpers, validation, etc.
pyproject.toml      uv/PEP 621 project definition
AGENTS.md           Contributor guide and workflow expectations

Getting Started

uv sync                             # install deps in .venv
uv run python examples/minimal.py   # inspect nested configs & path helpers
uv run python examples/argparse_example.py --serve.port 9090 --workers 4
uv run pytest tests -q              # run the test suite

To pull configuration from JSON or args:

from dc_options import Options, option

@dataclass
class Train(Options):
    epochs: int = option(default=10, min=1, label="Epochs")

cfg = Train.load("train.json")
cfg.validate()
parser = Train.build_argparser()
cfg.apply_cli_overrides(parser.parse_args())

Examples

• examples/minimal.py shows nested option classes, validation, and get/set helpers that operate on dot paths.
• examples/argparse_example.py demonstrates combining JSON loading with CLI overrides using build_argparser.

Documentation

• Update option metadata before exporting docs; the default template lives in dc_options/docs_template.md.j2.
• Generate fresh docs with uv run python - <<'PY' ... Options.export_docs(...).
• Preview site content through MkDocs (mkdocs serve) if documentation is published.

Metadata Reference

• label / description – available for every field; provide human-readable names and context.
• editable – all field types; mark values that should be read-only in generated UIs.
• min, max, step – numeric fields (int/float); used for validation and slider widgets.
• choices, labels – enumerations (str, int, etc.); specify allowed values and friendly labels.
• default, default_factory – all fields; stored in metadata for resets or documentation.

Contributing

Follow AGENTS.md for project structure tips, coding style, testing expectations, and git hygiene. Every feature or fix should ship with regression tests and refreshed docs whenever CLI behavior or configuration metadata changes.