hydraflow 0.7.3__tar.gz → 0.7.5__tar.gz

hydraflow-0.7.5/.github/workflows/ci.yaml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: test-${{ github.head_ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHONUNBUFFERED: "1"
+  FORCE_COLOR: "1"
+
+jobs:
+  run:
+    name: Python ${{ matrix.python-version }} on ${{ startsWith(matrix.os, 'macos-') && 'macOS' || startsWith(matrix.os, 'windows-') && 'Windows' || 'Linux' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - name: Install uv and ruff
+        run: pip install uv ruff
+      - name: Install the project
+        run: uv sync
+      - name: Ruff check
+        run: ruff check
+      - name: Run test
+        run: uv run pytest -v --junitxml=junit.xml
+      - name: Upload Codecov Results
+        if: success()
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: lcov.info
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/test-results-action@v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

hydraflow-0.7.5/.github/workflows/docs.yaml

@@ -0,0 +1,25 @@
+name: Documentation
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+permissions:
+  contents: write
+jobs:
+  deploy:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+      - name: Install package
+        run: pip install -e . mkapi markdown-exec[ansi]
+      - name: Deploy documentation
+        run: mkdocs gh-deploy --force

{hydraflow-0.7.3 → hydraflow-0.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hydraflow
-Version: 0.7.3
+Version: 0.7.5
 Summary: Hydraflow integrates Hydra and MLflow to manage and track machine learning experiments.
 Project-URL: Documentation, https://daizutabi.github.io/hydraflow/
 Project-URL: Source, https://github.com/daizutabi/hydraflow
@@ -38,6 +38,9 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: hydra-core>=1.3
 Requires-Dist: mlflow>=2.15
+Requires-Dist: omegaconf
+Requires-Dist: rich
+Requires-Dist: typer
 Description-Content-Type: text/markdown
 
 # Hydraflow
@@ -52,7 +55,7 @@ Description-Content-Type: text/markdown
 [pypi-v-link]: https://pypi.org/project/hydraflow/
 [python-v-image]: https://img.shields.io/pypi/pyversions/hydraflow.svg
 [python-v-link]: https://pypi.org/project/hydraflow
-[GHAction-image]: https://github.com/daizutabi/hydraflow/actions/workflows/ci.yml/badge.svg?branch=main&event=push
+[GHAction-image]: https://github.com/daizutabi/hydraflow/actions/workflows/ci.yaml/badge.svg?branch=main&event=push
 [GHAction-link]: https://github.com/daizutabi/hydraflow/actions?query=event%3Apush+branch%3Amain
 [codecov-image]: https://codecov.io/github/daizutabi/hydraflow/coverage.svg?branch=main
 [codecov-link]: https://codecov.io/github/daizutabi/hydraflow?branch=main

{hydraflow-0.7.3 → hydraflow-0.7.5}/README.md

@@ -10,7 +10,7 @@
 [pypi-v-link]: https://pypi.org/project/hydraflow/
 [python-v-image]: https://img.shields.io/pypi/pyversions/hydraflow.svg
 [python-v-link]: https://pypi.org/project/hydraflow
-[GHAction-image]: https://github.com/daizutabi/hydraflow/actions/workflows/ci.yml/badge.svg?branch=main&event=push
+[GHAction-image]: https://github.com/daizutabi/hydraflow/actions/workflows/ci.yaml/badge.svg?branch=main&event=push
 [GHAction-link]: https://github.com/daizutabi/hydraflow/actions?query=event%3Apush+branch%3Amain
 [codecov-image]: https://codecov.io/github/daizutabi/hydraflow/coverage.svg?branch=main
 [codecov-link]: https://codecov.io/github/daizutabi/hydraflow?branch=main

hydraflow-0.7.5/docs/index.md

@@ -0,0 +1,10 @@
+# Hydraflow Documentation
+
+Hydraflow integrates [Hydra](https://hydra.cc/) and [MLflow](https://mlflow.org/)
+to manage and track machine learning experiments.
+
+## Installation
+
+```bash
+pip install hydraflow
+```

hydraflow-0.7.5/docs/usage/quickstart.md

@@ -0,0 +1,150 @@
+# Quickstart
+
+## Hydra application
+
+The following example demonstrates how to use Hydraflow with a Hydra application.
+There are two main steps to using Hydraflow:
+
+1. Set the MLflow experiment using the Hydra job name.
+2. Start a new MLflow run that logs the Hydra configuration.
+
+```python title="apps/quickstart.py" linenums="1" hl_lines="24 26"
+--8<-- "apps/quickstart.py"
+```
+
+### Set the MLflow experiment
+
+[`hydraflow.set_experiment`][] sets the MLflow experiment using the Hydra job name.
+Optionally, it can also set the tracking URI with `uri` argument.
+For example,
+
+```python
+hydraflow.set_experiment(uri="sqlite:///mlruns.db")
+```
+
+### Start a new MLflow run
+
+[`hydraflow.start_run`][] starts a new MLflow run that logs the Hydra configuration.
+It returns the started run so that it can be used to log metrics, parameters, and artifacts
+within the context of the run.
+
+```python
+with hydraflow.start_run(cfg) as run:
+    pass
+```
+
+## Run the application
+
+```bash exec="on"
+rm -rf mlruns outputs multirun
+```
+
+### Single-run
+
+Run the Hydra application as a normal Python script.
+
+```console exec="1" source="console"
+$ python apps/quickstart.py
+```
+
+Check the MLflow CLI to view the experiment.
+
+```console exec="1" source="console"
+$ mlflow experiments search
+```
+
+### Multi-run
+
+```console exec="1" source="console"
+$ python apps/quickstart.py -m width=400,600 height=100,200,300
+```
+
+## Use Hydraflow API
+
+### Run collection
+
+```pycon exec="1" source="console" session="quickstart"
+>>> import mlflow
+>>> mlflow.set_experiment("quickstart")
+>>> import hydraflow
+>>> rc = hydraflow.list_runs()
+>>> print(rc)
+```
+
+### Retrieve a run
+
+```pycon exec="1" source="console" session="quickstart"
+>>> run = rc.first()
+>>> print(type(run))
+```
+
+```pycon exec="1" source="console" session="quickstart"
+>>> cfg = hydraflow.load_config(run)
+>>> print(type(cfg))
+>>> print(cfg)
+```
+
+```pycon exec="1" source="console" session="quickstart"
+>>> run = rc.last()
+>>> cfg = hydraflow.load_config(run)
+>>> print(cfg)
+```
+
+### Filter runs
+
+```pycon exec="1" source="console" session="quickstart"
+>>> filtered = rc.filter(width=400)
+>>> print(filtered)
+```
+
+```pycon exec="1" source="console" session="quickstart"
+>>> filtered = rc.filter(height=[100, 300])
+>>> print(filtered)
+```
+
+```pycon exec="1" source="console" session="quickstart"
+>>> filtered = rc.filter(height=(100, 300))
+>>> print(filtered)
+```
+
+```pycon exec="1" source="console" session="quickstart"
+>>> run = rc.find(height=100)
+>>> print(run.data.params)
+```
+
+```pycon exec="1" source="console" session="quickstart"
+>>> run = rc.find_last(height=100)
+>>> print(run.data.params)
+```
+
+### Map runs
+
+```pycon exec="1" source="console" session="quickstart"
+>>> params = rc.map(lambda x: x.data.params)
+>>> for p in params:
+...     print(p)
+```
+
+```pycon exec="1" source="console" session="quickstart"
+>>> list(rc.map_id(print))
+```
+
+### Group runs
+
+```pycon exec="1" source="console" session="quickstart"
+>>> grouped = rc.groupby("width")
+>>> for key, group in grouped.items():
+...     print(key, group)
+```
+
+```pycon exec="1" source="console" session="quickstart"
+>>> grouped = rc.groupby(["height"])
+>>> for key, group in grouped.items():
+...     print(key, group)
+```
+
+### Config dataframe
+
+```pycon exec="1" source="console" session="quickstart"
+>>> print(rc.data.config)
+```

hydraflow-0.7.5/hydraflow.yaml

@@ -0,0 +1,5 @@
+a:
+  b: [1, 2]
+  c.d: 3m
+  c.e/3: 4
+  e: true

{hydraflow-0.7.3 → hydraflow-0.7.5}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["hatchling>=1.26.1"]
+requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [project]
 name = "hydraflow"
-version = "0.7.3"
+version = "0.7.5"
 description = "Hydraflow integrates Hydra and MLflow to manage and track machine learning experiments."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -19,40 +19,34 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
 ]
 requires-python = ">=3.10"
-dependencies = ["hydra-core>=1.3", "mlflow>=2.15"]
+dependencies = ["hydra-core>=1.3", "mlflow>=2.15", "omegaconf", "rich", "typer"]
 
 [project.urls]
 Documentation = "https://daizutabi.github.io/hydraflow/"
 Source = "https://github.com/daizutabi/hydraflow"
 Issues = "https://github.com/daizutabi/hydraflow/issues"
 
-[tool.uv]
-dev-dependencies = [
-  "markdown-exec[ansi]",
-  "mkapi",
-  "mkdocs-material",
-  "mkdocs>=1.6",
+[project.scripts]
+hydraflow = "hydraflow.cli:app"
+
+[dependency-groups]
+dev = [
+  "pytest-clarity",
   "pytest-cov",
   "pytest-order",
   "pytest-randomly",
   "pytest-xdist",
 ]
-
-[tool.hatch.build.targets.sdist]
-exclude = ["/.github", "/docs"]
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/hydraflow"]
+docs = ["markdown-exec[ansi]", "mkapi", "mkdocs-material"]
 
 [tool.pytest.ini_options]
 addopts = [
   "--cov=hydraflow",
   "--cov-report=lcov:lcov.info",
-  "-n8",
   "--dist=loadgroup",
+  "-n8",
 ]
 filterwarnings = [
-  "ignore:pkg_resources is deprecated:DeprecationWarning",
   "ignore:Support for class-based `config` is deprecated",
   "ignore:Pydantic V1 style",
 ]
@@ -98,3 +92,4 @@ ignore = [
 ]
 "apps/*.py" = ["D", "G", "INP"]
 "src/hydraflow/main.py" = ["ANN201", "D401", "PLR0913"]
+"src/hydraflow/cli.py" = ["ANN", "D"]

{hydraflow-0.7.3 → hydraflow-0.7.5}/src/hydraflow/__init__.py

@@ -3,7 +3,13 @@
 from hydraflow.config import select_config, select_overrides
 from hydraflow.context import chdir_artifact, log_run, start_run
 from hydraflow.main import main
-from hydraflow.mlflow import list_runs, search_runs, set_experiment
+from hydraflow.mlflow import (
+    list_run_ids,
+    list_run_paths,
+    list_runs,
+    search_runs,
+    set_experiment,
+)
 from hydraflow.run_collection import RunCollection
 from hydraflow.utils import (
     get_artifact_dir,
@@ -22,6 +28,8 @@ __all__ = [
     "get_artifact_path",
     "get_hydra_output_dir",
     "get_overrides",
+    "list_run_ids",
+    "list_run_paths",
     "list_runs",
     "load_config",
     "load_overrides",

hydraflow-0.7.5/src/hydraflow/cli.py

@@ -0,0 +1,75 @@
+"""Hydraflow CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from omegaconf import DictConfig, OmegaConf
+from rich.console import Console
+from typer import Argument, Option
+
+app = typer.Typer(add_completion=False)
+console = Console()
+
+
+@app.command()
+def run(
+    names: Annotated[
+        list[str] | None,
+        Argument(help="Job names.", show_default=False),
+    ] = None,
+) -> None:
+    """Run jobs."""
+    typer.echo(names)
+
+    cfg = load_config()
+    typer.echo(cfg)
+
+
+@app.command()
+def show() -> None:
+    """Show the config."""
+    from rich.syntax import Syntax
+
+    cfg = load_config()
+    code = OmegaConf.to_yaml(cfg)
+    syntax = Syntax(code, "yaml")
+    console.print(syntax)
+
+
+@app.callback(invoke_without_command=True)
+def callback(
+    *,
+    version: Annotated[
+        bool,
+        Option("--version", help="Show the version and exit."),
+    ] = False,
+) -> None:
+    if version:
+        import importlib.metadata
+
+        typer.echo(f"hydraflow {importlib.metadata.version('hydraflow')}")
+        raise typer.Exit
+
+
+def find_config() -> Path:
+    if Path("hydraflow.yaml").exists():
+        return Path("hydraflow.yaml")
+
+    if Path("hydraflow.yml").exists():
+        return Path("hydraflow.yml")
+
+    typer.echo("No config file found.")
+    raise typer.Exit(code=1)
+
+
+def load_config() -> DictConfig:
+    cfg = OmegaConf.load(find_config())
+
+    if isinstance(cfg, DictConfig):
+        return cfg
+
+    typer.echo("Invalid config file.")
+    raise typer.Exit(code=1)

{hydraflow-0.7.3 → hydraflow-0.7.5}/src/hydraflow/mlflow.py

@@ -153,18 +153,17 @@ def search_runs(  # noqa: PLR0913
     return RunCollection(runs)  # type: ignore
 
 
-def list_runs(
+def list_run_paths(
     experiment_names: str | list[str] | None = None,
-    n_jobs: int = 0,
-    status: str | list[str] | int | list[int] | None = None,
-) -> RunCollection:
-    """List all runs for the specified experiments.
+    *other: str,
+) -> list[Path]:
+    """List all run paths for the specified experiments.
 
-    This function retrieves all runs for the given list of experiment names.
+    This function retrieves all run paths for the given list of experiment names.
     If no experiment names are provided (None), it defaults to searching all runs
     for the currently active experiment. If an empty list is provided, the function
     will search all runs for all experiments except the "Default" experiment.
-    The function returns the results as a `RunCollection` object.
+    The function returns the results as a list of `Path` objects.
 
     Note:
         The returned runs are sorted by their start time in ascending order.
@@ -174,27 +173,12 @@ def list_runs(
             for runs. If None or an empty list is provided, the function will
             search the currently active experiment or all experiments except
             the "Default" experiment.
-        n_jobs (int): The number of jobs to run in parallel. If 0, the function
-            will search runs sequentially.
-        status (str | list[str] | int | list[int] | None): The status of the runs
-            to filter.
+        other (str): The parts of the run directory to join.
 
     Returns:
-        RunCollection: A `RunCollection` instance containing the runs for the
-        specified experiments.
+        list[Path]: A list of run paths for the specified experiments.
 
     """
-    rc = _list_runs(experiment_names, n_jobs)
-    if status is None:
-        return rc
-
-    return rc.filter(status=status)
-
-
-def _list_runs(
-    experiment_names: str | list[str] | None = None,
-    n_jobs: int = 0,
-) -> RunCollection:
     if isinstance(experiment_names, str):
         experiment_names = [experiment_names]
 
@@ -202,14 +186,11 @@ def _list_runs(
         experiments = mlflow.search_experiments()
         experiment_names = [e.name for e in experiments if e.name != "Default"]
 
-    if n_jobs == 0:
-        return search_runs(experiment_names=experiment_names)
-
     if experiment_names is None:
         experiment_id = _get_experiment_id()
         experiment_names = [mlflow.get_experiment(experiment_id).name]
 
-    run_ids = []
+    run_paths: list[Path] = []
 
     for name in experiment_names:
         if experiment := mlflow.get_experiment_by_name(name):
@@ -217,9 +198,83 @@ def _list_runs(
 
             if isinstance(uri, str):
                 path = get_artifact_dir(uri=uri)
-                run_ids.extend(file.stem for file in path.iterdir() if file.is_dir())
+                run_paths.extend(p for p in path.iterdir() if p.is_dir())
+
+    if other:
+        return [p.joinpath(*other) for p in run_paths]
+
+    return run_paths
+
+
+def list_run_ids(experiment_names: str | list[str] | None = None) -> list[str]:
+    """List all run IDs for the specified experiments.
+
+    This function retrieves all runs for the given list of experiment names.
+    If no experiment names are provided (None), it defaults to searching all runs
+    for the currently active experiment. If an empty list is provided, the function
+    will search all runs for all experiments except the "Default" experiment.
+    The function returns the results as a list of string.
+
+    Note:
+        The returned runs are sorted by their start time in ascending order.
+
+    Args:
+        experiment_names (list[str] | None): List of experiment names to search
+            for runs. If None or an empty list is provided, the function will
+            search the currently active experiment or all experiments except
+            the "Default" experiment.
+
+    Returns:
+        list[str]: A list of run IDs for the specified experiments.
+
+    """
+    return [run_dir.stem for run_dir in list_run_paths(experiment_names)]
+
+
+def list_runs(
+    experiment_names: str | list[str] | None = None,
+    n_jobs: int = 0,
+    status: str | list[str] | int | list[int] | None = None,
+) -> RunCollection:
+    """List all runs for the specified experiments.
+
+    This function retrieves all runs for the given list of experiment names.
+    If no experiment names are provided (None), it defaults to searching all runs
+    for the currently active experiment. If an empty list is provided, the function
+    will search all runs for all experiments except the "Default" experiment.
+    The function returns the results as a `RunCollection` object.
+
+    Note:
+        The returned runs are sorted by their start time in ascending order.
+
+    Args:
+        experiment_names (list[str] | None): List of experiment names to search
+            for runs. If None or an empty list is provided, the function will
+            search the currently active experiment or all experiments except
+            the "Default" experiment.
+        n_jobs (int): The number of jobs to run in parallel. If 0, the function
+            will search runs sequentially.
+        status (str | list[str] | int | list[int] | None): The status of the runs
+            to filter.
+
+    Returns:
+        RunCollection: A `RunCollection` instance containing the runs for the
+        specified experiments.
+
+    """
+    run_ids = list_run_ids(experiment_names)
+
+    if n_jobs == 0:
+        runs = [mlflow.get_run(run_id) for run_id in run_ids]
+
+    else:
+        it = (joblib.delayed(mlflow.get_run)(run_id) for run_id in run_ids)
+        runs = joblib.Parallel(n_jobs, prefer="threads")(it)
 
-    it = (joblib.delayed(mlflow.get_run)(run_id) for run_id in run_ids)
-    runs = joblib.Parallel(n_jobs, prefer="threads")(it)
     runs = sorted(runs, key=lambda run: run.info.start_time)  # type: ignore
-    return RunCollection(runs)  # type: ignore
+    rc = RunCollection(runs)  # type: ignore
+
+    if status is None:
+        return rc
+
+    return rc.filter(status=status)

hydraflow-0.7.5/tests/cli/conftest.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def setup(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
+    monkeypatch.chdir(tmp_path)
+    yield

hydraflow-0.7.5/tests/cli/test_run.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from hydraflow.cli import app
+
+runner = CliRunner()
+
+
+def test_invoke_error():
+    result = runner.invoke(app, ["run"])
+    assert result.exit_code == 1
+
+
+def test_invoke():
+    Path("hydraflow.yaml").write_text("a:\n b: [1, 2]")
+    result = runner.invoke(app, ["run"])
+    assert result.exit_code == 0

hydraflow-0.7.5/tests/cli/test_show.py

@@ -0,0 +1,52 @@
+from pathlib import Path
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from hydraflow.cli import app
+
+runner = CliRunner()
+
+
+@pytest.mark.parametrize("file", ["hydraflow.yaml", "hydraflow.yml"])
+def test_find_config(file):
+    from hydraflow.cli import find_config
+
+    Path(file).touch()
+    assert find_config() == Path(file)
+
+
+def test_find_config_error():
+    from hydraflow.cli import find_config
+
+    with pytest.raises(typer.Exit):
+        find_config()
+
+
+def test_load_config():
+    from hydraflow.cli import load_config
+
+    Path("hydraflow.yaml").write_text("a:\n b: 1")
+    cfg = load_config()
+    assert cfg["a"]["b"] == 1
+
+
+def test_load_config_error():
+    from hydraflow.cli import load_config
+
+    Path("hydraflow.yml").write_text("- 1\n- 2")
+
+    with pytest.raises(typer.Exit):
+        load_config()
+
+
+def test_invoke_error():
+    result = runner.invoke(app, ["show"])
+    assert result.exit_code == 1
+
+
+def test_invoke():
+    Path("hydraflow.yaml").write_text("a:\n b: [1, 2]")
+    result = runner.invoke(app, ["show"])
+    assert result.exit_code == 0

hydraflow-0.7.5/tests/cli/test_version.py

@@ -0,0 +1,20 @@
+import subprocess
+
+from typer.testing import CliRunner
+
+from hydraflow.cli import app
+
+runner = CliRunner()
+
+
+def test_invoke():
+    result = runner.invoke(app, ["--version"])
+    assert result.exit_code == 0
+    assert "hydraflow" in result.stdout
+    assert result.stdout.count(".") == 2
+
+
+def test_command():
+    out = subprocess.check_output(["hydraflow", "--version"], text=True)
+    assert "hydraflow" in out
+    assert out.count(".") == 2

{hydraflow-0.7.3 → hydraflow-0.7.5}/tests/test_mlflow.py

@@ -92,3 +92,10 @@ def test_list_runs(experiment: Experiment, status, n, n_jobs, func):
     experiment_names = func(experiment.name)
     rc = list_runs(experiment_names=experiment_names, status=status, n_jobs=n_jobs)
     assert len(rc) == n
+
+
+def test_list_run_dirs(experiment: Experiment):
+    from hydraflow.mlflow import list_run_paths
+
+    dirs = list_run_paths(experiment.name, "artifacts")
+    assert all(d.is_dir() for d in dirs)