draccus

0.11.5 · active · verified Tue Apr 14

Draccus is a Python library that provides a slightly opinionated framework for simple dataclass-based configurations, built as a fork of Pyrallis. It extends Pyrallis with advanced features such as support for subtyping configurations, the ability to include config files within other config files, and enhanced handling for containers of configurations. The current version is 0.11.5.

Warnings

gotcha Draccus is a fork of Pyrallis. While it maintains much of Pyrallis's API, it introduces unique features like subtyping and nested config file inclusion. Code expecting direct Pyrallis behavior for these advanced scenarios might need adaptation.
Fix: Consult Draccus documentation for differences, especially when using ChoiceRegistry, nested config files, or containers of configs. Prefer `draccus`'s own decorators and functions over direct `pyrallis` imports if you intend to use Draccus-specific features.
gotcha When using the `@draccus.wrap()` decorator, the decorated function's parameters are automatically populated by the parsed configuration. Avoid manually calling `draccus.parse()` within a function already wrapped by `@draccus.wrap()` unless a separate parsing context is explicitly intended.
Fix: Ensure that `draccus.wrap()` is applied directly to your main entry point function, and let it handle the configuration injection. If explicit parsing is needed for a sub-component, consider making it a separate, unwrapped function or using `draccus.parse()` directly where appropriate.
deprecated Earlier versions might have used `draccus.parse()` as the primary entry point. While still available, `@draccus.wrap()` is generally recommended for top-level application configuration due to its seamless integration.
Fix: Refactor your main application entry point to use the `@draccus.wrap()` decorator for a more streamlined and idiomatic approach to configuration management.

Install

pip install draccus Install stable version

Imports

wrap
```
import draccus
@draccus.wrap(...)
def main(cfg: Config): ...
```
The `@draccus.wrap()` decorator is the primary entry point for integrating dataclass configurations with argument parsing.
parse
```
import draccus
cfg = draccus.parse(config_class=Config)
```
Use `draccus.parse()` for manual parsing of a configuration dataclass, typically when not using the `@draccus.wrap()` decorator.

Quickstart

This example demonstrates how to define a simple dataclass for configuration and use the `@draccus.wrap()` decorator to parse command-line arguments or YAML files into an instance of that dataclass. Run it from the command line, for example: `python your_script.py --exp_name=my_first_exp --workers=4`.

from dataclasses import dataclass
import draccus

@dataclass
class TrainConfig:
    """Training Config for Machine Learning"""
    workers: int = 8  # The number of workers for training
    exp_name: str = 'default_exp' # The experiment name

@draccus.wrap()
def main(cfg: TrainConfig):
    print(f"Training {cfg.exp_name} with {cfg.workers} workers...")

if __name__ == "__main__":
    main()

view raw JSON →