Eafig
Manage your hyperparameters from the outside.
Installation
pip install eafig
Requires Python ≥ 3.12.
Quick Start
import eafig
from eafig import configclass
@configclass("training")
class TrainingConfig:
a: int = 1
c: float = 1.0
@configclass(name="model")
class ModelConfig:
x: str = "hello"
y: str = "world"
# Load from file, then CLI — later calls win
eafig.load("config/default.yaml")
eafig.from_cli()
# Instantiate — values come from file/CLI or defaults
training = TrainingConfig()
model = ModelConfig()
# Save to file
eafig.save("config/saved_config.yaml")
Core ideas
Group-only layers
There is no "root config". Every config class is a named group registered with
@configclass("path"). The path is dot-separated for nesting:
@configclass("model")
class ModelConfig:
hidden_dim: int = 256
@configclass("model.optimizer")
class OptimizerConfig:
lr: float = 1e-3
Every field needs a default
Fields must declare a default value (or a default_factory). Registering a field
without one raises a TypeError:
@configclass("model")
class ModelConfig:
hidden_dim: int = 256 # OK
# lr: float # TypeError: must provide a default value
Config loading order
defaults < file (load) < CLI (from_cli)
Each layer overrides the one before it. Among load() / from_cli() calls,
later calls win.
keep_cli
A later load() normally overrides CLI values. Pass keep_cli=True to keep CLI
on top:
eafig.from_cli()
eafig.load("config.yaml", keep_cli=True) # CLI stays above file
load_by_cli
Load a config file whose path comes from a command-line flag:
# python app.py --config config.yaml
eafig.load_by_cli("config")
The flag is registered as the single root schema field, remains in the stored
configuration, and is included by save(). Because the root schema may only be
registered once, load_by_cli() may only be called once per process when the flag
is present; a second call raises ValueError.
CLI overrides
--model.hidden_dim 1024 --model.optimizer.lr 1e-3
A flag with no value is True; dotted keys nest. An explicitly supplied empty
argument remains an empty string:
eafig.from_cli(["--debug", "--name", ""])
assert eafig.get("debug") is True
assert eafig.get("name") == ""
Unknown keys (allow_dynamic_children)
By default a config group rejects keys that are not declared fields or child
groups. The rejection happens when the config is read — when you instantiate the
group or call save():
@configclass("model")
class ModelConfig:
hidden_dim: int = 256
eafig.load("config.yaml") # config.yaml has model.typo_key → loaded without error
model = ModelConfig() # KeyError: Invalid key(s) {'typo_key'}
Set allow_dynamic_children=True to tolerate extra keys (they are ignored):
@configclass("model", allow_dynamic_children=True)
class ModelConfig:
hidden_dim: int = 256
Schema registration may happen after load(). Loading performs structural
validation for schema paths already known at that time; unknown-key validation is
deferred until a group is instantiated or the configuration is saved.
Hidden groups
@configclass("api", hidden=True)
class ApiConfig:
secret_key: str = "..."
Hidden groups are excluded from save() and from recursive reads by default.
Frozen groups
@configclass("model", frozen=True)
class ModelConfig:
hidden_dim: int = 256
m = ModelConfig() # OK — uses defaults
m.hidden_dim = 1024 # FrozenInstanceError
Runtime get
value = eafig.get("model.hidden_dim") # 256
value = eafig.get("missing.key", default=0) # 0
API reference
| API | Description |
|---|---|
@configclass(name, *, frozen=False, hidden=False, allow_dynamic_children=False) |
Register a dataclass as a config group |
eafig.load(path=None, keep_cli=False) |
Load a YAML file or file-like object |
eafig.from_cli(args=None) |
Parse CLI args (default: sys.argv[1:]) |
eafig.load_by_cli(flag, keep_cli=False) |
Load a file path taken from a CLI flag |
eafig.save(path, sort_keys=True) |
Save the config to YAML |
eafig.get(key, default=None) |
Get a single value (dot notation) |
Examples
See examples/.
License
MIT
Metadata
Release files for eafig 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| eafig-2.0.0.tar.gz | 23.8 kB | With provenance | Details for eafig-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| eafig-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for eafig-2.0.0-py3-none-any.whl |
Total release size: 34.7 kB
Release files / eafig-2.0.0.tar.gz
| Download URL | eafig-2.0.0.tar.gz |
|---|---|
| Size | 23.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2941a977840f404051783a737a29fe74b967cf925c208e08150594959cde7717
|
|
BLAKE2b-256 checksum How to use checksums |
28eb90a9eb94dfe645d59f8979bcf7dc65db7a4f6a3c2601c83b05123d9d73cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 29, 2026.
Transparency logRelease files / eafig-2.0.0-py3-none-any.whl
| Download URL | eafig-2.0.0-py3-none-any.whl |
|---|---|
| Size | 10.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
77723406101d5f371a60a41f71d640523657590909e88bf2f181bd7c3fd4289a
|
|
BLAKE2b-256 checksum How to use checksums |
43d854be42be12cd935cb76945a58f81ce7b988d005bb9aa23ac1f9699725fd6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 29, 2026.
Transparency logSecurity for eafig 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for eafig-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.