hydraflow 0.12.0__tar.gz → 0.12.2__tar.gz

{hydraflow-0.12.0 → hydraflow-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hydraflow
-Version: 0.12.0
+Version: 0.12.2
 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

{hydraflow-0.12.0 → hydraflow-0.12.2}/apps/quickstart.py

@@ -1,13 +1,16 @@
+from __future__ import annotations
+
 import logging
 from dataclasses import dataclass
+from typing import TYPE_CHECKING
 
-import hydra
-import mlflow
 from hydra.core.config_store import ConfigStore
-from hydra.core.hydra_config import HydraConfig
 
 import hydraflow
 
+if TYPE_CHECKING:
+    from mlflow.entities import Run
+
 log = logging.getLogger(__name__)
 
 
@@ -21,13 +24,10 @@ cs = ConfigStore.instance()
 cs.store(name="config", node=Config)
 
 
-@hydra.main(config_name="config", version_base=None)
-def app(cfg: Config) -> None:
-    hc = HydraConfig.get()
-    mlflow.set_experiment(hc.job.name)
-
-    with hydraflow.start_run(cfg):
-        log.info(f"{cfg.width=}, {cfg.height=}")
+@hydraflow.main(Config)
+def app(run: Run, cfg: Config) -> None:
+    log.info(run.info.run_id)
+    log.info(cfg)
 
 
 if __name__ == "__main__":

{hydraflow-0.12.0 → hydraflow-0.12.2}/docs/usage/quickstart.md

@@ -2,24 +2,22 @@
 
 ## Hydra application
 
-The following example demonstrates how to use Hydraflow with a Hydra application.
-There are two main steps to using Hydraflow:
+The following example demonstrates how to use a Hydraflow application.
 
-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"
+```python title="apps/quickstart.py" linenums="1"
 --8<-- "apps/quickstart.py"
 ```
 
-### Start a new MLflow run
+### Hydraflow's `main` decorator
 
-[`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.
+[`hydraflow.main`][] starts a new MLflow run that logs the Hydra configuration.
+The decorated function must have two arguments: `Run` and `Config`.
+The `Run` argument is the current MLflow run.
+The `Config` argument is the Hydra configuration.
 
 ```python
-with hydraflow.start_run(cfg) as run:
+@hydraflow.main(Config)
+def app(run: Run, cfg: Config) -> None:
     pass
 ```
 
@@ -31,7 +29,7 @@ rm -rf mlruns outputs multirun
 
 ### Single-run
 
-Run the Hydra application as a normal Python script.
+Run the Hydraflow application as a normal Python script.
 
 ```console exec="1" source="console"
 $ python apps/quickstart.py
@@ -43,8 +41,12 @@ Check the MLflow CLI to view the experiment.
 $ mlflow experiments search
 ```
 
+The experiment name is the name of the Hydra job.
+
 ### Multi-run
 
+Run the Hydraflow application with multiple configurations.
+
 ```console exec="1" source="console"
 $ python apps/quickstart.py -m width=400,600 height=100,200,300
 ```
@@ -53,6 +55,8 @@ $ python apps/quickstart.py -m width=400,600 height=100,200,300
 
 ### Run collection
 
+The `RunCollection` object is a collection of runs.
+
 ```pycon exec="1" source="console" session="quickstart"
 >>> import hydraflow
 >>> rc = hydraflow.list_runs("quickstart")
@@ -61,35 +65,47 @@ $ python apps/quickstart.py -m width=400,600 height=100,200,300
 
 ### Retrieve a run
 
+The `RunCollection` object has a `first` and `last` method that
+returns the first and last run in the collection.
+
 ```pycon exec="1" source="console" session="quickstart"
 >>> run = rc.first()
 >>> print(type(run))
 ```
 
 ```pycon exec="1" source="console" session="quickstart"
+>>> run = rc.last()
 >>> cfg = hydraflow.load_config(run)
->>> print(type(cfg))
 >>> print(cfg)
 ```
 
+The `load_config` function loads the Hydra configuration from the run.
+
 ```pycon exec="1" source="console" session="quickstart"
->>> run = rc.last()
 >>> cfg = hydraflow.load_config(run)
+>>> print(type(cfg))
 >>> print(cfg)
 ```
 
 ### Filter runs
 
+The `filter` method filters the runs by the given key-value pairs.
+
 ```pycon exec="1" source="console" session="quickstart"
 >>> filtered = rc.filter(width=400)
 >>> print(filtered)
 ```
 
+If the value is a list, the run will be included if the value is in the list.
+
 ```pycon exec="1" source="console" session="quickstart"
 >>> filtered = rc.filter(height=[100, 300])
 >>> print(filtered)
 ```
 
+If the value is a tuple, the run will be included if the value is between the tuple.
+The start and end of the tuple are inclusive.
+
 ```pycon exec="1" source="console" session="quickstart"
 >>> filtered = rc.filter(height=(100, 300))
 >>> print(filtered)
@@ -97,12 +113,16 @@ $ python apps/quickstart.py -m width=400,600 height=100,200,300
 
 ### Group runs
 
+The `groupby` method groups the runs by the given key.
+
 ```pycon exec="1" source="console" session="quickstart"
 >>> grouped = rc.groupby("width")
 >>> for key, group in grouped.items():
 ...     print(key, group)
 ```
 
+The `groupby` method can also take a list of keys.
+
 ```pycon exec="1" source="console" session="quickstart"
 >>> grouped = rc.groupby(["height"])
 >>> for key, group in grouped.items():
@@ -111,6 +131,13 @@ $ python apps/quickstart.py -m width=400,600 height=100,200,300
 
 ### Config dataframe
 
+The `data.config` attribute returns a pandas DataFrame
+of the Hydra configuration.
+
 ```pycon exec="1" source="console" session="quickstart"
 >>> print(rc.data.config)
 ```
+
+```bash exec="on"
+rm -rf mlruns outputs multirun
+```

{hydraflow-0.12.0 → hydraflow-0.12.2}/mkdocs.yaml

@@ -53,4 +53,4 @@ nav:
   - Home: index.md
   - Usage:
       - usage/quickstart.md
-  - Reference: $api/hydraflow.**
+  - Reference: $api/hydraflow.***

{hydraflow-0.12.0 → hydraflow-0.12.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hydraflow"
-version = "0.12.0"
+version = "0.12.2"
 description = "Hydraflow integrates Hydra and MLflow to manage and track machine learning experiments."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -96,7 +96,7 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-"apps/*.py" = ["D", "G", "INP"]
+"apps/*.py" = ["D", "G", "INP", "T"]
 "src/hydraflow/cli.py" = ["ANN", "D"]
 "src/hydraflow/core/main.py" = ["ANN201", "D401"]
 "src/hydraflow/executor/conf.py" = ["ANN", "D"]
@@ -104,3 +104,6 @@ ignore = [
 
 [tool.pyright]
 include = ["src", "tests"]
+strictDictionaryInference = true
+strictListInference = true
+strictSetInference = true

{hydraflow-0.12.0 → hydraflow-0.12.2}/src/hydraflow/core/main.py

@@ -16,6 +16,7 @@ used to wrap experiment entry points. This decorator handles:
 
 Example:
     ```python
+    import hydraflow
     from dataclasses import dataclass
     from mlflow.entities import Run
 
@@ -24,7 +25,7 @@ Example:
         learning_rate: float
         batch_size: int
 
-    @main(Config)
+    @hydraflow.main(Config)
     def train(run: Run, config: Config):
         # Your training code here
         pass

{hydraflow-0.12.0 → hydraflow-0.12.2}/src/hydraflow/executor/parser.py

@@ -48,7 +48,7 @@ def to_number(x: str) -> int | float:
     return int(x)
 
 
-def count_decimal_places(x: str) -> int:
+def count_decimal_digits(x: str) -> int:
     """Count decimal places in a string.
 
     Examine a string representing a number and returns the count
@@ -62,13 +62,13 @@ def count_decimal_places(x: str) -> int:
         int: The number of decimal places.
 
     Examples:
-        >>> count_decimal_places("1")
+        >>> count_decimal_digits("1")
         0
-        >>> count_decimal_places("-1.2")
+        >>> count_decimal_digits("-1.2")
         1
-        >>> count_decimal_places("1.234")
+        >>> count_decimal_digits("1.234")
         3
-        >>> count_decimal_places("-1.234e-10")
+        >>> count_decimal_digits("-1.234e-10")
         3
 
     """
@@ -82,8 +82,52 @@ def count_decimal_places(x: str) -> int:
     return len(decimal_part)
 
 
+def count_integer_digits(num_str: str) -> int:
+    """Count the number of digits in the integer part of a number.
+
+    Consider only the integer part of a number, even if it is in
+    scientific notation.
+
+    Args:
+        num_str (str): The string representing a number.
+
+    Returns:
+        int: The number of digits in the integer part of a number.
+        (excluding the sign)
+
+    Examples:
+        >>> count_integer_digits("123")
+        3
+        >>> count_integer_digits("-123.45")
+        3
+        >>> count_integer_digits("+0.00123")
+        1
+        >>> count_integer_digits("-1.200")
+        1
+        >>> count_integer_digits("+1.20e3")
+        1
+        >>> count_integer_digits("-0.120e-3")
+        1
+        >>> count_integer_digits(".123")
+        0
+
+    """
+    if num_str.startswith(("+", "-")):
+        num_str = num_str[1:]
+
+    if "e" in num_str.lower():
+        num_str = num_str.lower().split("e")[0]
+
+    if "." in num_str:
+        int_part = num_str.split(".")[0]
+        if not int_part:
+            return 0
+        return len(int_part)
+    return len(num_str)
+
+
 def is_number(x: str) -> bool:
-    """Check if a string is a number.
+    """Check if a string represents a valid number.
 
     Args:
         x (str): The string to check.
@@ -140,18 +184,46 @@ def _get_range(arg: str) -> tuple[float, float, float]:
 
 
 def _arange(start: float, step: float, stop: float) -> list[float]:
+    """Generate a range of floating point numbers.
+
+    This function generates a range of floating point numbers
+    with protection against rounding errors.
+
+    Args:
+        start (float): The starting value.
+        step (float): The step size.
+        stop (float): The end value (inclusive).
+
+    Returns:
+        list[float]: A list of floating point numbers from start to stop
+        (inclusive) with the given step.
+
+    """
+    if step == 0:
+        raise ValueError("Step cannot be zero")
+
+    epsilon = min(abs(start), abs(stop)) * 1e-5
+
     result = []
     current = start
 
-    while current <= stop if step > 0 else current >= stop:
-        result.append(current)
-        current += step
+    if step > 0:
+        while current <= stop + epsilon:
+            result.append(current)
+            current += step
+    else:
+        while current >= stop - epsilon:
+            result.append(current)
+            current += step
 
     return result
 
 
 def split_suffix(arg: str) -> tuple[str, str]:
-    """Split a string into prefix and suffix.
+    """Split a string into the prefix and suffix.
+
+    The suffix is the part of the string that starts with a colon (:).
+    The prefix is the part of the string that precedes the suffix.
 
     Args:
         arg (str): The string to split.
@@ -194,6 +266,16 @@ def add_exponent(value: str, exponent: str) -> str:
     Returns:
         str: The value with the exponent added.
 
+    Examples:
+        >>> add_exponent("1", "e3")
+        '1e3'
+        >>> add_exponent("1", "")
+        '1'
+        >>> add_exponent("0", "e-3")
+        '0'
+        >>> add_exponent("0.0", "e-3")
+        '0.0'
+
     """
     if value in ["0", "0.", "0.0"] or not exponent:
         return value
@@ -201,43 +283,6 @@ def add_exponent(value: str, exponent: str) -> str:
     return f"{value}{exponent}"
 
 
-def collect_values(arg: str) -> list[str]:
-    """Collect a list of values from a range argument.
-
-    Collect all individual values within a numeric range
-    represented by a string (e.g., `1:4`) and return them
-    as a list of strings.
-    Support both integer and floating-point ranges.
-
-    Args:
-        arg (str): The argument to collect.
-
-    Returns:
-        list[str]: A list of the collected values.
-
-    """
-    if "(" in arg:
-        return collect_parentheses(arg)
-
-    if ":" not in arg:
-        return [arg]
-
-    arg, exponent = split_suffix(arg)
-
-    if ":" not in arg:
-        return [f"{arg}{exponent}"]
-
-    rng = _get_range(arg)
-
-    if all(isinstance(x, int) for x in rng):
-        values = [str(x) for x in _arange(*rng)]
-    else:
-        n = max(*(count_decimal_places(x) for x in arg.split(":")))
-        values = [str(round(x, n)) for x in _arange(*rng)]
-
-    return [add_exponent(x, exponent) for x in values]
-
-
 def split_parentheses(arg: str) -> Iterator[str]:
     """Split a string with parentheses into a list of strings.
 
@@ -290,8 +335,60 @@ def collect_parentheses(arg: str) -> list[str]:
     return ["".join(x[::-1]) for x in product(*it[::-1])]
 
 
+def collect_values(arg: str) -> list[str]:
+    """Collect a list of values from a range argument.
+
+    Collect all individual values within a numeric range
+    represented by a string (e.g., `1:4`) and return them
+    as a list of strings.
+    Support both integer and floating-point ranges.
+
+    Args:
+        arg (str): The argument to collect.
+
+    Returns:
+        list[str]: A list of the collected values.
+
+    Examples:
+        >>> collect_values("1:4")
+        ['1', '2', '3', '4']
+        >>> collect_values("1.2:0.1:1.4:k")
+        ['1.2e3', '1.3e3', '1.4e3']
+        >>> collect_values("0.1")
+        ['0.1']
+        >>> collect_values("4:M")
+        ['4e6']
+        >>> collect_values("(1:3,5:7)M")
+        ['1e6', '2e6', '3e6', '5e6', '6e6', '7e6']
+        >>> collect_values("(1,5)e-(1:3)")
+        ['1e-1', '5e-1', '1e-2', '5e-2', '1e-3', '5e-3']
+
+    """
+    if "(" in arg:
+        return collect_parentheses(arg)
+
+    if ":" not in arg:
+        return [arg]
+
+    arg, exponent = split_suffix(arg)
+
+    if ":" not in arg:
+        return [f"{arg}{exponent}"]
+
+    rng = _get_range(arg)
+
+    if all(isinstance(x, int) for x in rng):
+        values = [str(x) for x in _arange(*rng)]
+    else:
+        n = max(*(count_integer_digits(x) for x in arg.split(":")))
+        m = max(*(count_decimal_digits(x) for x in arg.split(":")))
+        values = [f"{x:.{n + m}g}" for x in _arange(*rng)]
+
+    return [add_exponent(x, exponent) for x in values]
+
+
 def split(arg: str) -> list[str]:
-    r"""Split a string by top-level commas.
+    """Split a string by top-level commas.
 
     Splits a string by commas while respecting nested structures.
     Commas inside brackets and quotes are ignored, only splitting
@@ -355,8 +452,9 @@ def split(arg: str) -> list[str]:
 def expand_values(arg: str, suffix: str = "") -> Iterator[str]:
     """Expand a string argument into a list of values.
 
-    Take a string containing comma-separated values or ranges and return a list
-    of all individual values. Handle numeric ranges and special characters.
+    Take a string containing comma-separated values or ranges
+    and return a list of all individual values.
+    Handle numeric ranges and special characters.
 
     Args:
         arg (str): The argument to expand.
@@ -379,7 +477,8 @@ def split_arg(arg: str) -> tuple[str, str, str]:
         arg (str): The argument to split.
 
     Returns:
-        tuple[str, str, str]: A tuple containing the key, suffix, and value.
+        tuple[str, str, str]: A tuple containing the key,
+        suffix, and value.
 
     """
     if "=" not in arg:
@@ -398,8 +497,9 @@ def split_arg(arg: str) -> tuple[str, str, str]:
 def collect_arg(arg: str) -> str:
     """Collect a string of expanded key-value pairs.
 
-    Take a key-value pair argument and concatenates all expanded values with commas,
-    returning a single string suitable for command-line usage.
+    Take a key-value pair argument and concatenates all expanded
+    values with commas, returning a single string suitable for
+    command-line usage.
 
     Args:
         arg (str): The argument to collect.

{hydraflow-0.12.0 → hydraflow-0.12.2}/tests/executor/test_parser.py

@@ -1,3 +1,4 @@
+import numpy as np
 import pytest
 
 
@@ -12,10 +13,20 @@ def test_to_number(s, x):
     ("s", "x"),
     [("1", 0), ("1.2", 1), ("1.234", 3), ("123.", 0), ("", 0), ("1.234e-10", 3)],
 )
-def test_count_decimal_places(s, x):
-    from hydraflow.executor.parser import count_decimal_places
+def test_count_decimal_digits(s, x):
+    from hydraflow.executor.parser import count_decimal_digits
 
-    assert count_decimal_places(s) == x
+    assert count_decimal_digits(s) == x
+
+
+@pytest.mark.parametrize(
+    ("s", "x"),
+    [("1", 1), ("1.2", 1), ("1.234", 1), ("123.", 3), ("", 0), ("1.234e-10", 1)],
+)
+def test_count_integer_digits(s, x):
+    from hydraflow.executor.parser import count_integer_digits
+
+    assert count_integer_digits(s) == x
 
 
 @pytest.mark.parametrize(
@@ -24,6 +35,7 @@ def test_count_decimal_places(s, x):
         ("1:2", (1, 1, 2)),
         (":2", (0, 1, 2)),
         ("0.1:0.1:0.4", (0.1, 0.1, 0.4)),
+        ("1.2:0.1:1.4", (1.2, 0.1, 1.4)),
     ],
 )
 def test_get_range(s, x):
@@ -49,6 +61,29 @@ def test_get_range_errors(arg, expected_exception, expected_message):
     assert str(excinfo.value) == expected_message
 
 
+@pytest.mark.parametrize(
+    ("start", "step", "stop", "expected"),
+    [
+        (1.0, 2.0, 5.0, [1.0, 3.0, 5.0]),
+        (1.2, 0.1, 1.4, [1.2, 1.3, 1.4]),
+        (1.2e-12, 0.1e-12, 1.4e-12, [1.2e-12, 1.3e-12, 1.4e-12]),
+        (1.4, -0.1, 1.2, [1.4, 1.3, 1.2]),
+        (1.02e-3, 0.01e-3, 1.04e-3, [0.00102, 0.00103, 0.00104]),
+    ],
+)
+def test_arange(start, step, stop, expected):
+    from hydraflow.executor.parser import _arange
+
+    np.testing.assert_allclose(_arange(start, step, stop), expected)
+
+
+def test_arange_error():
+    from hydraflow.executor.parser import _arange
+
+    with pytest.raises(ValueError):
+        _arange(1.0, 0.0, 1.0)
+
+
 @pytest.mark.parametrize(
     ("s", "x"),
     [
@@ -86,20 +121,27 @@ def test_split_suffix(s, x):
         ("1:M", ["1e6"]),
         ("0.234p", ["0.234p"]),
         ("1:3", ["1", "2", "3"]),
-        ("0:0.25:1", ["0", "0.25", "0.5", "0.75", "1.0"]),
+        ("0:0.25:1", ["0", "0.25", "0.5", "0.75", "1"]),
+        ("10:0.25:11", ["10", "10.25", "10.5", "10.75", "11"]),
         (":3", ["0", "1", "2", "3"]),
         ("5:7", ["5", "6", "7"]),
         ("-1:1", ["-1", "0", "1"]),
-        ("1:0.5:2", ["1", "1.5", "2.0"]),
-        ("1.:0.5:2", ["1.0", "1.5", "2.0"]),
-        ("2:0.5:3", ["2", "2.5", "3.0"]),
-        ("-1:0.5:1", ["-1", "-0.5", "0.0", "0.5", "1.0"]),
+        ("1:0.5:2", ["1", "1.5", "2"]),
+        ("1.:0.5:2", ["1", "1.5", "2"]),
+        ("2:0.5:3", ["2", "2.5", "3"]),
+        ("-1:0.5:1", ["-1", "-0.5", "0", "0.5", "1"]),
         ("4:-1:2", ["4", "3", "2"]),
-        ("4.5:-1.5:2", ["4.5", "3.0"]),
-        ("4.5:-1.5:1.5", ["4.5", "3.0", "1.5"]),
-        ("4.5:-1.5:-4.5", ["4.5", "3.0", "1.5", "0.0", "-1.5", "-3.0", "-4.5"]),
+        ("4.5:-1.5:2", ["4.5", "3"]),
+        ("4.5:-1.5:1.5", ["4.5", "3", "1.5"]),
+        ("4.5:-1.5:-4.5", ["4.5", "3", "1.5", "0", "-1.5", "-3", "-4.5"]),
         ("1:2:u", ["1e-6", "2e-6"]),
-        ("1:.25:2:n", ["1e-9", "1.25e-9", "1.5e-9", "1.75e-9", "2.0e-9"]),
+        ("1:.25:2:n", ["1e-9", "1.25e-9", "1.5e-9", "1.75e-9", "2e-9"]),
+        ("1.2:0.1:1.4:k", ["1.2e3", "1.3e3", "1.4e3"]),
+        ("1.2e-3:0.1e-3:1.4e-3", ["0.0012", "0.0013", "0.0014"]),
+        ("1.2e-12:0.1e-12:1.4e-12", ["1.2e-12", "1.3e-12", "1.4e-12"]),
+        ("1.22e-6:0.01e-6:1.24e-6", ["1.22e-06", "1.23e-06", "1.24e-06"]),
+        ("1.2e3:0.1e3:1.4e3", ["1.2e+03", "1.3e+03", "1.4e+03"]),
+        ("1.2e6:0.1e6:1.4e6", ["1.2e+06", "1.3e+06", "1.4e+06"]),
         ("1:2:e2", ["1e2", "2e2"]),
         (":2:e2", ["0", "1e2", "2e2"]),
         ("-2:2:k", ["-2e3", "-1e3", "0", "1e3", "2e3"]),
@@ -117,7 +159,7 @@ def test_collect_value(s, x):
     [
         ("1,2,3", ["1", "2", "3"]),
         ("1:3,5:6", ["1", "2", "3", "5", "6"]),
-        ("0:0.25:1,2.0", ["0", "0.25", "0.5", "0.75", "1.0", "2.0"]),
+        ("0:0.25:1,2.0", ["0", "0.25", "0.5", "0.75", "1", "2.0"]),
         ("3", ["3"]),
         ("3:k", ["3e3"]),
         ("1:3:k,3:2:7:M", ["1e3", "2e3", "3e3", "3e6", "5e6", "7e6"]),
@@ -140,7 +182,7 @@ def test_expand_value(s, x):
     [
         ("1,2,3", ["1e3", "2e3", "3e3"]),
         ("1:3,5:6", ["1e3", "2e3", "3e3", "5e3", "6e3"]),
-        ("0:0.25:1,2.0", ["0e3", "0.25e3", "0.5e3", "0.75e3", "1.0e3", "2.0e3"]),
+        ("0:0.25:1,2.0", ["0e3", "0.25e3", "0.5e3", "0.75e3", "1e3", "2.0e3"]),
         ("3", ["3e3"]),
     ],
 )