furu 0.0.1__tar.gz → 0.0.3__tar.gz

furu-0.0.1/README.md → furu-0.0.3/PKG-INFO

@@ -1,3 +1,22 @@
+Metadata-Version: 2.3
+Name: furu
+Version: 0.0.3
+Summary: Cacheable, nested pipelines for Python. Define computations as configs; furu handles caching, state tracking, and result reuse across runs.
+Author: Herman Brunborg
+Author-email: Herman Brunborg <herman@brunborg.com>
+Requires-Dist: chz>=0.4.0
+Requires-Dist: cloudpickle>=3.1.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=14.2.0
+Requires-Dist: submitit>=1.5.3
+Requires-Dist: fastapi>=0.109.0 ; extra == 'dashboard'
+Requires-Dist: uvicorn[standard]>=0.27.0 ; extra == 'dashboard'
+Requires-Dist: typer>=0.9.0 ; extra == 'dashboard'
+Requires-Python: >=3.12
+Provides-Extra: dashboard
+Description-Content-Type: text/markdown
+
 # furu
 
 > **Note:** `v0.0.x` is alpha and may include breaking changes.
@@ -114,20 +133,25 @@ class TrainTextModel(furu.Furu[str]):
 
 ### Storage Structure
 
+Furu uses two roots: `FURU_PATH` for `data/` + `raw/`, and
+`FURU_VERSION_CONTROLLED_PATH` for `artifacts/`. Defaults:
+
+```
+FURU_PATH=<project>/furu-data
+FURU_VERSION_CONTROLLED_PATH=<project>/furu-data/artifacts
+```
+
+`<project>` is the nearest directory containing `pyproject.toml` (falling back to
+the git root). This means you can move `FURU_PATH` without relocating artifacts.
+
 ```
 $FURU_PATH/
-├── data/                         # Default storage (version_controlled=False)
-│   └── <module>/<Class>/
-│       └── <hash>/
-│           ├── .furu/
-│           │   ├── metadata.json # Config, git info, environment
-│           │   ├── state.json    # Status and timestamps
-│           │   ├── furu.log    # Captured logs
-│           │   └── SUCCESS.json  # Marker file
-│           └── <your outputs>    # Files from _create()
-├── git/                          # For version_controlled=True
-│   └── <same structure>
-└── raw/                          # Shared directory for large files
+├── data/                         # version_controlled=False
+│   └── <module>/<Class>/<hash>/
+└── raw/
+
+$FURU_VERSION_CONTROLLED_PATH/    # version_controlled=True
+└── <module>/<Class>/<hash>/
 ```
 
 ## Features
@@ -241,10 +265,17 @@ For artifacts that should be stored separately (e.g., checked into git):
 
 ```python
 class VersionedConfig(furu.Furu[dict], version_controlled=True):
-    # Stored under $FURU_PATH/git/ instead of $FURU_PATH/data/
+    # Stored under $FURU_VERSION_CONTROLLED_PATH
+    # Default: <project>/furu-data/artifacts
     ...
 ```
 
+`<project>` is the nearest directory containing `pyproject.toml`, or the git root
+if `pyproject.toml` is missing.
+
+It is typical to keep `furu-data/data/` and `furu-data/raw/` in `.gitignore` while
+committing `furu-data/artifacts/`.
+
 ## Logging
 
 Furu installs stdlib `logging` handlers that capture logs to per-artifact files.
@@ -305,6 +336,17 @@ except FuruLockNotAcquired:
     print("Could not acquire lock")
 ```
 
+By default, failed artifacts are retried on the next `load_or_create()` call. Set
+`FURU_RETRY_FAILED=0` or pass `retry_failed=False` to keep failures sticky.
+
+`FURU_MAX_WAIT_SECS` overrides the per-class `_max_wait_time_sec` (default 600s)
+timeout used when waiting for compute locks before raising `FuruWaitTimeout`.
+
+Failures during metadata collection or signal handler setup (before `_create()`
+runs) raise `FuruComputeError` with the original exception attached. These
+failures still mark the attempt as failed and record details in `state.json`
+and `furu.log`.
+
 ## Submitit Integration
 
 Run computations on SLURM clusters via [submitit](https://github.com/facebookincubator/submitit):
@@ -379,10 +421,14 @@ The `/api/experiments` endpoint supports:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `FURU_PATH` | `./data-furu/` | Base storage directory |
+| `FURU_PATH` | `<project>/furu-data` | Base storage directory for non-versioned artifacts |
+| `FURU_VERSION_CONTROLLED_PATH` | `<project>/furu-data/artifacts` | Override version-controlled storage root |
 | `FURU_LOG_LEVEL` | `INFO` | Console verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
 | `FURU_IGNORE_DIFF` | `false` | Skip embedding git diff in metadata |
+| `FURU_ALWAYS_RERUN` | `""` | Comma-separated class qualnames to always rerun (use `ALL` to bypass cache globally; cannot combine with other entries; entries must be importable) |
+| `FURU_RETRY_FAILED` | `true` | Retry failed artifacts by default (set to `0` to keep failures sticky) |
 | `FURU_POLL_INTERVAL_SECS` | `10` | Polling interval for queued/running jobs |
+| `FURU_MAX_WAIT_SECS` | unset | Override wait timeout (falls back to `_max_wait_time_sec`, default 600s) |
 | `FURU_WAIT_LOG_EVERY_SECS` | `10` | Interval between "waiting" log messages |
 | `FURU_STALE_AFTER_SECS` | `1800` | Consider running jobs stale after this duration |
 | `FURU_LEASE_SECS` | `120` | Compute lock lease duration |

furu-0.0.1/PKG-INFO → furu-0.0.3/README.md

@@ -1,21 +1,3 @@
-Metadata-Version: 2.4
-Name: furu
-Version: 0.0.1
-Summary: Cacheable, nested pipelines for Python. Define computations as configs; furu handles caching, state tracking, and result reuse across runs.
-Author-email: Herman Brunborg <herman@brunborg.com>
-Requires-Python: >=3.12
-Requires-Dist: chz>=0.4.0
-Requires-Dist: cloudpickle>=3.1.1
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: python-dotenv>=1.0.0
-Requires-Dist: rich>=14.2.0
-Requires-Dist: submitit>=1.5.3
-Provides-Extra: dashboard
-Requires-Dist: fastapi>=0.109.0; extra == 'dashboard'
-Requires-Dist: typer>=0.9.0; extra == 'dashboard'
-Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'dashboard'
-Description-Content-Type: text/markdown
-
 # furu
 
 > **Note:** `v0.0.x` is alpha and may include breaking changes.
@@ -132,20 +114,25 @@ class TrainTextModel(furu.Furu[str]):
 
 ### Storage Structure
 
+Furu uses two roots: `FURU_PATH` for `data/` + `raw/`, and
+`FURU_VERSION_CONTROLLED_PATH` for `artifacts/`. Defaults:
+
+```
+FURU_PATH=<project>/furu-data
+FURU_VERSION_CONTROLLED_PATH=<project>/furu-data/artifacts
+```
+
+`<project>` is the nearest directory containing `pyproject.toml` (falling back to
+the git root). This means you can move `FURU_PATH` without relocating artifacts.
+
 ```
 $FURU_PATH/
-├── data/                         # Default storage (version_controlled=False)
-│   └── <module>/<Class>/
-│       └── <hash>/
-│           ├── .furu/
-│           │   ├── metadata.json # Config, git info, environment
-│           │   ├── state.json    # Status and timestamps
-│           │   ├── furu.log    # Captured logs
-│           │   └── SUCCESS.json  # Marker file
-│           └── <your outputs>    # Files from _create()
-├── git/                          # For version_controlled=True
-│   └── <same structure>
-└── raw/                          # Shared directory for large files
+├── data/                         # version_controlled=False
+│   └── <module>/<Class>/<hash>/
+└── raw/
+
+$FURU_VERSION_CONTROLLED_PATH/    # version_controlled=True
+└── <module>/<Class>/<hash>/
 ```
 
 ## Features
@@ -259,10 +246,17 @@ For artifacts that should be stored separately (e.g., checked into git):
 
 ```python
 class VersionedConfig(furu.Furu[dict], version_controlled=True):
-    # Stored under $FURU_PATH/git/ instead of $FURU_PATH/data/
+    # Stored under $FURU_VERSION_CONTROLLED_PATH
+    # Default: <project>/furu-data/artifacts
     ...
 ```
 
+`<project>` is the nearest directory containing `pyproject.toml`, or the git root
+if `pyproject.toml` is missing.
+
+It is typical to keep `furu-data/data/` and `furu-data/raw/` in `.gitignore` while
+committing `furu-data/artifacts/`.
+
 ## Logging
 
 Furu installs stdlib `logging` handlers that capture logs to per-artifact files.
@@ -323,6 +317,17 @@ except FuruLockNotAcquired:
     print("Could not acquire lock")
 ```
 
+By default, failed artifacts are retried on the next `load_or_create()` call. Set
+`FURU_RETRY_FAILED=0` or pass `retry_failed=False` to keep failures sticky.
+
+`FURU_MAX_WAIT_SECS` overrides the per-class `_max_wait_time_sec` (default 600s)
+timeout used when waiting for compute locks before raising `FuruWaitTimeout`.
+
+Failures during metadata collection or signal handler setup (before `_create()`
+runs) raise `FuruComputeError` with the original exception attached. These
+failures still mark the attempt as failed and record details in `state.json`
+and `furu.log`.
+
 ## Submitit Integration
 
 Run computations on SLURM clusters via [submitit](https://github.com/facebookincubator/submitit):
@@ -397,10 +402,14 @@ The `/api/experiments` endpoint supports:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `FURU_PATH` | `./data-furu/` | Base storage directory |
+| `FURU_PATH` | `<project>/furu-data` | Base storage directory for non-versioned artifacts |
+| `FURU_VERSION_CONTROLLED_PATH` | `<project>/furu-data/artifacts` | Override version-controlled storage root |
 | `FURU_LOG_LEVEL` | `INFO` | Console verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
 | `FURU_IGNORE_DIFF` | `false` | Skip embedding git diff in metadata |
+| `FURU_ALWAYS_RERUN` | `""` | Comma-separated class qualnames to always rerun (use `ALL` to bypass cache globally; cannot combine with other entries; entries must be importable) |
+| `FURU_RETRY_FAILED` | `true` | Retry failed artifacts by default (set to `0` to keep failures sticky) |
 | `FURU_POLL_INTERVAL_SECS` | `10` | Polling interval for queued/running jobs |
+| `FURU_MAX_WAIT_SECS` | unset | Override wait timeout (falls back to `_max_wait_time_sec`, default 600s) |
 | `FURU_WAIT_LOG_EVERY_SECS` | `10` | Interval between "waiting" log messages |
 | `FURU_STALE_AFTER_SECS` | `1800` | Consider running jobs stale after this duration |
 | `FURU_LEASE_SECS` | `120` | Compute lock lease duration |

{furu-0.0.1 → furu-0.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "furu"
-version = "0.0.1"
+version = "0.0.3"
 description = "Cacheable, nested pipelines for Python. Define computations as configs; furu handles caching, state tracking, and result reuse across runs."
 readme = "README.md"
 authors = [
@@ -42,14 +42,8 @@ test = [
 ]
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build]
-artifacts = ["src/furu/dashboard/frontend/dist/**/*"]
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/furu"]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{furu-0.0.1 → furu-0.0.3}/src/furu/__init__.py

@@ -13,7 +13,7 @@ __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 .core import DependencyChzSpec, DependencySpec, Furu, FuruList
 from .errors import (
     FuruComputeError,
     FuruError,
@@ -56,6 +56,8 @@ __all__ = [
     "FuruMigrationRequired",
     "FuruSerializer",
     "FuruWaitTimeout",
+    "DependencyChzSpec",
+    "DependencySpec",
     "MISSING",
     "migrate",
     "NamespacePair",

furu-0.0.3/src/furu/config.py

@@ -0,0 +1,178 @@
+import os
+from importlib import import_module
+from pathlib import Path
+
+
+class FuruConfig:
+    """Central configuration for Furu behavior."""
+
+    DEFAULT_ROOT_DIR = Path("furu-data")
+    VERSION_CONTROLLED_SUBDIR = DEFAULT_ROOT_DIR / "artifacts"
+
+    def __init__(self):
+        def _get_base_root() -> Path:
+            env = os.getenv("FURU_PATH")
+            if env:
+                return Path(env).expanduser().resolve()
+            project_root = self._find_project_root(fallback_to_cwd=True)
+            return (project_root / self.DEFAULT_ROOT_DIR).resolve()
+
+        self.base_root = _get_base_root()
+        self.version_controlled_root_override = self._get_version_controlled_override()
+        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)))
+        max_wait_env = os.getenv("FURU_MAX_WAIT_SECS")
+        self.max_wait_time_sec = float(max_wait_env) if max_wait_env else None
+        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.retry_failed = os.getenv("FURU_RETRY_FAILED", "1").lower() in {
+            "1",
+            "true",
+            "yes",
+        }
+        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",
+        }
+        always_rerun_items = {
+            item.strip()
+            for item in os.getenv("FURU_ALWAYS_RERUN", "").split(",")
+            if item.strip()
+        }
+        all_entries = {item for item in always_rerun_items if item.lower() == "all"}
+        if all_entries and len(always_rerun_items) > len(all_entries):
+            raise ValueError(
+                "FURU_ALWAYS_RERUN cannot combine 'ALL' with specific entries"
+            )
+        self.always_rerun_all = bool(all_entries)
+        if self.always_rerun_all:
+            always_rerun_items = {
+                item for item in always_rerun_items if item.lower() != "all"
+            }
+        self._require_namespaces_exist(always_rerun_items)
+        self.always_rerun = always_rerun_items
+        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 uses its own root)."""
+        if version_controlled:
+            if self.version_controlled_root_override is not None:
+                return self.version_controlled_root_override
+            return self._resolve_version_controlled_root()
+        return self.base_root / "data"
+
+    @classmethod
+    def _get_version_controlled_override(cls) -> Path | None:
+        env = os.getenv("FURU_VERSION_CONTROLLED_PATH")
+        if env:
+            return Path(env).expanduser().resolve()
+        return None
+
+    @classmethod
+    def _resolve_version_controlled_root(cls) -> Path:
+        project_root = cls._find_project_root()
+        return (project_root / cls.VERSION_CONTROLLED_SUBDIR).resolve()
+
+    @staticmethod
+    def _find_project_root(
+        start: Path | None = None, *, fallback_to_cwd: bool = False
+    ) -> Path:
+        base = (start or Path.cwd()).resolve()
+        git_root: Path | None = None
+        for path in (base, *base.parents):
+            if (path / "pyproject.toml").is_file():
+                return path
+            if git_root is None and (path / ".git").exists():
+                git_root = path
+        if git_root is not None:
+            return git_root
+        if fallback_to_cwd:
+            return base
+        raise ValueError(
+            "Cannot locate pyproject.toml or .git to determine version-controlled root. "
+            "Set FURU_VERSION_CONTROLLED_PATH to override."
+        )
+
+    @staticmethod
+    def _require_namespaces_exist(namespaces: set[str]) -> None:
+        if not namespaces:
+            return
+        missing_sentinel = object()
+        for namespace in namespaces:
+            module_name, _, qualname = namespace.rpartition(".")
+            if not module_name or not qualname:
+                raise ValueError(
+                    "FURU_ALWAYS_RERUN entries must be 'module.QualifiedName', "
+                    f"got {namespace!r}"
+                )
+            target: object = import_module(module_name)
+            for attr in qualname.split("."):
+                value = getattr(target, attr, missing_sentinel)
+                if value is missing_sentinel:
+                    raise ValueError(
+                        f"FURU_ALWAYS_RERUN entry does not exist: {namespace!r}"
+                    )
+                target = value
+
+    @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-0.0.3/src/furu/core/__init__.py

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