furu 0.0.1__py3-none-any.whl

furu/errors.py

@@ -0,0 +1,76 @@
+import traceback
+from pathlib import Path
+
+
+class _FuruMissing:
+    """Sentinel value for missing fields."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "Furu.MISSING"
+
+
+MISSING = _FuruMissing()
+
+
+class FuruError(Exception):
+    """Base exception for Furu errors."""
+
+    pass
+
+
+class FuruWaitTimeout(FuruError):
+    """Raised when waiting for a result exceeds _max_wait_time_sec."""
+
+    pass
+
+
+class FuruLockNotAcquired(FuruError):
+    """Raised when a compute lock cannot be acquired (someone else holds it)."""
+
+    pass
+
+
+class FuruComputeError(FuruError):
+    """Raised when computation fails."""
+
+    def __init__(
+        self,
+        message: str,
+        state_path: Path,
+        original_error: Exception | None = None,
+    ):
+        self.state_path = state_path
+        self.original_error = original_error
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        msg = super().__str__()  # ty: ignore[invalid-super-argument]
+        if self.original_error:
+            msg += f"\n\nOriginal error: {self.original_error}"
+            if hasattr(self.original_error, "__traceback__"):
+                tb = "".join(
+                    traceback.format_exception(
+                        type(self.original_error),
+                        self.original_error,
+                        self.original_error.__traceback__,
+                    )
+                )
+                msg += f"\n\nTraceback:\n{tb}"
+        msg += f"\n\nState file: {self.state_path}"
+        return msg
+
+
+class FuruMigrationRequired(FuruError):
+    """Raised when a migrated object requires explicit migration."""
+
+    def __init__(self, message: str, *, state_path: Path | None = None):
+        self.state_path = state_path
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        msg = super().__str__()  # ty: ignore[invalid-super-argument]
+        if self.state_path is not None:
+            msg += f"\n\nState file: {self.state_path}"
+        return msg

furu/migrate.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Literal, Mapping
+
+from .core.furu import Furu
+from .migration import (
+    MigrationValue,
+    apply_migration,
+    find_migration_candidates_initialized_target,
+)
+from .storage import MigrationRecord
+
+
+MigrationPolicy = Literal["alias", "move", "copy"]
+
+
+def migrate(
+    from_obj: Furu,
+    to_obj: Furu,
+    *,
+    policy: MigrationPolicy = "alias",
+    origin: str | None = None,
+    note: str | None = None,
+    default_values: Mapping[str, MigrationValue] | None = None,
+) -> MigrationRecord:
+    from_namespace = ".".join(from_obj._namespace().parts)
+    candidates = find_migration_candidates_initialized_target(
+        to_obj=to_obj,
+        from_namespace=from_namespace,
+        default_fields=None,
+        drop_fields=None,
+    )
+    if not candidates:
+        raise ValueError("migration: no candidates found for initialized target")
+    if len(candidates) != 1:
+        raise ValueError("migration: expected exactly one candidate")
+    candidate = candidates[0]
+    if default_values:
+        candidate = candidate.with_default_values(default_values)
+    records = apply_migration(
+        candidate,
+        policy=policy,
+        cascade=True,
+        origin=origin,
+        note=note,
+        conflict="throw",
+    )
+    return records[0]