resolvescript 0.1.2__py3-none-any.whl

resolve_script/sandbox/api.py

@@ -0,0 +1,393 @@
+"""Mock DaVinci Resolve / Fusion API objects for headless development.
+
+The classes here mirror the surface area a Resolve script actually touches:
+Resolve connection, project management, timelines, clips, the media pool,
+and a Fusion comp (tools, splines, strokes). They are intentionally small —
+enough to be useful, not a full emulation.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+_SPLINE_TYPES = ("BSpline", "Polyline")
+
+
+class FakeResolve:
+    def __init__(self, project_manager: Any):
+        self._pm = project_manager
+
+    def GetProjectManager(self) -> Any:
+        return self._pm
+
+    def __repr__(self) -> str:
+        return "<FakeResolve>"
+
+
+class FakeFusion:
+    def __init__(self, comp: Any):
+        self._comp = comp
+
+    def GetCurrentComp(self) -> Any:
+        return self._comp
+
+    def __repr__(self) -> str:
+        return "<FakeFusion>"
+
+
+class FakeProjectManager:
+    def __init__(self, projects: dict[str, Any], current: str):
+        self._projects = projects
+        self._current = current
+
+    def GetCurrentProject(self) -> Any:
+        return self._projects.get(self._current)
+
+    def GetProject(self, name: str) -> Any | None:
+        return self._projects.get(name)
+
+    def GetProjectList(self) -> list[str]:
+        return list(self._projects)
+
+    def __repr__(self) -> str:
+        return f"<FakeProjectManager projects={list(self._projects)}>"
+
+
+class FakeProject:
+    def __init__(self, name: str, timelines: list[Any], media_pool: Any):
+        self._name = name
+        self._timelines = timelines
+        self._media_pool = media_pool
+        self._current = 0
+
+    def GetName(self) -> str:
+        return self._name
+
+    def GetTimelineCount(self) -> int:
+        return len(self._timelines)
+
+    def GetTimelineByIndex(self, index: int) -> Any:
+        return self._timelines[index - 1]
+
+    def GetTimelineByName(self, name: str) -> Any | None:
+        for timeline in self._timelines:
+            if timeline.GetName() == name:
+                return timeline
+        return None
+
+    def GetCurrentTimeline(self) -> Any:
+        return self._timelines[self._current]
+
+    def GetMediaPool(self) -> Any:
+        return self._media_pool
+
+    def GetRenderJobList(self) -> list[Any]:
+        return []
+
+    def __repr__(self) -> str:
+        return f"<FakeProject {self._name!r}>"
+
+
+class FakeTimeline:
+    def __init__(
+        self,
+        name: str,
+        start_frame: int,
+        end_frame: int,
+        fps: float,
+        video_tracks: list[list[Any]],
+        audio_tracks: list[list[Any]],
+    ):
+        self._name = name
+        self._start = start_frame
+        self._end = end_frame
+        self._fps = fps
+        self._video = video_tracks
+        self._audio = audio_tracks
+        self._tc = "01:00:00:00"
+
+    def GetName(self) -> str:
+        return self._name
+
+    def GetStartFrame(self) -> int:
+        return self._start
+
+    def GetEndFrame(self) -> int:
+        return self._end
+
+    def GetSetting(self, key: str) -> Any:
+        if key == "timelineFrameRate":
+            return self._fps
+        return None
+
+    def GetTrackCount(self, track_type: str) -> int:
+        return len(self._video if track_type == "video" else self._audio)
+
+    def GetItemListInTrack(self, track_type: str, track_index: int) -> list[Any]:
+        tracks = self._video if track_type == "video" else self._audio
+        if track_index < 1 or track_index > len(tracks):
+            return []
+        return list(tracks[track_index - 1])
+
+    def GetTrackName(self, track_type: str, track_index: int) -> str:
+        return f"{track_type.capitalize()} Track {track_index}"
+
+    def SetCurrentTimecode(self, timecode: str) -> bool:
+        self._tc = timecode
+        return True
+
+    def GetCurrentTimecode(self) -> str:
+        return self._tc
+
+    def __repr__(self) -> str:
+        return f"<FakeTimeline {self._name!r}>"
+
+
+class FakeClip:
+    def __init__(self, name: str, start: int, end: int, media_item: Any):
+        self._name = name
+        self._start = start
+        self._end = end
+        self._item = media_item
+        self._comps: list[Any] = []
+
+    def GetName(self) -> str:
+        return self._name
+
+    def GetStart(self) -> int:
+        return self._start
+
+    def GetEnd(self) -> int:
+        return self._end
+
+    def GetDuration(self) -> int:
+        return self._end - self._start + 1
+
+    def GetMediaPoolItem(self) -> Any:
+        return self._item
+
+    def GetFusionCompCount(self) -> int:
+        return len(self._comps)
+
+    def GetFusionCompByIndex(self, index: int) -> Any | None:
+        if 1 <= index <= len(self._comps):
+            return self._comps[index - 1]
+        return None
+
+    def AddFusionComp(self) -> Any:
+        comp = FakeComp(f"{self._name} Comp {len(self._comps) + 1}")
+        self._comps.append(comp)
+        return comp
+
+    def __repr__(self) -> str:
+        return f"<FakeClip {self._name!r}>"
+
+
+class FakeMediaPoolItem:
+    def __init__(self, name: str, props: dict[str, str] | None = None):
+        self._name = name
+        self._props = props or {"FPS": "24", "Duration": "100", "Width": "1920", "Height": "1080"}
+
+    def GetName(self) -> str:
+        return self._name
+
+    def GetClipProperty(self, key: str) -> str | None:
+        return self._props.get(key)
+
+    def SetClipProperty(self, key: str, value: str) -> bool:
+        self._props[key] = value
+        return True
+
+    def __repr__(self) -> str:
+        return f"<FakeMediaPoolItem {self._name!r}>"
+
+
+class FakeFolder:
+    def __init__(self, name: str, clips: list[Any], subfolders: list[Any] | None = None):
+        self._name = name
+        self._clips = clips
+        self._subfolders = subfolders or []
+
+    def GetName(self) -> str:
+        return self._name
+
+    def GetClipList(self) -> list[Any]:
+        return list(self._clips)
+
+    def GetSubFolderList(self) -> list[Any]:
+        return list(self._subfolders)
+
+
+class FakeMediaPool:
+    def __init__(self, root: Any):
+        self._root = root
+
+    def GetRootFolder(self) -> Any:
+        return self._root
+
+    def ImportMedia(self, file_paths: list[str]) -> list[Any]:
+        return [FakeMediaPoolItem(Path(p).stem) for p in file_paths]
+
+
+class FakeKey:
+    def __init__(self, frame: int, x: float, y: float):
+        self.Frame = frame
+        self.X = x
+        self.Y = y
+
+
+class FakeSpline:
+    def __init__(self) -> None:
+        self._keys: dict[int, FakeKey] = {}
+
+    def AddKey(self, frame: int, value: dict[str, float]) -> None:
+        self._keys[frame] = FakeKey(frame, value.get("X", 0.0), value.get("Y", 0.0))
+
+    def DeleteKey(self, frame: int) -> None:
+        self._keys.pop(frame, None)
+
+    def DeleteAllKeys(self) -> None:
+        self._keys.clear()
+
+    def GetKeyCount(self) -> int:
+        return len(self._keys)
+
+    def GetKey(self, index: int) -> FakeKey:
+        ordered = sorted(self._keys.values(), key=lambda k: k.Frame)
+        return ordered[index]
+
+
+class FakeStroke:
+    def __init__(self, number: int):
+        self._attrs = {
+            "TOOLS_Name": f"Stroke_{number}",
+            "BrushType": "Stroke",
+            "BrushColor": (1.0, 1.0, 1.0, 1.0),
+            "BrushSize": 10.0,
+            "TOOLB_StartFrame": 0,
+            "TOOLB_EndFrame": 0,
+        }
+        self._points: list[tuple[float, float, float]] = []
+
+    def SetAttrs(self, attrs: dict[str, Any]) -> None:
+        self._attrs.update(attrs)
+
+    def GetAttrs(self) -> dict[str, Any]:
+        return dict(self._attrs)
+
+    def AddPoint(self, x: float, y: float, frame: float) -> None:
+        self._points.append((x, y, frame))
+        int_frame = int(frame)
+        prev_start = self._attrs.get("TOOLB_StartFrame") or int_frame
+        prev_end = self._attrs.get("TOOLB_EndFrame") or int_frame
+        self._attrs["TOOLB_StartFrame"] = min(prev_start, int_frame)
+        self._attrs["TOOLB_EndFrame"] = max(prev_end, int_frame)
+
+
+class FakeTool:
+    def __init__(self, regid: str, name: str, x: float, y: float):
+        self._attrs = {
+            "TOOLS_Name": name,
+            "TOOLS_RegID": regid,
+            "TOOLS_PosX": x,
+            "TOOLS_PosY": y,
+        }
+        self._spline = FakeSpline() if regid in _SPLINE_TYPES else None
+        self._strokes: dict[str, Any] = {}
+
+    def GetAttrs(self) -> dict[str, Any]:
+        return dict(self._attrs)
+
+    def SetAttrs(self, attrs: dict[str, Any]) -> None:
+        self._attrs.update(attrs)
+
+    def GetInput(self, name: str) -> Any:
+        return self._spline if name == "Spline" else None
+
+    def GetInputList(self) -> dict[str, Any]:
+        return {}
+
+    def GetOutputList(self) -> dict[str, Any]:
+        return {}
+
+    def SetInput(self, index: int | str, value: Any) -> bool:
+        return True
+
+    def ConnectInput(self, index: int | str, source: Any) -> bool:
+        self._attrs.setdefault("_connected", {})[index] = source
+        return True
+
+    def AddStroke(self) -> Any:
+        stroke = FakeStroke(len(self._strokes) + 1)
+        self._strokes[f"Stroke{len(self._strokes) + 1}"] = stroke
+        return stroke
+
+    def GetStrokeList(self) -> dict[str, Any]:
+        return dict(self._strokes)
+
+    def DeleteStroke(self, stroke: Any) -> None:
+        for key, value in list(self._strokes.items()):
+            if value is stroke:
+                del self._strokes[key]
+
+    def __repr__(self) -> str:
+        return f"<FakeTool {self._attrs['TOOLS_Name']!r} {self._attrs['TOOLS_RegID']}>"
+
+
+class FakeComp:
+    def __init__(
+        self,
+        name: str,
+        width: int = 1920,
+        height: int = 1080,
+        fps: float = 24.0,
+        start: int = 0,
+        end: int = 100,
+    ):
+        self._attrs = {
+            "COMPS_Name": name,
+            "COMPS_Width": width,
+            "COMPS_Height": height,
+            "COMPS_FrameRate": fps,
+            "COMPS_RenderStart": start,
+            "COMPS_RenderEnd": end,
+        }
+        self._tools: dict[str, Any] = {}
+        self._counters: dict[str, int] = {}
+
+    def GetAttrs(self) -> dict[str, Any]:
+        return dict(self._attrs)
+
+    def SetAttrs(self, attrs: dict[str, Any]) -> None:
+        self._attrs.update(attrs)
+
+    def GetToolList(self, tool_type: str | None = None) -> dict[str, Any]:
+        if tool_type is None:
+            return dict(self._tools)
+        return {
+            name: tool
+            for name, tool in self._tools.items()
+            if tool.GetAttrs()["TOOLS_RegID"] == tool_type
+        }
+
+    def AddTool(self, tool_type: str, x: float = 0, y: float = 0) -> Any:
+        self._counters[tool_type] = self._counters.get(tool_type, 0) + 1
+        name = f"{tool_type}{self._counters[tool_type]}"
+        tool = FakeTool(tool_type, name, x, y)
+        self._tools[name] = tool
+        return tool
+
+    def DeleteTool(self, tool: Any) -> None:
+        for key, value in list(self._tools.items()):
+            if value is tool:
+                del self._tools[key]
+
+    def Save(self, path: str | None = None) -> bool:
+        return True
+
+    def Close(self) -> None:
+        pass
+
+    def __repr__(self) -> str:
+        return f"<FakeComp {self._attrs['COMPS_Name']!r}>"

resolve_script/sandbox/env.py

@@ -0,0 +1,82 @@
+"""Environment injection: build a mock Resolve session and install it.
+
+``install_fake_resolve`` registers a fake ``DaVinciResolveScript`` module in
+``sys.modules`` so any extension that does ``import DaVinciResolveScript`` runs
+headless. It is idempotent — calling it again just replaces the module.
+"""
+
+from __future__ import annotations
+
+import sys
+from types import ModuleType
+from typing import Any
+
+from .api import (
+    FakeClip,
+    FakeComp,
+    FakeFolder,
+    FakeFusion,
+    FakeMediaPool,
+    FakeMediaPoolItem,
+    FakeProject,
+    FakeProjectManager,
+    FakeResolve,
+    FakeTimeline,
+)
+
+FUSION_SCRIPT_MODULE = "DaVinciResolveScript"
+
+DEFAULT_PROJECT = "Demo Project"
+
+
+def build_default_env() -> tuple[FakeResolve, FakeFusion]:
+    """Create a realistic mock session with clips, timelines and a Fusion comp."""
+    items = {f"Shot {i}": FakeMediaPoolItem(f"Shot {i}") for i in range(1, 7)}
+
+    def _clip(name: str, start: int, end: int) -> FakeClip:
+        return FakeClip(name, start, end, items[name])
+
+    video_1 = [
+        _clip("Shot 1", 1001, 1040),
+        None,
+        _clip("Shot 3", 1061, 1100),
+    ]
+    video_2 = [
+        _clip("Shot 2", 1001, 1040),
+        _clip("Shot 4", 1120, 1180),
+    ]
+    audio_1 = [
+        _clip("Shot 5", 1001, 1080),
+        _clip("Shot 6", 1081, 1180),
+    ]
+
+    timeline_1 = FakeTimeline("Main Timeline", 1001, 1200, 24.0, [video_1, video_2], [audio_1])
+    timeline_2 = FakeTimeline("Alt Timeline", 2001, 3000, 24.0, [video_2], [audio_1])
+
+    root = FakeFolder("Master", list(items.values()))
+    media_pool = FakeMediaPool(root)
+    project = FakeProject(DEFAULT_PROJECT, [timeline_1, timeline_2], media_pool)
+    pm = FakeProjectManager({DEFAULT_PROJECT: project}, DEFAULT_PROJECT)
+
+    resolve = FakeResolve(pm)
+    fusion = FakeFusion(FakeComp("Comp 1", start=1001, end=1200))
+    return resolve, fusion
+
+
+def fake_resolve_module() -> ModuleType:
+    """Build (but do not install) a fake DaVinciResolveScript module."""
+    resolve, fusion = build_default_env()
+    module = ModuleType(FUSION_SCRIPT_MODULE)
+
+    def _scriptapp(kind: str) -> Any:
+        return resolve if kind == "Resolve" else fusion
+
+    module.scriptapp = _scriptapp  # type: ignore[attr-defined]
+    return module
+
+
+def install_fake_resolve() -> ModuleType:
+    """Register the fake DaVinciResolveScript module (idempotent)."""
+    module = fake_resolve_module()
+    sys.modules[FUSION_SCRIPT_MODULE] = module
+    return module

resolve_script/sandbox/loader.py

@@ -0,0 +1,72 @@
+"""Module loading helpers: source packages and consolidated single files."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+
+def purge_module(prefix: str) -> None:
+    """Remove a module (and its submodules) from ``sys.modules``."""
+    for key in [k for k in list(sys.modules) if k == prefix or k.startswith(prefix + ".")]:
+        del sys.modules[key]
+    importlib.invalidate_caches()
+
+
+def _entry_file(module_name: str, package_dir: Path) -> tuple[Path, str | None]:
+    """Locate the on-disk entry file for ``module_name``.
+
+    Returns ``(file, package)`` where ``package`` is the package name for a
+    ``__init__.py`` entry (drives ``__package__``/``__path__``) or ``None`` for
+    a single-file module.
+    """
+    package_dir = Path(package_dir)
+    rel_dotted = module_name.replace(".", "/")
+    init = package_dir / rel_dotted / "__init__.py"
+    if init.is_file():
+        return init, module_name
+    single = package_dir / f"{rel_dotted}.py"
+    if single.is_file():
+        return single, None
+    raise ImportError(f"cannot find entrypoint for module '{module_name}' under {package_dir}")
+
+
+def load_source_module(module_name: str, package_dir: Path) -> ModuleType:
+    """Import ``module_name`` fresh from ``package_dir``.
+
+    The entry file is compiled directly from source (bypassing the bytecode
+    cache) so re-installs and rebuilds always see the current code.
+    """
+    purge_module(module_name)
+    package_dir = Path(package_dir).resolve()
+    if str(package_dir) not in sys.path:
+        sys.path.insert(0, str(package_dir))
+
+    file_path, package = _entry_file(module_name, package_dir)
+    module = ModuleType(module_name)
+    module.__file__ = str(file_path)
+    module.__package__ = package or ""
+    if package:
+        module.__path__ = [str(file_path.parent)]
+    code = compile(file_path.read_text(encoding="utf-8"), str(file_path), "exec")
+    sys.modules[module_name] = module
+    exec(code, module.__dict__)
+    return module
+
+
+def load_built_module(module_name: str, built_file: Path) -> ModuleType:
+    """Import a consolidated single-file build under ``module_name``."""
+    purge_module(module_name)
+    built_file = Path(built_file).resolve()
+    if not built_file.is_file():
+        raise FileNotFoundError(f"built package not found: {built_file}")
+    spec = importlib.util.spec_from_file_location(module_name, built_file)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load {built_file} as a Python module")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module

resolve_script/sandbox/repl.py

@@ -0,0 +1,57 @@
+"""Interactive REPL namespace for the sandbox."""
+
+from __future__ import annotations
+
+import code
+from types import ModuleType
+from typing import Any
+
+from .api import FakeProject, FakeResolve
+
+
+def _collect_clips(project: FakeProject) -> list[Any]:
+    clips: list[Any] = []
+    seen: set[int] = set()
+    for index in range(1, project.GetTimelineCount() + 1):
+        timeline = project.GetTimelineByIndex(index)
+        for track in range(1, timeline.GetTrackCount("video") + 1):
+            for clip in timeline.GetItemListInTrack("video", track):
+                if clip is None or id(clip) in seen:
+                    continue
+                seen.add(id(clip))
+                clips.append(clip)
+    return clips
+
+
+def default_namespace(module: ModuleType, resolve: FakeResolve | None = None) -> dict[str, Any]:
+    """Build the interactive namespace: ``resolve``, ``project``, ``timeline``,
+    ``clips`` and the loaded module under its own name."""
+    if resolve is None:
+        import sys
+
+        from .env import FUSION_SCRIPT_MODULE
+
+        dvr = sys.modules.get(FUSION_SCRIPT_MODULE)
+        resolve = dvr.scriptapp("Resolve") if dvr is not None else None  # type: ignore[attr-defined]
+    namespace: dict[str, Any] = {}
+    if resolve is not None:
+        namespace["resolve"] = resolve
+        project = resolve.GetProjectManager().GetCurrentProject()
+        if project is not None:
+            namespace["project"] = project
+            namespace["timeline"] = project.GetCurrentTimeline()
+            namespace["clips"] = _collect_clips(project)
+    namespace[module.__name__] = module
+    return namespace
+
+
+def start_repl(module: ModuleType, resolve: FakeResolve | None = None) -> None:
+    """Drop into an interactive interpreter with a live mock session."""
+    namespace = default_namespace(module, resolve)
+    banner = (
+        "\nInteractive sandbox. Available:\n"
+        f"  {module.__name__}  - the package under test\n"
+        "  resolve / project / timeline\n"
+        "  clips      - list of clips across the timeline video tracks\n"
+    )
+    code.interact(local=namespace, banner=banner)

resolve_script/sandbox/smoke.py

@@ -0,0 +1,104 @@
+"""Generic smoke checks for any Resolve script package.
+
+``run_smoke`` walks the package's public API (or an explicit list of export
+names) and calls every zero-arg callable against the injected mock Resolve
+environment. Any callable that raises is reported as a failure; functions that
+require arguments are skipped by design.
+"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from types import ModuleType
+from typing import Any, Callable
+
+_REQUIRED = (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+
+
+@dataclass
+class SmokeCheck:
+    name: str
+    ok: bool
+    detail: str = "ok"
+
+
+@dataclass
+class SmokeResult:
+    checks: list[SmokeCheck] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return all(check.ok for check in self.checks)
+
+    @property
+    def failed(self) -> int:
+        return sum(0 if check.ok else 1 for check in self.checks)
+
+    def __len__(self) -> int:
+        return len(self.checks)
+
+
+def callable_without_args(obj: Any) -> bool:
+    """True if ``obj`` is a plain callable that takes no required arguments."""
+    if inspect.isclass(obj):
+        return False
+    if not callable(obj):
+        return False
+    try:
+        signature = inspect.signature(obj)
+    except (TypeError, ValueError):
+        return False
+    for param in signature.parameters.values():
+        if param.kind in _REQUIRED and param.default is inspect.Parameter.empty:
+            return False
+    return True
+
+
+def discover_exports(module: ModuleType) -> dict[str, Callable[..., Any]]:
+    """Public zero-arg callables of a module (in ``dir()`` order)."""
+    exports: dict[str, Callable[..., Any]] = {}
+    for name in dir(module):
+        if name.startswith("_"):
+            continue
+        obj = getattr(module, name)
+        if isinstance(obj, ModuleType):
+            continue
+        if callable_without_args(obj):
+            exports[name] = obj
+    return exports
+
+
+def run_smoke(module: ModuleType, exports: list[str] | None = None, verbose: bool = False) -> SmokeResult:
+    """Exercise ``module``'s public API against the mock environment.
+
+    When ``exports`` is given it selects named attributes; otherwise the
+    module's public zero-arg callables are discovered automatically.
+    """
+    names = exports if exports is not None else sorted(discover_exports(module))
+    result = SmokeResult()
+
+    def _check(name: str, fn: Any) -> None:
+        try:
+            fn()
+        except Exception as exc:  # noqa: BLE001 - a smoke run must not abort
+            result.checks.append(SmokeCheck(name, False, f"{type(exc).__name__}: {exc}"))
+        else:
+            result.checks.append(SmokeCheck(name, True, "ok"))
+
+    for name in names:
+        attr = getattr(module, name, None)
+        if attr is None or not callable(attr):
+            result.checks.append(SmokeCheck(name, False, f"missing export '{name}'"))
+            continue
+        if not callable_without_args(attr):
+            result.checks.append(SmokeCheck(name, True, "skipped (requires arguments)"))
+            continue
+        _check(name, attr)
+
+    if verbose:
+        for check in result.checks:
+            tag = "PASS" if check.ok else "FAIL"
+            print(f"  [{tag}] {check.name}  ({check.detail})")
+        print(f"\n{len(result) - result.failed}/{len(result)} checks passed")
+    return result