furu 0.0.1__py3-none-any.whl

furu/__init__.py

@@ -0,0 +1,82 @@
+"""
+Furu: cacheable, nested pipelines as config objects.
+
+This package uses a src-layout. Import the package as `furu`.
+"""
+
+from importlib.metadata import version
+
+import chz
+import submitit
+
+__version__ = version("furu")
+
+from .config import FURU_CONFIG, FuruConfig, get_furu_root, set_furu_root
+from .adapters import SubmititAdapter
+from .core import Furu, FuruList
+from .errors import (
+    FuruComputeError,
+    FuruError,
+    FuruLockNotAcquired,
+    FuruMigrationRequired,
+    FuruWaitTimeout,
+    MISSING,
+)
+from .runtime import (
+    configure_logging,
+    current_holder,
+    current_log_dir,
+    enter_holder,
+    get_logger,
+    load_env,
+    log,
+    write_separator,
+)
+from .migrate import migrate
+from .migration import (
+    NamespacePair,
+    MigrationCandidate,
+    MigrationSkip,
+    apply_migration,
+    find_migration_candidates,
+    find_migration_candidates_initialized_target,
+)
+from .serialization import FuruSerializer
+from .storage import MetadataManager, StateManager
+
+__all__ = [
+    "__version__",
+    "FURU_CONFIG",
+    "Furu",
+    "FuruComputeError",
+    "FuruConfig",
+    "FuruError",
+    "FuruList",
+    "FuruLockNotAcquired",
+    "FuruMigrationRequired",
+    "FuruSerializer",
+    "FuruWaitTimeout",
+    "MISSING",
+    "migrate",
+    "NamespacePair",
+    "MigrationCandidate",
+    "MigrationSkip",
+    "apply_migration",
+    "find_migration_candidates",
+    "find_migration_candidates_initialized_target",
+    "MetadataManager",
+    "StateManager",
+    "SubmititAdapter",
+    "chz",
+    "configure_logging",
+    "current_holder",
+    "current_log_dir",
+    "enter_holder",
+    "get_furu_root",
+    "get_logger",
+    "load_env",
+    "log",
+    "write_separator",
+    "set_furu_root",
+    "submitit",
+]

furu/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .submitit import SubmititAdapter
+
+__all__ = ["SubmititAdapter"]

furu/adapters/submitit.py

@@ -0,0 +1,195 @@
+import threading
+import time
+from pathlib import Path
+from typing import Any, Callable, Protocol
+
+
+from ..config import FURU_CONFIG
+from ..storage import StateManager
+from ..storage.state import _FuruState, ProbeResult
+
+
+# Protocol for submitit Job-like objects. We use this instead of Any because
+# submitit is an external library and we want to document the interface we expect.
+class SubmititJobProtocol(Protocol):
+    """Protocol for submitit Job objects."""
+
+    job_id: str | None
+
+    def done(self) -> bool: ...
+    def state(self) -> str: ...
+    def result(self, timeout: float | None = None) -> object: ...
+    def wait(self) -> None: ...
+
+
+# Type alias for submitit Executor. The executor is from an external library
+# with a complex generic type, so we use Any here.
+SubmititExecutor = Any
+
+# Type alias for submitit Job. Jobs come from external library and can be
+# various types depending on the executor backend.
+SubmititJob = Any
+
+
+class SubmititAdapter:
+    """Adapter for working with submitit executors."""
+
+    JOB_PICKLE = "job.pkl"
+
+    def __init__(self, executor: SubmititExecutor):
+        self.executor = executor
+
+    def submit(self, fn: Callable[[], None]) -> SubmititJob:
+        """Submit a job to the executor."""
+        return self.executor.submit(fn)
+
+    def wait(self, job: SubmititJob, timeout: float | None = None) -> None:
+        """Wait for job completion."""
+        if timeout:
+            job.result(timeout=timeout)
+        else:
+            job.wait()
+
+    def get_job_id(self, job: SubmititJob) -> str | None:
+        """Get job ID if available."""
+        job_id = getattr(job, "job_id", None)
+        if job_id:
+            return str(job_id)
+        return None
+
+    def is_done(self, job: SubmititJob) -> bool:
+        """Check if job is done."""
+        done_fn = getattr(job, "done", None)
+        if done_fn and callable(done_fn):
+            return done_fn()
+        return False
+
+    def get_state(self, job: SubmititJob) -> str | None:
+        """Get job state from scheduler."""
+        state_fn = getattr(job, "state", None)
+        if state_fn and callable(state_fn):
+            return state_fn()
+        return None
+
+    def pickle_job(self, job: SubmititJob, directory: Path) -> None:
+        """Pickle job handle to file."""
+        import cloudpickle as pickle
+
+        job_path = StateManager.get_internal_dir(directory) / self.JOB_PICKLE
+        job_path.parent.mkdir(parents=True, exist_ok=True)
+        with job_path.open("wb") as f:
+            pickle.dump(job, f)
+
+    def load_job(self, directory: Path) -> SubmititJob | None:
+        """Load job handle from pickle file."""
+        job_path = StateManager.get_internal_dir(directory) / self.JOB_PICKLE
+        if not job_path.is_file():
+            return None
+
+        import cloudpickle as pickle
+
+        with job_path.open("rb") as f:
+            return pickle.load(f)
+
+    def watch_job_id(
+        self,
+        job: SubmititJob,
+        directory: Path,
+        *,
+        attempt_id: str,
+        callback: Callable[[str], None] | None = None,
+    ) -> None:
+        """Watch for job ID in background thread and update state."""
+
+        def watcher():
+            while True:
+                job_id = self.get_job_id(job)
+                if job_id:
+
+                    def mutate(state: _FuruState) -> None:
+                        attempt = state.attempt
+                        if attempt is None or attempt.id != attempt_id:
+                            return
+                        attempt.scheduler["job_id"] = job_id
+
+                    StateManager.update_state(directory, mutate)
+                    if callback:
+                        callback(job_id)
+                    break
+
+                if self.is_done(job):
+                    break
+
+                time.sleep(0.5)
+
+        thread = threading.Thread(target=watcher, daemon=True)
+        thread.start()
+
+    def classify_scheduler_state(self, state: str | None) -> str | None:
+        """Map scheduler state to Furu status."""
+        if not state:
+            return None
+
+        s = state.upper()
+
+        if "COMPLETE" in s or "COMPLETED" in s:
+            return "success"
+
+        if s in {
+            "PREEMPTED",
+            "TIMEOUT",
+            "NODE_FAIL",
+            "REQUEUED",
+            "REQUEUE_HOLD",
+        }:
+            return "preempted"
+
+        if s == "CANCELLED":
+            return "preempted" if FURU_CONFIG.cancelled_is_preempted else "failed"
+
+        if "FAIL" in s or "ERROR" in s:
+            return "failed"
+
+        return None
+
+    def probe(self, directory: Path, state: _FuruState) -> ProbeResult:
+        """
+        Best-effort scheduler reconciliation.
+
+        Returns a dict for `StateManager.reconcile(..., submitit_probe=...)`:
+        - `terminal_status`: one of {failed, cancelled, preempted, crashed}
+        - `scheduler_state`: raw scheduler state when available
+        - `reason`: best-effort reason string
+
+        Returns empty dict if job status cannot be determined (e.g., job pickle
+        doesn't exist yet), allowing reconcile to fall back to lease expiry.
+        """
+        job = self.load_job(directory)
+        if job is None:
+            # Job pickle doesn't exist - can't determine status, fall back to lease expiry
+            return {}
+
+        scheduler_state = self.get_state(job)
+        classified = self.classify_scheduler_state(scheduler_state)
+        if classified is None:
+            if self.is_done(job):
+                return {
+                    "terminal_status": "crashed",
+                    "scheduler_state": scheduler_state,
+                    "reason": "job_done_unknown_state",
+                }
+            return {}
+
+        # `COMPLETED` doesn't guarantee the worker wrote a success marker/state.
+        if classified == "success":
+            return {
+                "terminal_status": "crashed",
+                "scheduler_state": scheduler_state,
+                "reason": "scheduler_completed_no_success_marker",
+            }
+
+        return {
+            "terminal_status": classified,
+            "scheduler_state": scheduler_state,
+            "reason": f"scheduler:{scheduler_state}",
+        }

furu/config.py

@@ -0,0 +1,98 @@
+import os
+from pathlib import Path
+
+
+class FuruConfig:
+    """Central configuration for Furu behavior."""
+
+    def __init__(self):
+        def _get_base_root() -> Path:
+            env = os.getenv("FURU_PATH")
+            if env:
+                return Path(env).expanduser().resolve()
+            return Path("data-furu").resolve()
+
+        self.base_root = _get_base_root()
+        self.poll_interval = float(os.getenv("FURU_POLL_INTERVAL_SECS", "10"))
+        self.wait_log_every_sec = float(os.getenv("FURU_WAIT_LOG_EVERY_SECS", "10"))
+        self.stale_timeout = float(os.getenv("FURU_STALE_AFTER_SECS", str(30 * 60)))
+        self.lease_duration_sec = float(os.getenv("FURU_LEASE_SECS", "120"))
+        hb = os.getenv("FURU_HEARTBEAT_SECS")
+        self.heartbeat_interval_sec = (
+            float(hb) if hb is not None else max(1.0, self.lease_duration_sec / 3.0)
+        )
+        self.max_requeues = int(os.getenv("FURU_PREEMPT_MAX", "5"))
+        self.ignore_git_diff = os.getenv("FURU_IGNORE_DIFF", "0").lower() in {
+            "1",
+            "true",
+            "yes",
+        }
+        self.require_git = os.getenv("FURU_REQUIRE_GIT", "1").lower() in {
+            "1",
+            "true",
+            "yes",
+        }
+        self.require_git_remote = os.getenv("FURU_REQUIRE_GIT_REMOTE", "1").lower() in {
+            "1",
+            "true",
+            "yes",
+        }
+        self.force_recompute = {
+            item.strip()
+            for item in os.getenv("FURU_FORCE_RECOMPUTE", "").split(",")
+            if item.strip()
+        }
+        self.cancelled_is_preempted = os.getenv(
+            "FURU_CANCELLED_IS_PREEMPTED", "false"
+        ).lower() in {"1", "true", "yes"}
+
+        # Parse FURU_CACHE_METADATA: "never", "forever", or duration like "5m", "1h"
+        # Default: "5m" (5 minutes) - balances performance with freshness
+        self.cache_metadata_ttl_sec: float | None = self._parse_cache_duration(
+            os.getenv("FURU_CACHE_METADATA", "5m")
+        )
+
+    @staticmethod
+    def _parse_cache_duration(value: str) -> float | None:
+        """Parse cache duration string into seconds. Returns None for 'never', float('inf') for 'forever'."""
+        value = value.strip().lower()
+        if value in {"never", "0", "false", "no"}:
+            return None  # No caching
+        if value in {"forever", "inf", "true", "yes", "1"}:
+            return float("inf")  # Cache forever
+
+        # Parse duration like "5m", "1h", "30s"
+        import re
+
+        match = re.match(r"^(\d+(?:\.\d+)?)\s*([smh]?)$", value)
+        if not match:
+            raise ValueError(
+                f"Invalid FURU_CACHE_METADATA value: {value!r}. "
+                "Use 'never', 'forever', or duration like '5m', '1h', '30s'"
+            )
+
+        num = float(match.group(1))
+        unit = match.group(2) or "s"
+        multipliers = {"s": 1, "m": 60, "h": 3600}
+        return num * multipliers[unit]
+
+    def get_root(self, version_controlled: bool = False) -> Path:
+        """Get root directory for storage (version_controlled determines subdirectory)."""
+        if version_controlled:
+            return self.base_root / "git"
+        return self.base_root / "data"
+
+    @property
+    def raw_dir(self) -> Path:
+        return self.base_root / "raw"
+
+
+FURU_CONFIG = FuruConfig()
+
+
+def get_furu_root(*, version_controlled: bool = False) -> Path:
+    return FURU_CONFIG.get_root(version_controlled=version_controlled)
+
+
+def set_furu_root(path: Path) -> None:
+    FURU_CONFIG.base_root = path.resolve()

furu/core/__init__.py

@@ -0,0 +1,4 @@
+from .furu import Furu
+from .list import FuruList
+
+__all__ = ["Furu", "FuruList"]