omegakit 0.1.0__tar.gz

omegakit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Lindemann
+
+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.

omegakit-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: omegakit
+Version: 0.1.0
+Summary: Composable YAML configuration and Python object construction.
+Keywords: omegaconf,yaml,configuration,config,instantiation
+Author: Patrick Lindemann
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: omegaconf>=2.3,<2.4
+Requires-Dist: typing-extensions>=4.12
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/patrick-lindemann/omegakit
+Project-URL: Documentation, https://omegakit.readthedocs.io
+Project-URL: Source, https://github.com/patrick-lindemann/omegakit
+Project-URL: Changelog, https://github.com/patrick-lindemann/omegakit/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# omegakit
+
+Composable YAML configuration and Python object construction, powered by OmegaConf.
+Requires Python 3.12 or newer. The runtime dependencies are OmegaConf and
+typing_extensions.
+
+Install with `pip install omegakit`. omegakit builds on OmegaConf but is not affiliated
+with or endorsed by the OmegaConf project.
+
+```python
+from omegakit import instantiate, load_config
+
+config = load_config("app.yaml", overrides=["worker.timeout=30"])
+worker = instantiate(config.worker)
+```
+
+```yaml
+# defaults.yaml
+timeout: 10
+retries: 3
+```
+
+```yaml
+# app.yaml
+worker:
+  $base: ~import defaults.yaml
+  $class: myapp.Worker
+  timeout: 20
+```
+
+## Configuration syntax
+
+- `~import file.yaml` replaces a node with another file. Paths are relative to the
+  importing file; `~import file.yaml#worker` selects a subnode. Cycles are rejected.
+- `$base` merges a mapping or list of mappings underneath the current node. Later
+  bases win over earlier bases; the current node wins over all bases.
+- `$defaults` supplies defaults to dict-valued siblings. Item values win.
+- `$class` imports and calls a Python class or callable with the node's arguments.
+  Nested class nodes are instantiated recursively. A `from_config` method, if present,
+  receives the materialized argument mapping instead of constructor keyword arguments.
+- `$ref` imports an object without calling it. It is supported inside an instantiated
+  tree and cannot have sibling arguments (except `$meta`).
+- `$partial: true` returns a `functools.partial`; the value must be `true` or
+  `false`. `prepare(config)` also defers the top-level call; nested objects are still
+  built during preparation. Call-time arguments win over config arguments.
+- `$meta` is removed by default; `load_config(..., keep_meta=True)` preserves it.
+  Instantiation always ignores metadata. `keep_targets=False` removes construction keys.
+- Every `$`-prefixed key is reserved. Loading keeps unknown ones, but instantiating a
+  node with a `$` key that is not allowed there raises.
+
+Assembly runs imports, bases, and defaults, then applies overrides. Only structural
+references are resolved during assembly; other interpolations stay lazy and resolve
+against the assembled configuration. `???` can be filled by consumers and fails when
+accessed or instantiated if still missing. Overrides accept dictionaries, DictConfig,
+or OmegaConf `key=value` dotlists; they do not rerun structural assembly.
+
+Errors raised by a constructor or `from_config` keep their type and get a note naming
+the failing node. The complete rules are in the
+[configuration contracts](https://omegakit.readthedocs.io/en/latest/contracts.html).
+
+`Configurable` provides a default `from_config` implementation. `walk` traverses
+mapping nodes depth-first, parents before children. The optional `expected` argument
+to `instantiate` and `prepare` is a typing hint, not runtime validation: with it, the
+result is typed as that class, and without it as `Any`. `overrides` is keyword-only.
+
+## Optional resolvers
+
+Nothing is registered on import, and this library does not load `.env` files. Each
+resolver module carries its own dependencies, so `omegakit.resolvers` itself exports
+nothing; import from the module, such as `omegakit.resolvers.paths`.
+
+```python
+from pathlib import Path
+from omegakit.resolvers.paths import register_paths_resolver
+
+register_paths_resolver({"data_dir": Path("/srv/data")})
+# YAML: dataset: ${paths:data_dir}/training
+```
+
+Paths are copied as strings; relative paths remain relative and unknown keys return
+None. The caller defines the project layout.
+
+```python
+from omegakit.resolvers.torch import register_torch_resolvers
+
+register_torch_resolvers()
+# YAML: dtype: ${dtype:float32}
+# YAML: use_cuda: ${cuda_available:}
+```
+
+Install PyTorch separately for your platform before enabling these resolvers. It is
+not a package dependency. Importing the resolver module does not import Torch;
+registration without Torch raises an explanatory ImportError. Individual functions
+`register_torch_dtype_resolver` and `register_cuda_available_resolver` are available.
+
+Register resolvers before loading configs. Registration is global to OmegaConf and
+refuses existing names unless `replace=True` is supplied. Resolver results are cached
+per config; replacing a resolver does not clear caches on existing configs.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check
+uv run ruff format --check
+uv run pydoclint src
+uv run pyright
+uv run sphinx-build -W docs docs/_build
+uv build
+```
+
+Tests that require a real Torch installation skip when it is absent.
+
+This package imports and calls Python objects specified by configs, so configs must
+come from trusted sources. Assembly currently relies on private OmegaConf node APIs;
+the supported OmegaConf range is intentionally constrained to 2.3.x.

omegakit-0.1.0/README.md

@@ -0,0 +1,117 @@
+# omegakit
+
+Composable YAML configuration and Python object construction, powered by OmegaConf.
+Requires Python 3.12 or newer. The runtime dependencies are OmegaConf and
+typing_extensions.
+
+Install with `pip install omegakit`. omegakit builds on OmegaConf but is not affiliated
+with or endorsed by the OmegaConf project.
+
+```python
+from omegakit import instantiate, load_config
+
+config = load_config("app.yaml", overrides=["worker.timeout=30"])
+worker = instantiate(config.worker)
+```
+
+```yaml
+# defaults.yaml
+timeout: 10
+retries: 3
+```
+
+```yaml
+# app.yaml
+worker:
+  $base: ~import defaults.yaml
+  $class: myapp.Worker
+  timeout: 20
+```
+
+## Configuration syntax
+
+- `~import file.yaml` replaces a node with another file. Paths are relative to the
+  importing file; `~import file.yaml#worker` selects a subnode. Cycles are rejected.
+- `$base` merges a mapping or list of mappings underneath the current node. Later
+  bases win over earlier bases; the current node wins over all bases.
+- `$defaults` supplies defaults to dict-valued siblings. Item values win.
+- `$class` imports and calls a Python class or callable with the node's arguments.
+  Nested class nodes are instantiated recursively. A `from_config` method, if present,
+  receives the materialized argument mapping instead of constructor keyword arguments.
+- `$ref` imports an object without calling it. It is supported inside an instantiated
+  tree and cannot have sibling arguments (except `$meta`).
+- `$partial: true` returns a `functools.partial`; the value must be `true` or
+  `false`. `prepare(config)` also defers the top-level call; nested objects are still
+  built during preparation. Call-time arguments win over config arguments.
+- `$meta` is removed by default; `load_config(..., keep_meta=True)` preserves it.
+  Instantiation always ignores metadata. `keep_targets=False` removes construction keys.
+- Every `$`-prefixed key is reserved. Loading keeps unknown ones, but instantiating a
+  node with a `$` key that is not allowed there raises.
+
+Assembly runs imports, bases, and defaults, then applies overrides. Only structural
+references are resolved during assembly; other interpolations stay lazy and resolve
+against the assembled configuration. `???` can be filled by consumers and fails when
+accessed or instantiated if still missing. Overrides accept dictionaries, DictConfig,
+or OmegaConf `key=value` dotlists; they do not rerun structural assembly.
+
+Errors raised by a constructor or `from_config` keep their type and get a note naming
+the failing node. The complete rules are in the
+[configuration contracts](https://omegakit.readthedocs.io/en/latest/contracts.html).
+
+`Configurable` provides a default `from_config` implementation. `walk` traverses
+mapping nodes depth-first, parents before children. The optional `expected` argument
+to `instantiate` and `prepare` is a typing hint, not runtime validation: with it, the
+result is typed as that class, and without it as `Any`. `overrides` is keyword-only.
+
+## Optional resolvers
+
+Nothing is registered on import, and this library does not load `.env` files. Each
+resolver module carries its own dependencies, so `omegakit.resolvers` itself exports
+nothing; import from the module, such as `omegakit.resolvers.paths`.
+
+```python
+from pathlib import Path
+from omegakit.resolvers.paths import register_paths_resolver
+
+register_paths_resolver({"data_dir": Path("/srv/data")})
+# YAML: dataset: ${paths:data_dir}/training
+```
+
+Paths are copied as strings; relative paths remain relative and unknown keys return
+None. The caller defines the project layout.
+
+```python
+from omegakit.resolvers.torch import register_torch_resolvers
+
+register_torch_resolvers()
+# YAML: dtype: ${dtype:float32}
+# YAML: use_cuda: ${cuda_available:}
+```
+
+Install PyTorch separately for your platform before enabling these resolvers. It is
+not a package dependency. Importing the resolver module does not import Torch;
+registration without Torch raises an explanatory ImportError. Individual functions
+`register_torch_dtype_resolver` and `register_cuda_available_resolver` are available.
+
+Register resolvers before loading configs. Registration is global to OmegaConf and
+refuses existing names unless `replace=True` is supplied. Resolver results are cached
+per config; replacing a resolver does not clear caches on existing configs.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check
+uv run ruff format --check
+uv run pydoclint src
+uv run pyright
+uv run sphinx-build -W docs docs/_build
+uv build
+```
+
+Tests that require a real Torch installation skip when it is absent.
+
+This package imports and calls Python objects specified by configs, so configs must
+come from trusted sources. Assembly currently relies on private OmegaConf node APIs;
+the supported OmegaConf range is intentionally constrained to 2.3.x.

omegakit-0.1.0/pyproject.toml

@@ -0,0 +1,122 @@
+[project]
+name = "omegakit"
+version = "0.1.0"
+description = "Composable YAML configuration and Python object construction."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "omegaconf",
+    "yaml",
+    "configuration",
+    "config",
+    "instantiation",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "omegaconf>=2.3,<2.4",
+    "typing_extensions>=4.12",
+]
+
+[[project.authors]]
+name = "Patrick Lindemann"
+
+[project.urls]
+Homepage = "https://github.com/patrick-lindemann/omegakit"
+Documentation = "https://omegakit.readthedocs.io"
+Source = "https://github.com/patrick-lindemann/omegakit"
+Changelog = "https://github.com/patrick-lindemann/omegakit/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4,<9",
+    "pytest-cov>=7.1,<8",
+    "ruff>=0.14,<0.15",
+    "pyright>=1.1.414,<1.2",
+    "pydoclint>=0.9.1,<0.10",
+]
+docs = [
+    "furo>=2025.9",
+    "myst-parser>=4,<5",
+    "sphinx>=8.2,<9",
+    "sphinx-autodoc-typehints>=3,<4",
+]
+
+[tool.uv]
+default-groups = [
+    "dev",
+    "docs",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--import-mode=importlib"
+
+[tool.coverage.run]
+source = ["omegakit"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "B",
+    "UP",
+    "A",
+    "D",
+    "SIM",
+    "RUF",
+    "PT",
+    "TID",
+]
+ignore = [
+    "D100",
+    "D104",
+    "D105",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api."typing.TYPE_CHECKING"]
+msg = "Import at runtime; TYPE_CHECKING only when functionally necessary."
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+
+[tool.pydoclint]
+style = "google"
+arg-type-hints-in-docstring = false
+check-return-types = false
+check-yield-types = false
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"
+reportImplicitOverride = "error"
+reportUnnecessaryTypeIgnoreComment = "error"

omegakit-0.1.0/pyproject.toml.orig

@@ -0,0 +1,88 @@
+[project]
+name = "omegakit"
+version = "0.1.0"
+description = "Composable YAML configuration and Python object construction."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Patrick Lindemann" }]
+keywords = ["omegaconf", "yaml", "configuration", "config", "instantiation"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = ["omegaconf>=2.3,<2.4", "typing_extensions>=4.12"]
+
+[project.urls]
+Homepage = "https://github.com/patrick-lindemann/omegakit"
+Documentation = "https://omegakit.readthedocs.io"
+Source = "https://github.com/patrick-lindemann/omegakit"
+Changelog = "https://github.com/patrick-lindemann/omegakit/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4,<9",
+    "pytest-cov>=7.1,<8",
+    "ruff>=0.14,<0.15",
+    "pyright>=1.1.414,<1.2",
+    "pydoclint>=0.9.1,<0.10",
+]
+docs = [
+    "furo>=2025.9",
+    "myst-parser>=4,<5",
+    "sphinx>=8.2,<9",
+    "sphinx-autodoc-typehints>=3,<4",
+]
+
+[tool.uv]
+default-groups = ["dev", "docs"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--import-mode=importlib"
+
+[tool.coverage.run]
+source = ["omegakit"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP", "A", "D", "SIM", "RUF", "PT", "TID"]
+ignore = ["D100", "D104", "D105"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"typing.TYPE_CHECKING".msg = "Import at runtime; TYPE_CHECKING only when functionally necessary."
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+
+[tool.pydoclint]
+style = "google"
+arg-type-hints-in-docstring = false
+check-return-types = false
+check-yield-types = false
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.12"            # the floor; development runs on 3.13
+typeCheckingMode = "standard"
+reportImplicitOverride = "error"
+reportUnnecessaryTypeIgnoreComment = "error"

omegakit-0.1.0/src/omegakit/__init__.py

@@ -0,0 +1,28 @@
+from .configurable import Configurable
+from .instantiate import instantiate, prepare
+from .keys import (
+    BASE_KEY,
+    CLASS_KEY,
+    DEFAULTS_KEY,
+    IMPORT_KEY,
+    META_KEY,
+    PARTIAL_KEY,
+    REF_KEY,
+)
+from .loading import load_config
+from .utils import walk
+
+__all__ = [
+    "BASE_KEY",
+    "CLASS_KEY",
+    "DEFAULTS_KEY",
+    "IMPORT_KEY",
+    "META_KEY",
+    "PARTIAL_KEY",
+    "REF_KEY",
+    "Configurable",
+    "instantiate",
+    "load_config",
+    "prepare",
+    "walk",
+]

omegakit-0.1.0/src/omegakit/assembly.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any, cast
+
+from omegaconf import DictConfig, ListConfig, Node, OmegaConf
+
+from .keys import BASE_KEY, DEFAULTS_KEY, IMPORT_KEY
+from .utils import walk
+
+
+def resolve_imports(
+    config: DictConfig | ListConfig,
+    config_path: Path,
+    visited_paths: set[Path],
+    cache: dict[Path, DictConfig | ListConfig],
+) -> None:
+    """Replace every `~import` value in `config` in place, depth-first.
+
+    Args:
+        config: The config to process.
+        config_path: The file `config` was loaded from; relative imports resolve
+            against its directory.
+        visited_paths: The files in the current import chain, for cycle detection.
+        cache: Imported files already loaded during this `load_config` call.
+    """
+    if isinstance(config, ListConfig):
+        for index in range(len(config)):
+            node = config._get_node(index)
+            if isinstance(node, (DictConfig, ListConfig)):
+                resolve_imports(node, config_path, visited_paths, cache)
+            else:
+                value = node._value() if isinstance(node, Node) else None
+                if isinstance(value, str) and value.startswith(IMPORT_KEY):
+                    config[index] = _import_node(
+                        config[index], config_path, visited_paths, cache
+                    )
+        return
+    for key, value in config.items_ex(resolve=False):
+        if isinstance(value, (DictConfig, ListConfig)):
+            resolve_imports(value, config_path, visited_paths, cache)
+        elif isinstance(value, str) and value.startswith(IMPORT_KEY):
+            config[key] = _import_node(config[key], config_path, visited_paths, cache)
+
+
+def _import_node(
+    statement: str,
+    config_path: Path,
+    visited_paths: set[Path],
+    cache: dict[Path, DictConfig | ListConfig],
+) -> Any:
+    # Match the pattern ~import <file_path>[#<node_path>]
+    args = statement[len(IMPORT_KEY) :].strip().split("#")
+    if len(args) > 2:
+        raise ValueError(
+            f"Import `{statement}` contains more than one `#`. Use `#` only to "
+            "separate the file path from the node path."
+        )
+    file_path = Path(args[0])
+    if not file_path.is_absolute():
+        file_path = Path(config_path.parent, file_path)
+    file_path = file_path.resolve()
+    node_path = args[1].strip() if len(args) > 1 else ""
+    # Load the imported config file and resolve its own imports first
+    if file_path in visited_paths:
+        raise ValueError(
+            f"Circular import detected: `{file_path}` was already imported."
+        )
+    if file_path in cache:
+        imported_config = cache[file_path]
+    else:
+        imported_config = OmegaConf.load(file_path)
+        resolve_imports(
+            imported_config,
+            file_path,
+            visited_paths={*visited_paths, file_path},
+            cache=cache,
+        )
+        cache[file_path] = imported_config
+    node = imported_config
+    for part in filter(None, node_path.split(".")):
+        if isinstance(node, DictConfig):
+            node = node._get_node(part)
+        elif (
+            isinstance(node, ListConfig)
+            and part.lstrip("-").isdigit()
+            and -len(node) <= int(part) < len(node)
+        ):
+            node = node._get_node(int(part))
+        else:
+            node = None
+        if node is None:
+            break
+    if node is None:
+        raise ValueError(
+            f"Import `{statement}` selects node `{node_path}`, which does not exist in "
+            f"`{file_path}`."
+        )
+    return node
+
+
+def merge_base_recursive(config: DictConfig | ListConfig) -> None:
+    """Merge every `$base` underneath its node in place, children before parents.
+
+    Args:
+        config: The config to process.
+
+    Raises:
+        ValueError: If a `$base` is not a mapping or a list of mappings.
+    """
+    for node in _walk_post_order(config):
+        if node._get_node(BASE_KEY) is None:
+            continue
+        base = node[BASE_KEY]
+        # A base may be a single mapping or a list of mappings. Later list elements
+        # take precedence over earlier ones, and the node's own keys over all.
+        if isinstance(base, ListConfig):
+            bases = [base[index] for index in range(len(base))]
+            if not all(isinstance(item, DictConfig) for item in bases):
+                raise ValueError(
+                    f"List-valued `{BASE_KEY}` in parent `{node}` must contain only "
+                    f"dictionaries."
+                )
+        elif isinstance(base, DictConfig):
+            bases = [base]
+        else:
+            raise ValueError(
+                f"Node `{BASE_KEY}` in parent `{node}` is not a dictionary or a list "
+                f"of dictionaries."
+            )
+        node.pop(BASE_KEY)
+        merged_config = cast(DictConfig, OmegaConf.merge(*bases, node))
+        for key in list(merged_config.keys()):
+            node[key] = merged_config._get_node(key)
+
+
+def resolve_defaults_recursive(config: DictConfig | ListConfig) -> None:
+    """Merge every `$defaults` under its dict-valued siblings in place.
+
+    Nested mappings are processed before their parents.
+
+    Args:
+        config: The config to process.
+
+    Raises:
+        ValueError: If a `$defaults` is not a mapping.
+    """
+    for node in _walk_post_order(config):
+        if node._get_node(DEFAULTS_KEY) is None:
+            continue
+        defaults = node[DEFAULTS_KEY]
+        if not isinstance(defaults, DictConfig):
+            raise ValueError(
+                f"Node `{DEFAULTS_KEY}` in parent `{node}` is not a dictionary."
+            )
+        node.pop(DEFAULTS_KEY)
+        for key in list(node.keys()):
+            if str(key).startswith("$"):
+                continue
+            item = node._get_node(key)
+            if isinstance(item, DictConfig):
+                node[key] = OmegaConf.merge(defaults, item)
+
+
+def exclude_keys_recursive(config: DictConfig | ListConfig, exclude: set[str]) -> None:
+    """Remove the given keys from every mapping in `config`, in place.
+
+    Args:
+        config: The config to process.
+        exclude: The keys to remove.
+    """
+    for node in walk(config):
+        for key in list(node.keys()):
+            if key in exclude:
+                node.pop(key)
+
+
+def _walk_post_order(config: DictConfig | ListConfig) -> Iterator[DictConfig]:
+    # Like `walk`, but children before parents, so a pass sees assembled children.
+    if isinstance(config, DictConfig):
+        children = [node for _, node in config.items_ex(resolve=False)]
+    else:
+        children = [config._get_node(index) for index in range(len(config))]
+    for node in children:
+        if isinstance(node, (DictConfig, ListConfig)):
+            yield from _walk_post_order(node)
+    if isinstance(config, DictConfig):
+        yield config

omegakit-0.1.0/src/omegakit/configurable.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Generic
+
+from omegaconf import DictConfig
+from typing_extensions import TypeVar
+
+TConfig = TypeVar("TConfig", bound=Mapping[str, Any], default=DictConfig)
+
+
+class Configurable(Generic[TConfig]):
+    """A class that can be instantiated from a config."""
+
+    @classmethod
+    def from_config(
+        cls, config: TConfig | DictConfig | dict[str, Any], **kwargs
+    ) -> Any:
+        """Create an instance from a materialized config.
+
+        Args:
+            config: The constructor arguments, keyed by parameter name.
+            **kwargs: Call-time arguments from a partial. They win over `config`
+                arguments of the same name.
+
+        Returns:
+            The created instance.
+        """
+        return cls(**dict(config, **kwargs))

omegakit-0.1.0/src/omegakit/instantiate.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any, cast, overload
+
+from omegaconf import DictConfig, ListConfig, OmegaConf
+
+from .keys import CLASS_KEY, META_KEY, PARTIAL_KEY, REF_KEY
+from .loading import cast_overrides
+from .utils import import_object
+
+
+@overload
+def instantiate(
+    config: DictConfig | dict[str, Any],
+    *,
+    overrides: DictConfig | dict[str, Any] | list[str] | None = None,
+) -> Any: ...
+
+
+@overload
+def instantiate[T](
+    config: DictConfig | dict[str, Any],
+    expected: type[T],
+    *,
+    overrides: DictConfig | dict[str, Any] | list[str] | None = None,
+) -> T: ...
+
+
+def instantiate(
+    config: DictConfig | dict[str, Any],
+    expected: type[Any] | None = None,
+    *,
+    overrides: DictConfig | dict[str, Any] | list[str] | None = None,
+) -> Any:
+    """Instantiate an object from a configuration.
+
+    Args:
+        config: The configuration.
+        expected: The expected type of the instantiated object. It is a static typing
+            hint only and is not checked at runtime. Defaults to `None`.
+        overrides: Additional argument overrides. Can be provided as a DictConfig, a
+            regular dictionary, or a list of `key=value` strings (e.g.
+            `["foo=1.0", "bar=baz"]`). Defaults to `None`.
+
+    Returns:
+        The instantiated object.
+    """
+    return _instantiate(config, overrides)
+
+
+@overload
+def prepare(
+    config: DictConfig | dict[str, Any],
+    *,
+    overrides: DictConfig | dict[str, Any] | list[str] | None = None,
+) -> functools.partial[Any]: ...
+
+
+@overload
+def prepare[T](
+    config: DictConfig | dict[str, Any],
+    expected: type[T],
+    *,
+    overrides: DictConfig | dict[str, Any] | list[str] | None = None,
+) -> functools.partial[T]: ...
+
+
+def prepare(
+    config: DictConfig | dict[str, Any],
+    expected: type[Any] | None = None,
+    *,
+    overrides: DictConfig | dict[str, Any] | list[str] | None = None,
+) -> functools.partial[Any]:
+    """Prepare an object for instantiation from a configuration.
+
+    The resulting function can be called later to perform the actual instantiation with
+    extra arguments.
+
+    Args:
+        config: The configuration.
+        expected: The expected type of the instantiated object. It is a static typing
+            hint only and is not checked at runtime. Defaults to `None`.
+        overrides: Additional argument overrides. Can be provided as a DictConfig, a
+            regular dictionary, or a list of `key=value` strings (e.g.
+            `["foo=1.0", "bar=baz"]`). Defaults to `None`.
+
+    Returns:
+        The instantiating function.
+    """
+    return _instantiate(config, overrides, wrap=functools.partial)
+
+
+def _instantiate(
+    config: DictConfig | dict[str, Any],
+    overrides: DictConfig | dict[str, Any] | list[str] | None = None,
+    wrap: Callable | None = None,
+) -> Any:
+    if CLASS_KEY not in config:
+        raise ValueError(
+            f"Cannot instantiate config with no `{CLASS_KEY}` key:"
+            f"\n{OmegaConf.to_yaml(config)}"
+        )
+    if not isinstance(config, DictConfig):
+        config = OmegaConf.create(config)
+    if overrides is not None:
+        config = config.copy()
+        overrides = cast_overrides(overrides)
+        config.merge_with(overrides)
+    plain_config = cast(
+        dict[str, Any],
+        OmegaConf.to_container(config, resolve=True, throw_on_missing=True),
+    )
+    return _build(plain_config, wrap)
+
+
+def _build(
+    plain_config: dict[str, Any],
+    wrap: Callable | None = None,
+    path: tuple[str | int, ...] = (),
+) -> Any:
+    cls = import_object(plain_config[CLASS_KEY])
+    # Recursively materialize the nested config: Instantiating all children containing
+    # the class key
+    kwargs = {}
+    for key, value in plain_config.items():
+        if key in (CLASS_KEY, META_KEY):
+            continue
+        if isinstance(key, str) and key.startswith("$") and key != PARTIAL_KEY:
+            raise ValueError(
+                f"Invalid config node with `{CLASS_KEY}` key: {plain_config}. Key "
+                f"`{key}` is not supported here; keys starting with `$` are reserved."
+            )
+        if key == PARTIAL_KEY:
+            if not isinstance(value, bool):
+                raise ValueError(
+                    f"`{PARTIAL_KEY}` must be `true` or `false`, got `{value!r}`."
+                )
+            if value:
+                wrap = functools.partial
+            continue
+        kwargs[key] = _materialize(value, (*path, key))
+    # Final instantiation
+    try:
+        if hasattr(cls, "from_config"):
+            return (
+                wrap(cls.from_config, kwargs)
+                if wrap is not None
+                else cls.from_config(kwargs)
+            )
+        return wrap(cls, **kwargs) if wrap is not None else cls(**kwargs)
+    except Exception as error:
+        location = ".".join(map(str, path)) or "<root>"
+        error.add_note(f"while instantiating {location} ({plain_config[CLASS_KEY]})")
+        raise
+
+
+def _materialize(node: Any, path: tuple[str | int, ...]) -> Any:
+    if isinstance(node, (dict, DictConfig)):
+        node = {k: v for k, v in node.items() if k != META_KEY}
+        if CLASS_KEY in node:
+            return _build(node, path=path)
+        if REF_KEY in node:
+            if len(node) > 1:
+                raise ValueError(
+                    f"Invalid config node with `{REF_KEY}` key: {node}. A node using "
+                    f"`{REF_KEY}` cannot contain any other keys."
+                )
+            return import_object(node[REF_KEY])
+        for key in node:
+            if isinstance(key, str) and key.startswith("$"):
+                raise ValueError(
+                    f"Invalid config node: {node}. Key `{key}` is not supported here; "
+                    "keys starting with `$` are reserved."
+                )
+        return {k: _materialize(v, (*path, k)) for k, v in node.items()}
+    if isinstance(node, (list, ListConfig)):
+        return [_materialize(v, (*path, index)) for index, v in enumerate(node)]
+    return node

omegakit-0.1.0/src/omegakit/keys.py

@@ -0,0 +1,73 @@
+META_KEY = "$meta"
+"""Arbitrary metadata attached to any node.
+
+For example `$meta: {author: myname}`. Preserved on load only when
+`load_config(..., keep_meta=True)`, and always ignored by `instantiate` (never passed
+to a constructor).
+"""
+
+IMPORT_KEY = "~import"
+"""String value replacing a node with another config file, `~import <path>[#<node>]`.
+
+A relative path is resolved against the importing file, an absolute path is used as-is;
+the optional `#<node>` selects a subnode of the imported config (e.g. `~import
+models/base.yaml#optimizer`). Circular imports raise a `ValueError`.
+
+The statement may contain `${...}` interpolations (e.g. `~import
+${paths:config_dir}/models/base.yaml`). Being part of the reference itself, they are
+resolved eagerly at assembly time — per file, before any `$base` merge — so resolvers
+are always available, but config-value references only see keys literally present in
+the importing file at that point.
+"""
+
+BASE_KEY = "$base"
+"""Defaults merged into the current node.
+
+For example `$base: {lr: 0.1, steps: 100}`. The `$base` mapping is merged underneath
+the node (the node's own keys win) before instantiation. Bases are merged bottom-up,
+so nested nodes resolve their own `$base` first. Typically populated via `~import` or
+an interpolation (`$base: ${..._common}`).
+
+Resolution contract: assembly (`~import` + `$base` merge) is structural and resolves
+nothing except the `$base`/`~import` reference itself (it decides what to merge).
+Every `${...}` interpolation and `???` mandatory-missing value is carried through
+untouched and resolved once, later — lazily on access, or when `instantiate` builds the
+object tree — against the fully-assembled config. So a `???` means "a `$base` consumer
+must supply this key"; unfilled, it errors at use time (naming the key), never during
+assembly.
+"""
+
+DEFAULTS_KEY = "$defaults"
+"""Defaults merged underneath every dict-valued sibling of the containing mapping.
+
+Scalar and list-valued siblings and `$`-keys are untouched. Item keys win, and passes
+run bottom-up, so an inner `$defaults` wins over an outer one.
+
+Follows the `$base` resolution contract: only the `$defaults` reference itself is
+resolved eagerly; every `${...}` inside the values is carried through and resolved
+lazily at the item's final position — relative interpolations (`${.id}`) are written
+as-if already inside an item, absolute ones resolve from the config root.
+"""
+
+CLASS_KEY = "$class"
+"""Import path of the class to build from a node.
+
+For example `$class: myapp.models.Foo`. Its presence marks a node as instantiable:
+`instantiate` imports the class and calls it (or its `from_config`) with the node's
+other keys as keyword arguments.
+"""
+
+REF_KEY = "$ref"
+"""Import path resolved to the referenced object itself.
+
+For example `$ref: torch.float32`. Unlike `$class` the object is imported but not
+called. A `$ref` node must contain no other keys (`$meta` aside).
+"""
+
+PARTIAL_KEY = "$partial"
+"""Flag deferring instantiation of a `$class` node.
+
+For example `$partial: true`. When true, `instantiate` returns a `functools.partial`
+bound to the resolved arguments instead of the constructed object, so remaining
+arguments can be supplied at call time.
+"""

omegakit-0.1.0/src/omegakit/loading.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+from omegaconf import DictConfig, ListConfig, OmegaConf
+
+from .assembly import (
+    exclude_keys_recursive,
+    merge_base_recursive,
+    resolve_defaults_recursive,
+    resolve_imports,
+)
+from .keys import CLASS_KEY, META_KEY, PARTIAL_KEY, REF_KEY
+
+type PathLike = Path | str
+
+
+def load_config(
+    file_path: PathLike,
+    *,
+    overrides: DictConfig | dict[str, Any] | list[str] | None = None,
+    keep_targets: bool = True,
+    keep_meta: bool = False,
+) -> DictConfig:
+    """Load a YAML configuration file from a given file path.
+
+    Args:
+        file_path: The path to the configuration file.
+        overrides: Additional configuration overrides. Can be provided as a
+            DictConfig, a regular dictionary, or a list of `key=value` strings (e.g.
+            `["foo=1.0", "bar=baz"]`). Defaults to `None`.
+        keep_targets: Whether to keep target fields needed for instantiation in the
+            parsed config. Defaults to `True`.
+        keep_meta: Whether to keep metadata fields in the parsed config. Defaults to
+            `False`.
+
+    Returns:
+        The parsed configuration.
+    """
+    file_path = Path(file_path).resolve()
+    config = cast(DictConfig, OmegaConf.load(file_path))
+    resolve_imports(config, file_path, visited_paths={file_path}, cache={})
+    merge_base_recursive(config)
+    resolve_defaults_recursive(config)
+    if overrides is not None:
+        overrides = cast_overrides(overrides)
+        config.merge_with(overrides)
+    if keep_meta and keep_targets:
+        return config
+    exclude_keys = set()
+    if not keep_meta:
+        exclude_keys.add(META_KEY)
+    if not keep_targets:
+        exclude_keys.add(REF_KEY)
+        exclude_keys.add(CLASS_KEY)
+        exclude_keys.add(PARTIAL_KEY)
+    exclude_keys_recursive(config, exclude_keys)
+    return config
+
+
+def cast_overrides(
+    overrides: DictConfig | dict[str, Any] | list[str],
+) -> DictConfig:
+    """Convert overrides into a `DictConfig`.
+
+    Args:
+        overrides: A `DictConfig`, a dictionary, or a list of `key=value` strings.
+
+    Returns:
+        The overrides as a `DictConfig`.
+
+    Raises:
+        ValueError: If `overrides` has another type.
+    """
+    if isinstance(overrides, (DictConfig, ListConfig)):
+        return cast(DictConfig, overrides)
+    elif isinstance(overrides, dict):
+        return OmegaConf.create(overrides)
+    elif isinstance(overrides, list):
+        return OmegaConf.from_dotlist(overrides)
+    raise ValueError(
+        f"Unsupported overrides type: {type(overrides)}. Expected `Config`, `dict` "
+        "or `list` of `key=value` string pairs."
+    )

omegakit-0.1.0/src/omegakit/resolvers/paths.py

@@ -0,0 +1,18 @@
+from collections.abc import Mapping
+from pathlib import Path
+
+from omegaconf import OmegaConf
+
+
+def register_paths_resolver(
+    paths: Mapping[str, str | Path], *, replace: bool = False
+) -> None:
+    """Register `${paths:key}` using a snapshot of caller-provided paths.
+
+    Values are converted to strings without resolving them. Unknown keys return None,
+    matching the original resolver. Registration is global to OmegaConf.
+    """
+    values = {key: str(value) for key, value in paths.items()}
+    OmegaConf.register_new_resolver(
+        "paths", values.get, replace=replace, use_cache=True
+    )

omegakit-0.1.0/src/omegakit/resolvers/torch.py

@@ -0,0 +1,57 @@
+"""Optional Torch resolvers. Torch is needed only when registering or resolving."""
+
+import importlib
+from typing import Any
+
+from omegaconf import OmegaConf
+
+
+def _require_torch() -> Any:
+    try:
+        torch = importlib.import_module("torch")
+    except ModuleNotFoundError as error:
+        if error.name != "torch":
+            raise
+        raise ImportError(
+            "Torch resolvers require PyTorch. Install torch for your platform "
+            "before calling register_torch_resolvers()."
+        ) from error
+    return torch
+
+
+def _resolve_dtype(dtype_str: str) -> Any:
+    torch = _require_torch()
+    dtype = getattr(torch, dtype_str, None)
+    if not isinstance(dtype, torch.dtype):
+        raise ValueError(f"Invalid torch dtype: {dtype_str}")
+    return dtype
+
+
+def register_torch_dtype_resolver(*, replace: bool = False) -> None:
+    """Register `${dtype:float32}`; require an existing Torch installation."""
+    _require_torch()
+    OmegaConf.register_new_resolver(
+        "dtype", _resolve_dtype, replace=replace, use_cache=True
+    )
+
+
+def register_cuda_available_resolver(*, replace: bool = False) -> None:
+    """Register `${cuda_available:}`; require an existing Torch installation."""
+    torch = _require_torch()
+    OmegaConf.register_new_resolver(
+        "cuda_available",
+        lambda _=None: torch.cuda.is_available(),
+        replace=replace,
+        use_cache=True,
+    )
+
+
+def register_torch_resolvers(*, replace: bool = False) -> None:
+    """Register both Torch resolvers, without overwriting names by default."""
+    _require_torch()
+    if not replace:
+        for name in ("dtype", "cuda_available"):
+            if OmegaConf.has_resolver(name):
+                raise ValueError(f"Resolver '{name}' is already registered")
+    register_torch_dtype_resolver(replace=replace)
+    register_cuda_available_resolver(replace=replace)

omegakit-0.1.0/src/omegakit/utils.py

@@ -0,0 +1,48 @@
+import importlib
+from collections.abc import Iterator
+from typing import Any
+
+from omegaconf import DictConfig, ListConfig
+
+
+def walk(config: DictConfig | ListConfig) -> Iterator[DictConfig]:
+    """Walk along every mapping node in `config` depth-first.
+
+    Args:
+        config: The config to traverse.
+
+    Yields:
+        Each mapping node, parents before children.
+    """
+    if isinstance(config, DictConfig):
+        yield config
+        children = [node for _, node in config.items_ex(resolve=False)]
+    else:
+        children = [config._get_node(index) for index in range(len(config))]
+    for node in children:
+        if isinstance(node, (DictConfig, ListConfig)):
+            yield from walk(node)
+
+
+def import_object(import_path: str) -> Any:
+    """Import an object by its dotted path, such as `package.module.Name`.
+
+    Args:
+        import_path: The module path and attribute name, separated by a dot.
+
+    Returns:
+        The imported object.
+
+    Raises:
+        ImportError: If the module has no attribute of that name.
+    """
+    module_path, _, attr_name = import_path.rpartition(".")
+    module = importlib.import_module(module_path)
+    try:
+        return getattr(module, attr_name)
+    except AttributeError as error:
+        raise ImportError(
+            f"Could not import `{attr_name}` from module `{module_path}`. Make sure "
+            "the import name is correct, and that dependencies are installed, if "
+            "necessary."
+        ) from error