furu 0.0.1__py3-none-any.whl

furu/runtime/__init__.py

@@ -0,0 +1,27 @@
+"""
+Runtime helpers for furu (logging, .env loading, tracebacks).
+"""
+
+from .env import load_env
+from .logging import (
+    configure_logging,
+    current_holder,
+    current_log_dir,
+    enter_holder,
+    get_logger,
+    log,
+    write_separator,
+)
+from .tracebacks import _print_colored_traceback
+
+__all__ = [
+    "_print_colored_traceback",
+    "configure_logging",
+    "current_holder",
+    "current_log_dir",
+    "enter_holder",
+    "get_logger",
+    "load_env",
+    "log",
+    "write_separator",
+]

furu/runtime/env.py

@@ -0,0 +1,8 @@
+def load_env() -> None:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+
+
+# Preserve previous behavior: attempt to load `.env` at import-time.
+load_env()

furu/runtime/logging.py

@@ -0,0 +1,301 @@
+import contextlib
+import contextvars
+import datetime
+import logging
+import os
+import threading
+from pathlib import Path
+from typing import Generator, Protocol
+
+from rich.text import Text
+
+from ..config import FURU_CONFIG
+
+
+class _HolderProtocol(Protocol):
+    """Protocol for objects that can be used as logging context holders."""
+
+    @property
+    def furu_dir(self) -> Path: ...
+
+
+# A holder is either a Path directly or an object with a furu_dir attribute
+HolderType = Path | _HolderProtocol
+
+_FURU_HOLDER_STACK: contextvars.ContextVar[tuple[HolderType, ...]] = (
+    contextvars.ContextVar("furu_holder_stack", default=())
+)
+_FURU_LOG_LOCK = threading.Lock()
+_FURU_CONSOLE_LOCK = threading.Lock()
+
+_LOAD_OR_CREATE_PREFIX = "load_or_create"
+
+
+def _strip_load_or_create_decision_suffix(message: str) -> str:
+    """
+    Strip a trailing `(<decision>)` suffix from `load_or_create ...` console lines.
+
+    This keeps detailed decision info in file logs, but makes console output cleaner.
+    """
+    if not message.startswith(_LOAD_OR_CREATE_PREFIX):
+        return message
+    if not message.endswith(")"):
+        return message
+    idx = message.rfind(" (")
+    if idx == -1:
+        return message
+
+    decision = message[idx + 2 : -1]
+    if decision == "create" or "->" in decision:
+        return message[:idx]
+    return message
+
+
+def _holder_to_log_dir(holder: HolderType) -> Path:
+    if isinstance(holder, Path):
+        base_dir = holder
+    else:
+        directory = getattr(holder, "furu_dir", None)
+        if not isinstance(directory, Path):
+            raise TypeError(
+                "holder must be a pathlib.Path or have a .furu_dir: pathlib.Path attribute"
+            )
+        base_dir = directory
+    return base_dir / ".furu"
+
+
+@contextlib.contextmanager
+def enter_holder(holder: HolderType) -> Generator[None, None, None]:
+    """
+    Push a holder object onto the logging stack for this context.
+
+    Furu calls this automatically during `load_or_create()`, so nested
+    dependencies will log to the active dependency's folder and then revert.
+    """
+    configure_logging()
+    stack = _FURU_HOLDER_STACK.get()
+    token = _FURU_HOLDER_STACK.set((*stack, holder))
+    try:
+        yield
+    finally:
+        _FURU_HOLDER_STACK.reset(token)
+
+
+def current_holder() -> HolderType | None:
+    """Return the current holder object for logging, if any."""
+    stack = _FURU_HOLDER_STACK.get()
+    return stack[-1] if stack else None
+
+
+def current_log_dir() -> Path:
+    """Return the directory logs should be written to for this context."""
+    holder = current_holder()
+    if holder is None:
+        return FURU_CONFIG.base_root
+    return _holder_to_log_dir(holder)
+
+
+class _FuruLogFormatter(logging.Formatter):
+    def formatTime(  # noqa: N802 - keep logging.Formatter API
+        self, record: logging.LogRecord, datefmt: str | None = None
+    ) -> str:
+        dt = datetime.datetime.fromtimestamp(record.created, tz=datetime.timezone.utc)
+        return dt.isoformat(timespec="seconds")
+
+
+class _FuruContextFileHandler(logging.Handler):
+    """
+    A logging handler that writes to `current_log_dir() / "furu.log"` at emit-time.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        message = self.format(record)
+
+        directory = current_log_dir()
+        directory.mkdir(parents=True, exist_ok=True)
+
+        log_path = directory / "furu.log"
+        with _FURU_LOG_LOCK:
+            with log_path.open("a", encoding="utf-8") as fp:
+                fp.write(f"{message}\n")
+
+
+class _FuruScopeFilter(logging.Filter):
+    """
+    Capture all logs while inside a holder context.
+
+    Outside a holder context, only capture logs from the `furu` logger namespace.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if current_holder() is not None:
+            return True
+        return record.name == "furu" or record.name.startswith("furu.")
+
+
+class _FuruFileFilter(logging.Filter):
+    """Filter out records intended for console only."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return not bool(getattr(record, "furu_console_only", False))
+
+
+class _FuruConsoleFilter(logging.Filter):
+    """Only show furu namespace logs on console."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if bool(getattr(record, "furu_file_only", False)):
+            return False
+        return record.name == "furu" or record.name.startswith("furu.")
+
+
+def _console_level() -> int:
+    level = os.getenv("FURU_LOG_LEVEL", "INFO").upper()
+    return logging.getLevelNamesMapping().get(level, logging.INFO)
+
+
+class _FuruRichConsoleHandler(logging.Handler):
+    def __init__(self, *, level: int) -> None:
+        super().__init__(level=level)
+        from rich.console import Console  # type: ignore
+
+        self._console = Console(stderr=True)
+
+    @staticmethod
+    def _format_location(record: logging.LogRecord) -> str:
+        # Use caller location if available (for load_or_create messages)
+        caller_file = getattr(record, "furu_caller_file", None)
+        caller_line = getattr(record, "furu_caller_line", None)
+        if caller_file is not None and caller_line is not None:
+            filename = Path(caller_file).name
+            return f"[{filename}:{caller_line}]"
+        filename = Path(record.pathname).name if record.pathname else "<unknown>"
+        return f"[{filename}:{record.lineno}]"
+
+    @staticmethod
+    def _format_message_text(record: logging.LogRecord) -> Text:
+        message = _strip_load_or_create_decision_suffix(record.getMessage())
+        action_color = getattr(record, "furu_action_color", None)
+        if isinstance(action_color, str) and message.startswith(_LOAD_OR_CREATE_PREFIX):
+            prefix = _LOAD_OR_CREATE_PREFIX
+            rest = message[len(prefix) :]
+            text = Text()
+            text.append(prefix, style=action_color)
+            text.append(rest)
+            return text
+        return Text(message)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        level_style = self._level_style(record.levelno)
+        timestamp = datetime.datetime.fromtimestamp(
+            record.created, tz=datetime.timezone.utc
+        ).strftime("%H:%M:%S")
+
+        location = self._format_location(record)
+
+        line = Text()
+        line.append(timestamp, style="dim")
+        line.append(" ")
+        line.append(location, style=level_style)
+        line.append(" ")
+        line.append_text(self._format_message_text(record))
+
+        with _FURU_CONSOLE_LOCK:
+            self._console.print(line)
+
+        if record.exc_info:
+            from rich.traceback import Traceback  # type: ignore
+
+            exc_type, exc_value, tb = record.exc_info
+            if exc_type is not None and exc_value is not None and tb is not None:
+                with _FURU_CONSOLE_LOCK:
+                    self._console.print(
+                        Traceback.from_exception(
+                            exc_type, exc_value, tb, show_locals=False
+                        )
+                    )
+
+    @staticmethod
+    def _level_style(levelno: int) -> str:
+        if levelno >= logging.ERROR:
+            return "red"
+        if levelno >= logging.WARNING:
+            return "yellow"
+        if levelno >= logging.INFO:
+            return "blue"
+        return "magenta"
+
+
+def configure_logging() -> None:
+    """
+    Install context-aware file logging + rich console logging (idempotent).
+
+    With this installed, any stdlib logger (e.g. `logging.getLogger(__name__)`)
+    that propagates to the root logger will be written to the current holder's
+    `furu.log` while a holder is active.
+    """
+    root = logging.getLogger()
+    if not any(isinstance(h, _FuruContextFileHandler) for h in root.handlers):
+        handler = _FuruContextFileHandler(level=logging.DEBUG)
+        handler.addFilter(_FuruScopeFilter())
+        handler.addFilter(_FuruFileFilter())
+        handler.setFormatter(
+            _FuruLogFormatter(
+                "%(asctime)s [%(levelname)s] %(name)s %(filename)s:%(lineno)d %(message)s"
+            )
+        )
+        root.addHandler(handler)
+
+    if not any(isinstance(h, _FuruRichConsoleHandler) for h in root.handlers):
+        console = _FuruRichConsoleHandler(level=_console_level())
+        console.addFilter(_FuruConsoleFilter())
+        root.addHandler(console)
+
+
+def get_logger() -> logging.Logger:
+    """
+    Return the default furu logger.
+
+    It is configured with a context-aware file handler that routes log records to
+    the current holder's directory (see `enter_holder()`).
+    """
+    configure_logging()
+    logger = logging.getLogger("furu")
+    logger.setLevel(logging.DEBUG)
+    return logger
+
+
+def log(message: str, *, level: str = "INFO") -> Path:
+    """
+    Log a message to the current holder's `furu.log` via stdlib `logging`.
+
+    If no holder is active, logs to `FURU_CONFIG.base_root / "furu.log"`.
+    Returns the path written to.
+    """
+    directory = current_log_dir()
+    log_path = directory / "furu.log"
+
+    level_no = logging.getLevelNamesMapping().get(level.upper())
+    if level_no is None:
+        raise ValueError(f"Unknown log level: {level!r}")
+
+    configure_logging()
+    get_logger().log(level_no, message)
+    return log_path
+
+
+def write_separator(line: str = "------------------") -> Path:
+    """
+    Write a raw separator line to the current holder's `furu.log`.
+
+    This bypasses standard formatting so repeated `load_or_create()` calls are easy to spot.
+    """
+    directory = current_log_dir()
+    log_path = directory / "furu.log"
+
+    directory.mkdir(parents=True, exist_ok=True)
+
+    with _FURU_LOG_LOCK:
+        with log_path.open("a", encoding="utf-8") as fp:
+            fp.write(f"{line}\n")
+    return log_path

furu/runtime/tracebacks.py

@@ -0,0 +1,64 @@
+import io
+import os
+
+from rich.console import Console
+from rich.traceback import Traceback
+
+
+def format_traceback(exc: BaseException) -> str:
+    """
+    Format an exception traceback for writing to logs.
+
+    Uses Rich traceback (box-drawn, readable).
+    """
+    buffer = io.StringIO()
+    console = Console(file=buffer, record=True, width=120)
+    tb = Traceback.from_exception(
+        type(exc),
+        exc,
+        exc.__traceback__,
+        show_locals=False,
+        width=120,
+        extra_lines=3,
+        theme="monokai",
+        word_wrap=False,
+    )
+    console.print(tb)
+    return console.export_text(styles=False).rstrip()
+
+
+def _print_colored_traceback(exc: BaseException) -> None:
+    """
+    Print a full, colored traceback to stderr.
+    Uses rich for pretty formatting.
+    """
+    console = Console(stderr=True)
+    tb = Traceback.from_exception(
+        type(exc),
+        exc,
+        exc.__traceback__,
+        show_locals=False,  # flip True if you want locals
+        width=None,  # auto width
+        extra_lines=3,  # a bit more context
+        theme="monokai",  # pick your fave; 'ansi_dark' is nice too
+        word_wrap=False,
+    )
+    console.print(tb)
+
+
+def _install_rich_uncaught_exceptions() -> None:
+    from rich.traceback import install as _rich_install  # type: ignore
+
+    _rich_install(show_locals=False)
+
+
+_RICH_UNCAUGHT_ENABLED = os.getenv("FURU_RICH_UNCAUGHT_TRACEBACKS", "").lower() in {
+    "",
+    "1",
+    "true",
+    "yes",
+}
+
+# Enable rich tracebacks for uncaught exceptions by default (opt-out via env var).
+if _RICH_UNCAUGHT_ENABLED:
+    _install_rich_uncaught_exceptions()

furu/serialization/__init__.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel
+
+from .migrations import (
+    FieldAdd,
+    FieldRename,
+    MIGRATION_REGISTRY,
+    MigrationSpec,
+    Transform,
+)
+from .serializer import FuruSerializer
+
+__all__ = [
+    "BaseModel",
+    "FieldAdd",
+    "FieldRename",
+    "FuruSerializer",
+    "MIGRATION_REGISTRY",
+    "MigrationSpec",
+    "Transform",
+]

furu/serialization/migrations.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Generic, TypeVar
+
+from ..runtime.logging import get_logger
+from .serializer import JsonValue
+
+
+_T = TypeVar("_T")
+
+
+@dataclass(frozen=True)
+class MigrationContext:
+    fields: dict[str, JsonValue]
+    from_class: str
+    to_class: str
+    from_version: float
+    to_version: float
+
+
+@dataclass(frozen=True)
+class FieldRename:
+    old: str
+    new: str
+
+
+@dataclass(frozen=True)
+class FieldAdd(Generic[_T]):
+    name: str
+    default: _T | None = None
+    default_factory: Callable[[MigrationContext], _T] | None = None
+
+
+@dataclass(frozen=True)
+class Transform:
+    func: Callable[[dict[str, JsonValue]], dict[str, JsonValue]]
+
+
+MigrationStep = FieldRename | FieldAdd[JsonValue] | Transform
+
+
+@dataclass(frozen=True)
+class MigrationSpec:
+    from_class: str
+    from_version: float
+    to_version: float
+    steps: list[MigrationStep]
+    to_class: str | None = None
+    note: str | None = None
+
+    def default_value_for(self, name: str, data: dict[str, JsonValue]) -> JsonValue:
+        for step in self.steps:
+            if isinstance(step, FieldAdd) and step.name == name:
+                if step.default_factory is None:
+                    return step.default
+                context = MigrationContext(
+                    fields={k: v for k, v in data.items() if k != "__class__"},
+                    from_class=self.from_class,
+                    to_class=self.to_class or self.from_class,
+                    from_version=self.from_version,
+                    to_version=self.to_version,
+                )
+                return step.default_factory(context)
+        return None
+
+
+class MigrationRegistry:
+    def __init__(self) -> None:
+        self._specs: dict[tuple[str, float], MigrationSpec] = {}
+
+    def register(
+        self, spec: MigrationSpec, *, default_to_class: str | None = None
+    ) -> None:
+        to_class = spec.to_class or default_to_class
+        if to_class is None:
+            raise ValueError("MigrationSpec.to_class is required")
+        key = (spec.from_class, spec.from_version)
+        if key in self._specs:
+            raise ValueError(
+                f"Duplicate migration for {spec.from_class}@{spec.from_version}"
+            )
+        normalized = MigrationSpec(
+            from_class=spec.from_class,
+            from_version=spec.from_version,
+            to_version=spec.to_version,
+            steps=spec.steps,
+            to_class=to_class,
+            note=spec.note,
+        )
+        self._specs[key] = normalized
+
+    def resolve_chain(
+        self,
+        *,
+        from_class: str,
+        from_version: float,
+        to_class: str | None = None,
+        to_version: float | None = None,
+    ) -> list[MigrationSpec]:
+        chain: list[MigrationSpec] = []
+        current_class = from_class
+        current_version = from_version
+        visited: set[tuple[str, float]] = set()
+
+        while True:
+            key = (current_class, current_version)
+            if key in visited:
+                raise ValueError(
+                    f"Migration loop detected for {current_class}@{current_version}"
+                )
+            visited.add(key)
+
+            spec = self._specs.get(key)
+            if spec is None:
+                break
+            chain.append(spec)
+            current_class = spec.to_class or spec.from_class
+            current_version = spec.to_version
+
+            if to_class is not None and to_version is not None:
+                if current_class == to_class and current_version == to_version:
+                    break
+
+        if to_class is not None and to_version is not None:
+            if current_class != to_class or current_version != to_version:
+                raise ValueError(
+                    f"No migration path from {from_class}@{from_version} to {to_class}@{to_version}"
+                )
+
+        if len(chain) > 1:
+            get_logger().warning(
+                "migration: chain length %s from %s@%s",
+                len(chain),
+                from_class,
+                from_version,
+            )
+        return chain
+
+    def apply_chain(
+        self,
+        data: dict[str, JsonValue],
+        *,
+        to_class: str | None = None,
+        to_version: float | None = None,
+    ) -> tuple[dict[str, JsonValue], list[MigrationSpec]]:
+        from_class = _require_class_name(data)
+        from_version = _get_version(data)
+        chain = self.resolve_chain(
+            from_class=from_class,
+            from_version=from_version,
+            to_class=to_class,
+            to_version=to_version,
+        )
+        result = dict(data)
+        for spec in chain:
+            result = _apply_spec(result, spec)
+        result = _apply_nested_migrations(result, registry=self)
+        return result, chain
+
+    def has_migration(self, from_class: str, from_version: float) -> bool:
+        return (from_class, from_version) in self._specs
+
+
+MIGRATION_REGISTRY = MigrationRegistry()
+
+
+def _require_class_name(data: dict[str, JsonValue]) -> str:
+        class_name = data.get("__class__")
+        if not isinstance(class_name, str):
+            raise ValueError("Serialized Furu object missing __class__")
+        return class_name
+
+
+def _get_version(data: dict[str, JsonValue]) -> float:
+    version_value = data.get("furu_version")
+    if isinstance(version_value, (float, int)):
+        return float(version_value)
+    return 0.0
+
+
+def _apply_spec(
+    data: dict[str, JsonValue], spec: MigrationSpec
+) -> dict[str, JsonValue]:
+    result = dict(data)
+    result["__class__"] = spec.to_class or spec.from_class
+
+    for step in spec.steps:
+        if isinstance(step, FieldRename):
+            if step.old in result:
+                result[step.new] = result.pop(step.old)
+            continue
+
+        if isinstance(step, FieldAdd):
+            if step.name not in result:
+                context = MigrationContext(
+                    fields={k: v for k, v in result.items() if k != "__class__"},
+                    from_class=spec.from_class,
+                    to_class=result["__class__"],
+                    from_version=spec.from_version,
+                    to_version=spec.to_version,
+                )
+                if step.default_factory is not None:
+                    result[step.name] = step.default_factory(context)
+                else:
+                    result[step.name] = step.default
+            continue
+
+        if isinstance(step, Transform):
+            result = step.func(result)
+            continue
+
+        raise TypeError(f"Unsupported migration step: {step}")
+
+    result["furu_version"] = spec.to_version
+    return result
+
+
+def _apply_nested_migrations(
+    data: dict[str, JsonValue], *, registry: MigrationRegistry
+) -> dict[str, JsonValue]:
+    result: dict[str, JsonValue] = {}
+    for key, value in data.items():
+        if isinstance(value, dict) and "__class__" in value:
+            nested = value
+            if registry.has_migration(
+                _require_class_name(nested), _get_version(nested)
+            ):
+                migrated, _ = registry.apply_chain(nested)
+                result[key] = migrated
+                continue
+            result[key] = _apply_nested_migrations(nested, registry=registry)
+            continue
+        if isinstance(value, list):
+            result[key] = [
+                _apply_nested_migrations(item, registry=registry)
+                if isinstance(item, dict)
+                else item
+                for item in value
+            ]
+            continue
+        if isinstance(value, dict):
+            result[key] = _apply_nested_migrations(value, registry=registry)
+            continue
+        result[key] = value
+    return result