dargs

0.5.0.post0 verified Fri May 01 auth: no python

Process arguments for the deep modeling project. Current version: 0.5.0.post0. Release cadence: irregular, with recent releases every few months. Supports Python >=3.7.

pip install dargs

Common errors

error dargs.exceptions.DargsError: The argument 'X' is not defined. ↓

cause User input contains a key not defined in the argument specification.

fix

Remove the extra key or add it to the argument list using Argument(...).

error dargs.exceptions.DargsError: The variant choice 'Y' is invalid. ↓

cause The value for a variant field does not match any of the defined variant choices.

fix

Check the variant choices and provide a valid one; e.g., for backend, use 'tensorflow' or 'pytorch'.

error dargs.exceptions.DargsError: Expected type 'int' but got 'str'. ↓

cause A field value has a mismatched type compared to the Argument's dtype.

fix

Ensure the user input conforms to the expected types, or use a custom dtype validator.

Warnings

breaking In v0.5.0, the `default` parameter may behave differently for mutable types (e.g., list, dict). Now defaults are deep-copied to avoid mutation sharing. If you rely on defaults being shared across calls, you must update your code to explicitly handle that. ↓

fix Review usage of mutable defaults; consider using factory functions if sharing is needed.

gotcha When using Variant, the variant key (e.g., 'backend') must be a string, and the choice key must be exactly one of the defined variant names. Common mistake: nesting variant inside another variant incorrectly. ↓

fix Ensure user input structure matches the variant hierarchy exactly.

deprecated The `dargs.cli` module (exposed in v0.4.8) is deprecated in favor of using `Argument` directly with command-line parsing via `argparse`. The `dargs` CLI may be removed in future versions. ↓

fix Stop importing from dargs.cli; use Argument definitions and argparse for CLI.

Imports

Argument
```
from dargs import Argument
```
The main class for defining arguments.
normalize
```
from dargs import normalize
```
Normalize input dictionary against argument definitions.
dedent
```
from dargs import dedent
```
Remove leading whitespace from multi-line argument documentation.
Variant
```
from dargs import Variant
```
Define variant arguments (e.g., different model types).

Quickstart

Basic usage of dargs: define arguments with variants, then normalize user input.

from dargs import Argument, Variant, normalize

# Define arguments
arg1 = Argument("learning_rate", float, default=0.001)
arg2 = Argument("layers", list, default=[128, 64])

# Define a variant
variant = Variant("backend", [
    Argument("tensorflow", dict, [
        Argument("device", str, default="GPU")
    ]),
    Argument("pytorch", dict, [
        Argument("device", str, default="CPU")
    ])
])

# Compile arguments
args = [arg1, arg2, variant]

# Example user input
user_input = {
    "learning_rate": 0.01,
    "layers": [256, 128],
    "backend": {
        "tensorflow": {"device": "TPU"}
    }
}

# Normalize (validate and apply defaults)
try:
    normalized = normalize(args, user_input)
    print("Normalized config:", normalized)
except Exception as e:
    print("Error:", e)