heracls 0.1.0__tar.gz

heracls-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 François Rozet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heracls-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: heracls
+Version: 0.1.0
+Summary: Slayer of Hydra
+Author-email: François Rozet <francois.rozet@outlook.com>
+License-Expression: MIT
+Project-URL: documentation, https://github.com/francois-rozet/heracls
+Project-URL: source, https://github.com/francois-rozet/heracls
+Project-URL: tracker, https://github.com/francois-rozet/heracls/issues
+Keywords: config,dataclass
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dacite>=1.9.2
+Requires-Dist: omegaconf>=2.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: ruff==0.15.2; extra == "dev"
+Dynamic: license-file
+
+# Heracls - Slayer of Hydra
+
+`heracls` is a tiny utility package to instantiate typed dataclasses from flexible config sources (dictionary, OmegaConf, YAML, dotlist, ...). It is designed for projects that want strict, typed config objects while supporting the dynamic overrides commonly used in scripts and experiments.
+
+## Installation
+
+The `heracls` package is available on [PyPi](https://pypi.org/project/heracls) and can be installed with `pip`.
+
+```
+pip install heracls
+```
+
+Alternatively, if you need the latest features, you can install it from source.
+
+```
+pip install git+https://github.com/francois-rozet/heracls
+```
+
+## Getting started
+
+The following example demonstrates how to declare a nested dataclass config, instantiate it while overriding default fields with a dotlist, serialize it to YAML, and use its fields in a script.
+
+```python
+import heracls
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, Tuple, Union
+
+@dataclass
+class AdamConfig:
+    optimizer: Literal["adam", "adamw"] = "adam"
+    betas: Tuple[float, float] = (0.95, 0.95)
+    learning_rate: float = 1e-3
+    weight_decay: float = 0.0
+
+@dataclass
+class SGDConfig:
+    optimizer: Literal["sgd"] = "sgd"
+    momentum: float = 0.0
+    learning_rate: float = 1e-3
+    weight_decay: float = 0.0
+    nesterov: bool = False
+
+@dataclass
+class TrainConfig:
+    optim: Union[AdamConfig, SGDConfig] = field(default_factory=AdamConfig)
+    n_epochs: int = 1024
+    data_splits: Tuple[float, float] = (0.8, 0.1)
+    slurm: Dict[str, Any] = field(default_factory=dict)
+
+dotlist = [  # usually retrieved from the command line
+    "optim.optimizer=sgd",
+    "data_splits=[0.7,0.2]",
+    "slurm.account=frozet",
+]
+
+cfg = heracls.from_dotlist(TrainConfig, dotlist)
+
+with open("config.yaml", "w") as f:
+    f.write(heracls.to_yaml(cfg))
+
+trainset, validset, testset = load_dataset(cfg.data_splits)
+
+for epoch in range(cfg.n_epochs):
+    ...
+```
+
+The fields that are not specified in the dotlist are instantiated with their default value, as can be seen in the dumped `config.yaml` file.
+
+```yaml
+optim:
+  optimizer: sgd
+  momentum: 0.0
+  learning_rate: 0.001
+  weight_decay: 0.0
+  nesterov: false
+n_epochs: 1024
+data_splits:
+- 0.7
+- 0.2
+slurm:
+  account: frozet
+```

heracls-0.1.0/README.md

@@ -0,0 +1,83 @@
+# Heracls - Slayer of Hydra
+
+`heracls` is a tiny utility package to instantiate typed dataclasses from flexible config sources (dictionary, OmegaConf, YAML, dotlist, ...). It is designed for projects that want strict, typed config objects while supporting the dynamic overrides commonly used in scripts and experiments.
+
+## Installation
+
+The `heracls` package is available on [PyPi](https://pypi.org/project/heracls) and can be installed with `pip`.
+
+```
+pip install heracls
+```
+
+Alternatively, if you need the latest features, you can install it from source.
+
+```
+pip install git+https://github.com/francois-rozet/heracls
+```
+
+## Getting started
+
+The following example demonstrates how to declare a nested dataclass config, instantiate it while overriding default fields with a dotlist, serialize it to YAML, and use its fields in a script.
+
+```python
+import heracls
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, Tuple, Union
+
+@dataclass
+class AdamConfig:
+    optimizer: Literal["adam", "adamw"] = "adam"
+    betas: Tuple[float, float] = (0.95, 0.95)
+    learning_rate: float = 1e-3
+    weight_decay: float = 0.0
+
+@dataclass
+class SGDConfig:
+    optimizer: Literal["sgd"] = "sgd"
+    momentum: float = 0.0
+    learning_rate: float = 1e-3
+    weight_decay: float = 0.0
+    nesterov: bool = False
+
+@dataclass
+class TrainConfig:
+    optim: Union[AdamConfig, SGDConfig] = field(default_factory=AdamConfig)
+    n_epochs: int = 1024
+    data_splits: Tuple[float, float] = (0.8, 0.1)
+    slurm: Dict[str, Any] = field(default_factory=dict)
+
+dotlist = [  # usually retrieved from the command line
+    "optim.optimizer=sgd",
+    "data_splits=[0.7,0.2]",
+    "slurm.account=frozet",
+]
+
+cfg = heracls.from_dotlist(TrainConfig, dotlist)
+
+with open("config.yaml", "w") as f:
+    f.write(heracls.to_yaml(cfg))
+
+trainset, validset, testset = load_dataset(cfg.data_splits)
+
+for epoch in range(cfg.n_epochs):
+    ...
+```
+
+The fields that are not specified in the dotlist are instantiated with their default value, as can be seen in the dumped `config.yaml` file.
+
+```yaml
+optim:
+  optimizer: sgd
+  momentum: 0.0
+  learning_rate: 0.001
+  weight_decay: 0.0
+  nesterov: false
+n_epochs: 1024
+data_splits:
+- 0.7
+- 0.2
+slurm:
+  account: frozet
+```

heracls-0.1.0/heracls/__init__.py

@@ -0,0 +1,14 @@
+"""Heracls - Slayer of Hydra"""
+
+__version__ = "0.1.0"
+
+from . import patch, transforms  # noqa: F401
+from .transforms import (  # noqa: F401
+    from_dict,
+    from_dotlist,
+    from_omega,
+    from_yaml,
+    to_dict,
+    to_omega,
+    to_yaml,
+)

heracls-0.1.0/heracls/patch.py

@@ -0,0 +1,35 @@
+"""Monkey patching."""
+
+import dacite
+
+from collections.abc import Mapping
+from dacite.core import Config, _build_value, extract_generic, is_subclass
+from typing import Any
+
+
+def _build_value_for_collection(collection: type, data: Any, config: Config) -> Any:
+    data_type = type(data)
+    if isinstance(data, dict) and is_subclass(collection, Mapping):
+        types = extract_generic(collection, defaults=(Any, Any))
+        return data_type(
+            (key, _build_value(type_=types[1], data=value, config=config))
+            for key, value in data.items()
+        )
+    elif isinstance(data, (list, tuple)) and is_subclass(collection, tuple):
+        types = extract_generic(collection)
+        if len(types) == 2 and types[1] is Ellipsis:
+            return data_type(
+                _build_value(type_=types[0], data=item, config=config) for item in data
+            )
+        elif len(data) == len(types):
+            return data_type(
+                _build_value(type_=type_, data=item, config=config)
+                for item, type_ in zip(data, types)
+            )
+    elif isinstance(data, (list, tuple)):
+        types = extract_generic(collection, defaults=(Any,))
+        return data_type(_build_value(type_=types[0], data=item, config=config) for item in data)
+    return data
+
+
+dacite.core._build_value_for_collection = _build_value_for_collection

heracls-0.1.0/heracls/transforms.py

@@ -0,0 +1,132 @@
+"""Data transformations."""
+
+__all__ = [
+    "from_dict",
+    "from_dotlist",
+    "from_omega",
+    "from_yaml",
+    "to_dict",
+    "to_omega",
+    "to_yaml",
+]
+
+import dacite
+
+from dataclasses import fields as iter_fields
+from dataclasses import is_dataclass
+from omegaconf import DictConfig, OmegaConf
+from typing import Any, ClassVar, Dict, List, Protocol, Type, TypeVar
+
+T = TypeVar("T")
+
+
+class DataClass(Protocol):
+    __dataclass_fields__: ClassVar[Dict[str, Any]]
+
+
+def from_dict(data_cls: Type[T], data: Dict[str, Any]) -> T:
+    """Instantiate a dataclass from a dictionary.
+
+    Arguments:
+        data_cls: A dataclass type.
+        data: A dictionary.
+
+    Returns:
+        A `data_cls` instance.
+    """
+    return dacite.from_dict(
+        data_class=data_cls,
+        data=data,
+        config=dacite.Config(
+            cast=[tuple],
+            strict=True,
+            strict_unions_match=True,
+        ),
+    )
+
+
+def to_dict(data: DataClass, /, recursive: bool = False) -> Dict[str, Any]:
+    """Convert a dataclass instance to a dictionary.
+
+    Arguments:
+        data: A dataclass instance.
+        recursive: Recursively convert nested dataclasses when `True`.
+
+    Returns:
+        A dictionary representation of `data`.
+    """
+    if not is_dataclass(type(data)):
+        return data
+    keys = [f.name for f in iter_fields(data)]
+    data = {k: getattr(data, k) for k in keys}
+    if recursive:
+        data = {k: to_dict(v, recursive=True) for k, v in data.items()}
+    return data
+
+
+def from_omega(data_cls: Type[T], data: DictConfig) -> T:
+    """Instantiate a dataclass from an :mod:`omegaconf` config.
+
+    Arguments:
+        data_cls: A dataclass type.
+        data: A config object.
+
+    Returns:
+        A `data_cls` instance.
+    """
+    return from_dict(
+        data_cls,
+        OmegaConf.to_container(data, resolve=True, throw_on_missing=True),
+    )
+
+
+def to_omega(data: DataClass) -> DictConfig:
+    """Convert a dataclass instance to an :mod:`omegaconf` config.
+
+    Arguments:
+        data: A dataclass instance.
+
+    Returns:
+        A config representation of `data`.
+    """
+    return OmegaConf.create(to_dict(data, recursive=True))
+
+
+def from_yaml(data_cls: Type[T], data: str) -> T:
+    """Instantiate a dataclass from a YAML string.
+
+    Arguments:
+        data_cls: A dataclass type.
+        data: A YAML string.
+
+    Returns:
+        A `data_cls` instance.
+    """
+    return from_omega(data_cls, OmegaConf.create(data))
+
+
+def to_yaml(data: DataClass, sort_keys: bool = False) -> str:
+    """Serialize a dataclass instance to YAML.
+
+    Arguments:
+        data: A dataclass instance.
+        sort_keys: Sort mapping keys in YAML output when `True`.
+
+    Returns:
+        A YAML string representation of `data`.
+    """
+    return OmegaConf.to_yaml(to_omega(data), sort_keys=sort_keys)
+
+
+def from_dotlist(data_cls: Type[T], data: List[str]) -> T:
+    """Instantiate a dataclass from a list of dot-style strings.
+
+    Arguments:
+        data_cls: A dataclass type.
+        data: A list of dot-style strings.
+            For example, `["foo.bar=1", "foo.bis=[baz,qux]"]`.
+
+    Returns:
+        A `data_cls` instance.
+    """
+    return from_omega(data_cls, OmegaConf.from_dotlist(data))

heracls-0.1.0/heracls.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: heracls
+Version: 0.1.0
+Summary: Slayer of Hydra
+Author-email: François Rozet <francois.rozet@outlook.com>
+License-Expression: MIT
+Project-URL: documentation, https://github.com/francois-rozet/heracls
+Project-URL: source, https://github.com/francois-rozet/heracls
+Project-URL: tracker, https://github.com/francois-rozet/heracls/issues
+Keywords: config,dataclass
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dacite>=1.9.2
+Requires-Dist: omegaconf>=2.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: ruff==0.15.2; extra == "dev"
+Dynamic: license-file
+
+# Heracls - Slayer of Hydra
+
+`heracls` is a tiny utility package to instantiate typed dataclasses from flexible config sources (dictionary, OmegaConf, YAML, dotlist, ...). It is designed for projects that want strict, typed config objects while supporting the dynamic overrides commonly used in scripts and experiments.
+
+## Installation
+
+The `heracls` package is available on [PyPi](https://pypi.org/project/heracls) and can be installed with `pip`.
+
+```
+pip install heracls
+```
+
+Alternatively, if you need the latest features, you can install it from source.
+
+```
+pip install git+https://github.com/francois-rozet/heracls
+```
+
+## Getting started
+
+The following example demonstrates how to declare a nested dataclass config, instantiate it while overriding default fields with a dotlist, serialize it to YAML, and use its fields in a script.
+
+```python
+import heracls
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, Tuple, Union
+
+@dataclass
+class AdamConfig:
+    optimizer: Literal["adam", "adamw"] = "adam"
+    betas: Tuple[float, float] = (0.95, 0.95)
+    learning_rate: float = 1e-3
+    weight_decay: float = 0.0
+
+@dataclass
+class SGDConfig:
+    optimizer: Literal["sgd"] = "sgd"
+    momentum: float = 0.0
+    learning_rate: float = 1e-3
+    weight_decay: float = 0.0
+    nesterov: bool = False
+
+@dataclass
+class TrainConfig:
+    optim: Union[AdamConfig, SGDConfig] = field(default_factory=AdamConfig)
+    n_epochs: int = 1024
+    data_splits: Tuple[float, float] = (0.8, 0.1)
+    slurm: Dict[str, Any] = field(default_factory=dict)
+
+dotlist = [  # usually retrieved from the command line
+    "optim.optimizer=sgd",
+    "data_splits=[0.7,0.2]",
+    "slurm.account=frozet",
+]
+
+cfg = heracls.from_dotlist(TrainConfig, dotlist)
+
+with open("config.yaml", "w") as f:
+    f.write(heracls.to_yaml(cfg))
+
+trainset, validset, testset = load_dataset(cfg.data_splits)
+
+for epoch in range(cfg.n_epochs):
+    ...
+```
+
+The fields that are not specified in the dotlist are instantiated with their default value, as can be seen in the dumped `config.yaml` file.
+
+```yaml
+optim:
+  optimizer: sgd
+  momentum: 0.0
+  learning_rate: 0.001
+  weight_decay: 0.0
+  nesterov: false
+n_epochs: 1024
+data_splits:
+- 0.7
+- 0.2
+slurm:
+  account: frozet
+```

heracls-0.1.0/heracls.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+heracls/__init__.py
+heracls/patch.py
+heracls/transforms.py
+heracls.egg-info/PKG-INFO
+heracls.egg-info/SOURCES.txt
+heracls.egg-info/dependency_links.txt
+heracls.egg-info/requires.txt
+heracls.egg-info/top_level.txt
+tests/test_transforms.py

heracls-0.1.0/heracls.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

heracls-0.1.0/heracls.egg-info/requires.txt

@@ -0,0 +1,6 @@
+dacite>=1.9.2
+omegaconf>=2.3.0
+
+[dev]
+pytest>=8.3.5
+ruff==0.15.2

heracls-0.1.0/heracls.egg-info/top_level.txt

@@ -0,0 +1 @@
+heracls

heracls-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["setuptools>=61.0"]
+
+[project]
+name = "heracls"
+description = "Slayer of Hydra"
+authors = [
+  {name = "François Rozet", email = "francois.rozet@outlook.com"}
+]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "dacite>=1.9.2",
+    "omegaconf>=2.3.0",
+]
+dynamic = ["version"]
+keywords = ["config", "dataclass"]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.8"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.5",
+    "ruff==0.15.2",
+]
+
+[project.urls]
+documentation = "https://github.com/francois-rozet/heracls"
+source = "https://github.com/francois-rozet/heracls"
+tracker = "https://github.com/francois-rozet/heracls/issues"
+
+[tool.ruff]
+line-length = 99
+
+[tool.ruff.lint]
+extend-select = ["B", "I", "W"]
+ignore = ["FA100"]
+preview = true
+
+[tool.ruff.lint.isort]
+lines-between-types = 1
+relative-imports-order = "closest-to-furthest"
+section-order = ["future", "third-party", "first-party", "local-folder"]
+
+[tool.ruff.format]
+preview = true
+
+[tool.setuptools.dynamic]
+version = {attr = "heracls.__version__"}
+
+[tool.setuptools.packages.find]
+include = ["heracls*"]

heracls-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

heracls-0.1.0/tests/test_transforms.py

@@ -0,0 +1,43 @@
+"""Tests for the heracls.transforms module."""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, Tuple, Union
+
+from heracls.transforms import from_dotlist, from_yaml, to_yaml
+
+
+def test_dl_config():
+    @dataclass
+    class AdamConfig:
+        optimizer: Literal["adam", "adamw"] = "adam"
+        betas: Tuple[float, float] = (0.95, 0.95)
+        learning_rate: float = 1e-3
+        weight_decay: float = 0.0
+
+    @dataclass
+    class SGDConfig:
+        optimizer: Literal["sgd"] = "sgd"
+        momentum: float = 0.0
+        learning_rate: float = 1e-3
+        weight_decay: float = 0.0
+        nesterov: bool = False
+
+    @dataclass
+    class TrainConfig:
+        optim: Union[AdamConfig, SGDConfig] = field(default_factory=AdamConfig)
+        n_epochs: int = 1024
+        data_splits: Tuple[float, float] = (0.8, 0.1)
+        slurm: Dict[str, Any] = field(default_factory=dict)
+
+    dotlist = ["optim.optimizer=sgd", "data_splits=[0.7,0.2]", "slurm.account=frozet"]
+    cfg = from_dotlist(TrainConfig, dotlist)
+
+    assert cfg == TrainConfig(
+        optim=SGDConfig(),
+        data_splits=(0.7, 0.2),
+        slurm={"account": "frozet"},
+    )
+
+    dump = to_yaml(cfg)
+
+    assert from_yaml(TrainConfig, dump) == cfg