hydr8 0.1.0__tar.gz

hydr8-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv run --python ${{ matrix.python-version }} pytest tests/ -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hydr8
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

hydr8-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+.venv/

hydr8-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: hydr8
+Version: 0.1.0
+Summary: Decorator-based config injection for Hydra
+Requires-Python: >=3.8
+Requires-Dist: omegaconf>=2.1
+Description-Content-Type: text/markdown
+
+# hydr8
+
+Decorator-based config injection for [Hydra](https://hydra.cc/).
+
+hydr8 lets you push Hydra config (or any config as long as it's a dict) values into function parameters automatically, so your functions stay clean and testable without manually threading `cfg` everywhere.
+
+## Installation
+
+```bash
+pip install hydr8
+# or
+uv add hydr8
+```
+
+## Quick start
+
+```python
+import hydra
+from omegaconf import DictConfig
+import hydr8
+
+@hydr8.use("db")
+def connect(host: str, port: int):
+    print(f"Connecting to {host}:{port}")
+
+@hydra.main(config_path="conf", config_name="config", version_base=None)
+def main(cfg: DictConfig):
+    hydr8.init(cfg)
+    connect()  # host and port injected from cfg.db
+
+if __name__ == "__main__":
+    main()
+```
+
+With a config like:
+
+```yaml
+db:
+  host: localhost
+  port: 5432
+```
+
+## Usage
+
+`hydr8.use()` is the core function. It can be used as a **decorator** to inject config into function parameters, or called **directly** to access a config sub-tree as a dict.
+
+### As a decorator
+
+#### Explicit path
+
+Pass a dot-separated path to resolve a specific config node. Config keys are matched to function parameter names. Extra config keys that don't match any parameter are silently ignored.
+
+```python
+@hydr8.use("db.postgres")
+def connect(host: str, port: int, user: str):
+    ...
+
+connect()              # all three injected from cfg.db.postgres
+connect(host="remote") # host overridden, port and user from config
+```
+
+List indexing is supported:
+
+```python
+@hydr8.use("db.replicas[0]")
+def connect(host: str, port: int):
+    ...
+```
+
+#### Implicit path (auto-resolve)
+
+When no path is given, hydr8 derives it from the function's `__module__`. If the first segment of the module isn't a top-level config key, it's treated as the project name and stripped — so auto-resolve works whether you run with `python -m` or `python file.py`:
+
+```python
+# In myproject/data/loaders.py
+@hydr8.use()
+def build_loader(batch_size: int, shuffle: bool):
+    ...
+# Resolves to cfg.data.loaders
+```
+
+```yaml
+# config.yaml
+data:
+  loaders:
+    batch_size: 32
+    shuffle: true
+```
+
+By default, `scope="module"` — the path resolves to the module's config node, and config keys are matched to function parameters. Multiple functions in the same module share the same config node.
+
+With `scope="fn"`, the function's qualname is appended to the path:
+
+```python
+# In myproject/data/loaders.py
+@hydr8.use(scope="fn")
+def build_loader(batch_size: int, shuffle: bool):
+    ...
+# Resolves to cfg.data.loaders.build_loader
+```
+
+```yaml
+# config.yaml
+data:
+  loaders:
+    build_loader:
+      batch_size: 32
+      shuffle: true
+```
+
+This works with methods too:
+
+```python
+# In myproject/db/client.py
+class Client:
+    @hydr8.use(scope="fn")
+    def __init__(self, host: str, port: int):
+        self.host = host
+        self.port = port
+# Resolves to cfg.db.client.Client.__init__
+```
+
+#### `as_dict` mode
+
+Pass the entire resolved sub-config as a single dict argument instead of matching individual keys:
+
+```python
+@hydr8.use("db.postgres", as_dict="config")
+def connect(config: dict):
+    host = config["host"]
+    port = config["port"]
+    ...
+```
+
+#### Caller overrides
+
+Caller-provided arguments always take precedence over injected config. If every required parameter is supplied by the caller, config is never accessed at all:
+
+```python
+@hydr8.use("db")
+def connect(host: str, port: int):
+    ...
+
+connect(host="remote")       # port from config, host = "remote"
+connect("localhost", 5432)   # config not accessed
+```
+
+### As a direct call
+
+`hydr8.use("path")` returns a lazy, dict-like proxy. The config is resolved on first access, not at call time, so you can call `use()` before `init()`.
+
+```python
+import hydr8
+
+db = hydr8.use("db")
+
+hydr8.init(cfg)
+db["host"]        # "localhost"
+db["port"]        # 5432
+```
+
+This is useful when you want to read config values without decorating a function:
+
+```python
+def connect():
+    db = hydr8.use("db")
+    engine = create_engine(f"postgresql://{db['host']}:{db['port']}")
+    ...
+```
+
+An explicit path is required when using `use()` as a direct call. Calling `use()` without a path and accessing it raises `TypeError`, since there is no function to derive the path from.
+
+## Testing
+
+### Option A: Supply all arguments directly
+
+When every required parameter is provided by the caller, config injection is skipped entirely — no `init` needed:
+
+```python
+def test_connect():
+    assert connect("localhost", 5432) == expected
+```
+
+### Option B: `override` context manager
+
+Temporarily replace the global config for a test:
+
+```python
+from hydr8 import override
+
+def test_connect():
+    with override({"db": {"host": "test-host", "port": 9999}}):
+        result = connect()
+        assert result == expected
+```
+
+## API reference
+
+| Function | Description |
+|---|---|
+| `init(cfg)` | Store the config globally (accepts any dict or OmegaConf DictConfig) |
+| `get()` | Retrieve the stored config (raises `RuntimeError` if uninitialized) |
+| `override(overrides)` | Context manager that temporarily replaces the config |
+| `use(path, *, as_dict, scope)` | Decorator or direct config accessor for a config sub-tree |

hydr8-0.1.0/README.md

@@ -0,0 +1,204 @@
+# hydr8
+
+Decorator-based config injection for [Hydra](https://hydra.cc/).
+
+hydr8 lets you push Hydra config (or any config as long as it's a dict) values into function parameters automatically, so your functions stay clean and testable without manually threading `cfg` everywhere.
+
+## Installation
+
+```bash
+pip install hydr8
+# or
+uv add hydr8
+```
+
+## Quick start
+
+```python
+import hydra
+from omegaconf import DictConfig
+import hydr8
+
+@hydr8.use("db")
+def connect(host: str, port: int):
+    print(f"Connecting to {host}:{port}")
+
+@hydra.main(config_path="conf", config_name="config", version_base=None)
+def main(cfg: DictConfig):
+    hydr8.init(cfg)
+    connect()  # host and port injected from cfg.db
+
+if __name__ == "__main__":
+    main()
+```
+
+With a config like:
+
+```yaml
+db:
+  host: localhost
+  port: 5432
+```
+
+## Usage
+
+`hydr8.use()` is the core function. It can be used as a **decorator** to inject config into function parameters, or called **directly** to access a config sub-tree as a dict.
+
+### As a decorator
+
+#### Explicit path
+
+Pass a dot-separated path to resolve a specific config node. Config keys are matched to function parameter names. Extra config keys that don't match any parameter are silently ignored.
+
+```python
+@hydr8.use("db.postgres")
+def connect(host: str, port: int, user: str):
+    ...
+
+connect()              # all three injected from cfg.db.postgres
+connect(host="remote") # host overridden, port and user from config
+```
+
+List indexing is supported:
+
+```python
+@hydr8.use("db.replicas[0]")
+def connect(host: str, port: int):
+    ...
+```
+
+#### Implicit path (auto-resolve)
+
+When no path is given, hydr8 derives it from the function's `__module__`. If the first segment of the module isn't a top-level config key, it's treated as the project name and stripped — so auto-resolve works whether you run with `python -m` or `python file.py`:
+
+```python
+# In myproject/data/loaders.py
+@hydr8.use()
+def build_loader(batch_size: int, shuffle: bool):
+    ...
+# Resolves to cfg.data.loaders
+```
+
+```yaml
+# config.yaml
+data:
+  loaders:
+    batch_size: 32
+    shuffle: true
+```
+
+By default, `scope="module"` — the path resolves to the module's config node, and config keys are matched to function parameters. Multiple functions in the same module share the same config node.
+
+With `scope="fn"`, the function's qualname is appended to the path:
+
+```python
+# In myproject/data/loaders.py
+@hydr8.use(scope="fn")
+def build_loader(batch_size: int, shuffle: bool):
+    ...
+# Resolves to cfg.data.loaders.build_loader
+```
+
+```yaml
+# config.yaml
+data:
+  loaders:
+    build_loader:
+      batch_size: 32
+      shuffle: true
+```
+
+This works with methods too:
+
+```python
+# In myproject/db/client.py
+class Client:
+    @hydr8.use(scope="fn")
+    def __init__(self, host: str, port: int):
+        self.host = host
+        self.port = port
+# Resolves to cfg.db.client.Client.__init__
+```
+
+#### `as_dict` mode
+
+Pass the entire resolved sub-config as a single dict argument instead of matching individual keys:
+
+```python
+@hydr8.use("db.postgres", as_dict="config")
+def connect(config: dict):
+    host = config["host"]
+    port = config["port"]
+    ...
+```
+
+#### Caller overrides
+
+Caller-provided arguments always take precedence over injected config. If every required parameter is supplied by the caller, config is never accessed at all:
+
+```python
+@hydr8.use("db")
+def connect(host: str, port: int):
+    ...
+
+connect(host="remote")       # port from config, host = "remote"
+connect("localhost", 5432)   # config not accessed
+```
+
+### As a direct call
+
+`hydr8.use("path")` returns a lazy, dict-like proxy. The config is resolved on first access, not at call time, so you can call `use()` before `init()`.
+
+```python
+import hydr8
+
+db = hydr8.use("db")
+
+hydr8.init(cfg)
+db["host"]        # "localhost"
+db["port"]        # 5432
+```
+
+This is useful when you want to read config values without decorating a function:
+
+```python
+def connect():
+    db = hydr8.use("db")
+    engine = create_engine(f"postgresql://{db['host']}:{db['port']}")
+    ...
+```
+
+An explicit path is required when using `use()` as a direct call. Calling `use()` without a path and accessing it raises `TypeError`, since there is no function to derive the path from.
+
+## Testing
+
+### Option A: Supply all arguments directly
+
+When every required parameter is provided by the caller, config injection is skipped entirely — no `init` needed:
+
+```python
+def test_connect():
+    assert connect("localhost", 5432) == expected
+```
+
+### Option B: `override` context manager
+
+Temporarily replace the global config for a test:
+
+```python
+from hydr8 import override
+
+def test_connect():
+    with override({"db": {"host": "test-host", "port": 9999}}):
+        result = connect()
+        assert result == expected
+```
+
+## API reference
+
+| Function | Description |
+|---|---|
+| `init(cfg)` | Store the config globally (accepts any dict or OmegaConf DictConfig) |
+| `get()` | Retrieve the stored config (raises `RuntimeError` if uninitialized) |
+| `override(overrides)` | Context manager that temporarily replaces the config |
+| `use(path, *, as_dict, scope)` | Decorator or direct config accessor for a config sub-tree |

hydr8-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "hydr8"
+version = "0.1.0"
+description = "Decorator-based config injection for Hydra"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["omegaconf>=2.1"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = ["pytest"]

hydr8-0.1.0/src/hydr8/__init__.py

@@ -0,0 +1,4 @@
+from ._store import get, init, override
+from ._decorator import use
+
+__all__ = ["get", "init", "override", "use"]

hydr8-0.1.0/src/hydr8/_decorator.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Callable, Iterator, TypeVar
+
+from ._store import get
+from ._resolver import resolve, resolve_auto
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class _ConfigProxy:
+    """Returned by ``use()``. Acts as both a decorator and a lazy config dict."""
+
+    def __init__(self, path: str | None, as_dict: str | None, scope: str) -> None:
+        self._path = path
+        self._as_dict = as_dict
+        self._scope = scope
+        self._resolved: dict[str, Any] | None = None
+
+    def _resolve(self) -> dict[str, Any]:
+        if self._resolved is None:
+            cfg = get()
+            if self._path is None:
+                raise TypeError(
+                    "Cannot resolve config as a function without an explicit path. "
+                    "Pass a path to use(), e.g. use('db')."
+                )
+            self._resolved = resolve(cfg, self._path)
+        return self._resolved
+
+    # -- decorator mode --
+
+    def __call__(self, fn: F) -> F:
+        path = self._path
+        as_dict = self._as_dict
+        scope = self._scope
+        sig = inspect.signature(fn)
+        param_names = set(sig.parameters)
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            bound = sig.bind_partial(*args, **kwargs)
+            supplied = set(bound.arguments)
+
+            required = {
+                name
+                for name, p in sig.parameters.items()
+                if p.default is inspect.Parameter.empty
+                and p.kind
+                not in (
+                    inspect.Parameter.VAR_POSITIONAL,
+                    inspect.Parameter.VAR_KEYWORD,
+                )
+            }
+            if required <= supplied:
+                return fn(*args, **kwargs)
+
+            cfg = get()
+            if path is None:
+                resolved = resolve_auto(cfg, fn, scope)
+            else:
+                resolved = resolve(cfg, path)
+
+            if as_dict is not None:
+                if as_dict not in supplied:
+                    kwargs[as_dict] = resolved
+            else:
+                for key, value in resolved.items():
+                    if key in param_names and key not in supplied:
+                        kwargs[key] = value
+
+            return fn(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    # -- dict-like mode --
+
+    def __getitem__(self, key: str) -> Any:
+        return self._resolve()[key]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._resolve()
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._resolve())
+
+    def __len__(self) -> int:
+        return len(self._resolve())
+
+    def keys(self) -> Any:
+        return self._resolve().keys()
+
+    def values(self) -> Any:
+        return self._resolve().values()
+
+    def items(self) -> Any:
+        return self._resolve().items()
+
+    def __repr__(self) -> str:
+        try:
+            return repr(self._resolve())
+        except Exception:
+            return f"_ConfigProxy(path={self._path!r})"
+
+
+def use(
+    path: str | None = None,
+    *,
+    as_dict: str | None = None,
+    scope: str = "module",
+) -> _ConfigProxy:
+    """Access a config sub-tree — as a decorator or a function.
+
+    Returns a proxy that can be used in two ways:
+
+    **As a decorator** — injects config values into function parameters::
+
+        @use("db")
+        def connect(host: str, port: int):
+            ...
+
+        connect()              # host and port injected from cfg.db
+        connect(host="other")  # caller args take precedence
+
+    When ``path`` is ``None`` (the default), the config path is derived
+    automatically from the function's module path.  If the first segment
+    of ``__module__`` isn't a top-level config key it is treated as the
+    project name and stripped, so auto-resolve works whether you run with
+    ``python -m`` or ``python file.py``::
+
+        # In myproject/data/loaders.py
+        @use()
+        def build_loader(batch_size: int, shuffle: bool):
+            ...
+        # resolves to cfg.data.loaders (scope="module", the default)
+
+    With ``scope="fn"``, the function's ``__qualname__`` is appended::
+
+        @use(scope="fn")
+        def build_loader(batch_size: int, shuffle: bool):
+            ...
+        # resolves to cfg.data.loaders.build_loader
+
+    With ``as_dict``, the entire sub-config is passed as a single kwarg
+    instead of matching individual keys to parameters::
+
+        @use("db", as_dict="config")
+        def connect(config: dict):
+            host = config["host"]
+
+    **As a function** — returns a lazy, dict-like view of the config node.
+    Requires an explicit ``path``::
+
+        db = use("db")
+        db["host"]        # "localhost"
+        dict(db)          # {"host": "localhost", "port": 5432}
+        "host" in db      # True
+
+    The config is resolved lazily on first access, so ``use("db")`` can be
+    called before ``init()``.
+
+    Calling ``use()`` without a path and accessing it as a function raises
+    ``TypeError``, since there is no function to derive the path from.
+
+    Args:
+        path: Dot-separated config path (e.g. ``"db.postgres"``). When
+            ``None``, the path is derived from the decorated function's
+            module (decorator mode only).
+        as_dict: When set, the resolved sub-config is passed as a single
+            kwarg with this name (decorator mode only).
+        scope: Controls auto-resolve granularity (decorator mode only).
+            ``"module"`` (default) resolves to the module's config node.
+            ``"fn"`` appends the function's qualname.
+    """
+    return _ConfigProxy(path, as_dict, scope)

hydr8-0.1.0/src/hydr8/_resolver.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from omegaconf import DictConfig, OmegaConf
+
+
+def resolve(cfg: DictConfig, path: str) -> dict[str, Any]:
+    """Traverse *cfg* along the dot-separated *path* and return a plain dict.
+
+    Raises ``KeyError`` if any segment is missing.
+    """
+    node = OmegaConf.select(cfg, path, throw_on_missing=True)
+    if node is None:
+        raise KeyError(f"Config path {path!r} not found")
+    if not OmegaConf.is_dict(node):
+        raise TypeError(
+            f"Config path {path!r} resolved to a leaf value, not a mapping"
+        )
+    return OmegaConf.to_container(node, resolve=True)  # type: ignore[return-value]
+
+
+def resolve_auto(
+    cfg: DictConfig, fn: Callable[..., Any], scope: str = "module"
+) -> dict[str, Any]:
+    """Derive the config path from *fn*'s module (and optionally qualname), then resolve.
+
+    If the first segment of ``__module__`` is not a top-level key in *cfg*,
+    it is assumed to be the project/package name and is stripped.  This makes
+    auto-resolve work regardless of whether the code was invoked with
+    ``python -m`` (which includes the package prefix) or ``python file.py``
+    (which does not).
+
+    When *scope* is ``"module"`` (the default), only the module path is used::
+
+        myproject.data.loaders -> data.loaders
+
+    When *scope* is ``"fn"``, the function's ``__qualname__`` is appended::
+
+        myproject.data.loaders + build_loader -> data.loaders.build_loader
+    """
+    parts = fn.__module__.split(".")
+
+    # If the first segment isn't a top-level config key, it's the project
+    # name — strip it.
+    if len(parts) > 1 and parts[0] not in cfg:
+        parts = parts[1:]
+
+    if scope == "fn":
+        path = ".".join(parts) + "." + fn.__qualname__
+    else:
+        path = ".".join(parts)
+
+    return resolve(cfg, path)