Add execution configuration helper

tests/test_execution_config.py

@@ -0,0 +1,61 @@
+import json
+from pathlib import Path
+
+import pytest
+
+import valohai
+from valohai.paths import get_config_path
+
+# execution configuration example
+EXAMPLE_CONFIG = {
+    "valohai.commit-identifier": "~8603a0246c0397770945439249084fa514eab09548a88dfcb16a019dfe420301",
+    "valohai.creator-email": None,
+    "valohai.creator-id": 1,
+    "valohai.creator-name": "test-user",
+    "valohai.environment-id": "0189ba6d-b1f5-4b64-1a08-9ff09f447034",
+    "valohai.environment-name": "The Default Environment",
+    "valohai.environment-slug": "default",
+    "valohai.execution-counter": 42,
+    "valohai.execution-ctime": "2024-12-30T13:58:46.832605+00:00",
+    "valohai.execution-duration": None,
+    "valohai.execution-id": "019417dc-b12f-0021-c074-87370badadef",
+    "valohai.execution-image": "ghcr.io/astral-sh/uv:python3.12-bookworm-slim",
+    "valohai.execution-qtime": None,
+    "valohai.execution-status": "created",
+    "valohai.execution-step": "exec-step-name",
+    "valohai.execution-tags": [],
+    "valohai.execution-title": "example execution title",
+    "valohai.project-id": "01931b1d-9db0-0021-c074-87370badadef",
+    "valohai.project-name": "test-org/test-project",
+}
+
+
+def test_config_does_not_exist():
+    config_path = Path(get_config_path())
+    assert (
+        not config_path.exists()
+    ), "Config file should not exist by default when not running in Valohai"
+
+    # try reading a non-existent config file
+    assert valohai.execution().config is None, "Execution should not exist"
+
+
+def test_get_config(fake_config):
+    fake_config.write_text(json.dumps(EXAMPLE_CONFIG))
+
+    config = valohai.execution().config
+    assert config is not None, "Execution config should exist"
+
+    assert config.id == EXAMPLE_CONFIG["valohai.execution-id"]
+    assert config.title == EXAMPLE_CONFIG["valohai.execution-title"]
+    assert config.counter == EXAMPLE_CONFIG["valohai.execution-counter"]
+
+
+@pytest.fixture
+def fake_config(tmp_path, monkeypatch) -> Path:
+    """Create and use a fake execution configuration file."""
+    config_file = tmp_path / "execution.json"
+    # patch the config path to point to the fake file
+    monkeypatch.setenv("VH_CONFIG_DIR", str(tmp_path))
+
+    return config_file

valohai/__init__.py

@@ -11,11 +11,13 @@
 from valohai.parameters import parameters
 from valohai.prepare_impl import prepare
 from valohai.triggers import triggers
+from valohai.execution import execution
 
 Pipeline = papi.Papi
 
 __all__ = [
     "distributed",
+    "execution",
     "inputs",
     "logger",
     "output_properties",

valohai/execution.py

@@ -0,0 +1,43 @@
+"""Helper for getting information about the current execution."""
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from valohai.paths import get_config_path
+
+
+@dataclass(frozen=True)
+class ExecutionConfig:
+    """Information about the current execution."""
+
+    counter: Optional[int]
+    id: Optional[str]
+    title: Optional[str]
+
+
+class Execution:
+    @property
+    def config(self) -> Optional[ExecutionConfig]:
+        """
+        Fetch execution configuration information.
+
+        Returns:
+            ExecutionConfig: The execution configuration information
+                             or None when running locally.
+        """
+        config_file = Path(get_config_path()) / "execution.json"
+        try:
+            config = json.loads(config_file.read_bytes())
+        except FileNotFoundError:
+            return None
+
+        return ExecutionConfig(
+            counter=config.get("valohai.execution-counter"),
+            id=config.get("valohai.execution-id"),
+            title=config.get("valohai.execution-title"),
+        )
+
+
+execution = Execution