yacs

library0.1.8pypypi✓ verified 23d ago

YACS is a lightweight Python library for defining and managing system configurations, particularly useful in scientific experimentation for reproducibility. It provides a hierarchical CfgNode object for structured configuration and supports loading configurations from both Python files and YAML files. The current version is 0.1.8, with a relatively active release cadence.

ai-ml data workflow

pip install yacs

github ↗package ↗

INSTALL

IMPORT

SIG · YACS

yacs

ai-mlpythonv0.1.8

Install

1.6s avg

Import

158ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.8 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.162s · 20MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.154s · 21MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CfgNode

✓ from yacs.config import CfgNode as CN

This quickstart demonstrates how to define a default configuration using `CfgNode`, retrieve a mutable copy, and then merge overrides from a YAML file and a list of command-line style options. It also shows the recommended practice of freezing the configuration to ensure reproducibility.

from yacs.config import CfgNode as CN import os # 1. Define your default configuration in a Python file (e.g., config.py) _C = CN() _C.SYSTEM = CN() _C.SYSTEM.NUM_GPUS = 8 _C.SYSTEM.NUM_WORKERS = 4 _C.TRAIN = CN() _C.TRAIN.HYPERPARAMETER_1 = 0.1 _C.TRAIN.SCALES = (2, 4, 8, 16) def get_cfg_defaults(): """Get a yacs CfgNode object with default values.""" return _C.clone() # 2. Example usage in your main application # Simulate an experiment.yaml file # This content would typically be in a separate file # with only the overrides. experiment_yaml_content = """ SYSTEM: NUM_GPUS: 2 TRAIN: SCALES: (1, 2, 3, 4) """ # Create a dummy experiment.yaml for demonstration with open("experiment.yaml", "w") as f: f.write(experiment_yaml_content) if __name__ == "__main__": cfg = get_cfg_defaults() # Merge from an experiment-specific YAML file cfg.merge_from_file("experiment.yaml") # Override from a list of key-value pairs (e.g., from command line) opts = ["SYSTEM.NUM_GPUS", 1, "TRAIN.HYPERPARAMETER_1", 0.5] cfg.merge_from_list(opts) # Freeze the configuration to prevent further modification cfg.freeze() print("Final Configuration:") print(cfg) print(f"Number of GPUs: {cfg.SYSTEM.NUM_GPUS}") print(f"Training Hyperparameter 1: {cfg.TRAIN.HYPERPARAMETER_1}") print(f"Training Scales: {cfg.TRAIN.SCALES}") # Clean up dummy file os.remove("experiment.yaml")

Debug

Known issues

breakingVersion 0.1.7 introduced explicit support for non-string keys in CfgNode. Prior to this, using non-string keys might have resulted in errors or implicit string conversion, which could be a breaking change for code that relied on or inadvertently used such keys.

fix

Review existing configurations and code for usage of non-string keys. If present, ensure they are compatible with the new behavior or adapt them accordingly.

affects: <0.1.7

gotchaYACS promotes the principle of "There is only one way to configure the same thing." It's a common footgun to use both YACS's `merge_from_list` for command-line overrides and separate `argparse` arguments for the same configuration options, leading to confusion or unexpected behavior.

fix

When using YACS, consolidate all command-line overrides through `cfg.merge_from_list(opts)` to maintain a single source of truth for configuration values. Avoid redundant argument parsing for values already managed by YACS.

affects: All

gotchaAfter loading and merging all configuration options, it's highly recommended to call `cfg.freeze()` to prevent accidental runtime modifications. Forgetting to freeze can lead to configurations changing unexpectedly during execution, hindering reproducibility.

fix

Always call `cfg.freeze()` on your primary configuration object once all modifications and merges are complete, typically at the start of your application logic.

affects: All

gotchaThere are multiple Python projects named 'YACS' (e.g., for course scheduling or SALOME GUI). Ensure you are importing and using `yacs` from `github.com/rbgirshick/yacs` for the configuration system described here, as their functionalities are entirely distinct.

fix

Verify your `pip install` commands and import statements (`from yacs.config import CfgNode`) to ensure you're using the correct configuration library.

affects: All

gotchaWhen loading configurations from Python source files (`yacs>=0.1.4`), the module must export a global variable named `cfg` of type `dict` or `CfgNode`. Deviating from this convention will lead to import errors.

fix

Ensure that any Python configuration file intended for YACS loading exports a variable named `cfg` (e.g., `cfg = CN()` or `cfg = {'KEY': 'VALUE'}`) at the module level.

affects: >=0.1.4

Errors

Common errors & fixes

ImportError: cannot import name 'CfgNode' from 'yacs'

The `CfgNode` class, which represents the configuration object, is located within the `yacs.config` submodule, not directly under the top-level `yacs` package.

fix

from yacs.config import CfgNode

KeyError: 'Attempting to set an immutable CfgNode field: FOO.BAR'

You are attempting to modify a configuration field after the `CfgNode` object has been frozen using `cfg.freeze()`, which makes it immutable.

fix

cfg.defrost()
cfg.FOO.BAR = 2
cfg.freeze()

FileNotFoundError: [Errno 2] No such file or directory: "{'B': 2}"

The `cfg.merge_from_file()` method expects a string path to a configuration file, not another `CfgNode` object.

fix

from yacs.config import CfgNode
cfg1 = CfgNode({'A': 1})
cfg2 = CfgNode({'B': 2})
cfg1.merge_from_other_cfg(cfg2)

AttributeError: type object 'CfgNode' has no attribute 'from_dict'

`CfgNode` does not provide a static factory method `from_dict()`; you create a `CfgNode` from a Python dictionary by passing the dictionary directly to its constructor.

fix

from yacs.config import CfgNode
my_dict = {'A': 1, 'B': {'C': 2}}
cfg = CfgNode(my_dict)

Upgrade

Version history

0.1.8latest on PyPI · released Aug 10, 2020

Audit

Dependencies

PyYAMLoptionalRequired for loading and dumping configurations from/to YAML files.

Agent activity

50 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/rbgirshick/yacs ↗

packagehttps://pypi.org/project/yacs/ ↗