blendiff 0.2.0__py3-none-any.whl

blendiff/__init__.py

@@ -0,0 +1,40 @@
+"""
+BlenDiff — semantic diff, snapshot history, and assisted merge for .blend files.
+
+When imported outside Blender (e.g. via pip), only the pure-Python core is
+available: data_model, diff_engine, serializer, storage, export, cli.
+
+When imported inside Blender, the full addon registers its UI panels and
+operators on top of the core.
+"""
+
+__version__ = "0.2.0"
+
+bl_info = {
+	"name":        "BlenDiff",
+	"author":      "Vishrut",
+	"version":     (0, 2, 0),
+	"blender":     (3, 6, 0),
+	"location":    "3D Viewport > Sidebar > BlenDiff",
+	"description": "Semantic scene diff, snapshot history, and assisted merge for .blend files",
+	"category":    "Scene",
+}
+
+try:
+	import bpy
+	_IN_BLENDER = True
+except ModuleNotFoundError:
+	_IN_BLENDER = False
+
+if _IN_BLENDER:
+	from .ui import panels, operators, merge_panel
+
+	def register() -> None:
+		operators.register()
+		panels.register()
+		merge_panel.register()
+
+	def unregister() -> None:
+		merge_panel.unregister()
+		panels.unregister()
+		operators.unregister()

blendiff/cli/__init__.py

@@ -0,0 +1,6 @@
+from .api import (
+	list_snapshots,
+	compare_snapshots,
+	compare_snapshots_by_label,
+	compare_latest_two,
+)

blendiff/cli/__main__.py

@@ -0,0 +1,214 @@
+"""
+blendiff.cli.__main__
+~~~~~~~~~~~~~~~~~~~~~~
+Entry point for:  python -m blendiff.cli <command> [args]
+
+Commands
+--------
+  list     <sidecar>                        List all snapshots in a sidecar
+  compare  <sidecar> <label_a> <label_b>   Diff two snapshots by label
+  latest   <sidecar>                        Diff the two most recent snapshots
+
+Global flags
+------------
+  --output <path>      Write HTML report to this path (default: print JSON)
+  --json               Print result as JSON to stdout
+  --fail-on-changes    Exit with code 1 if any changes detected (for CI gates)
+  --quiet              Suppress all output except errors
+
+Exit codes
+----------
+  0  — success, no changes (or changes detected but --fail-on-changes not set)
+  1  — changes detected and --fail-on-changes is set
+  2  — error (file not found, snapshot not found, parse failure, etc.)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def _build_parser() -> argparse.ArgumentParser:
+	parser = argparse.ArgumentParser(
+		prog="python -m blendiff.cli",
+		description="BlenDiff headless CLI — diff Blender scene snapshots without opening Blender.",
+	)
+
+	sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+	sub.required = True
+
+	# ── list ──────────────────────────────────────────────────────────────
+	p_list = sub.add_parser("list", help="List all snapshots in a .blendiff sidecar")
+	p_list.add_argument("sidecar", help="Path to the .blendiff file")
+	p_list.add_argument("--json", dest="as_json", action="store_true",
+						help="Output as JSON")
+
+	# ── compare ───────────────────────────────────────────────────────────
+	p_compare = sub.add_parser(
+		"compare",
+		help="Diff two snapshots by label (most recent match used if duplicates exist)",
+	)
+	p_compare.add_argument("sidecar", help="Path to the .blendiff file")
+	p_compare.add_argument("label_a", help="Label of the base snapshot (before)")
+	p_compare.add_argument("label_b", help="Label of the target snapshot (after)")
+	p_compare.add_argument("--output", metavar="PATH",
+						   help="Write HTML report to this path")
+	p_compare.add_argument("--json", dest="as_json", action="store_true",
+						   help="Print result as JSON to stdout")
+	p_compare.add_argument("--fail-on-changes", action="store_true",
+						   help="Exit with code 1 if changes are detected")
+	p_compare.add_argument("--quiet", action="store_true",
+						   help="Suppress output except errors")
+
+	# ── latest ────────────────────────────────────────────────────────────
+	p_latest = sub.add_parser(
+		"latest",
+		help="Diff the two most recent snapshots",
+	)
+	p_latest.add_argument("sidecar", help="Path to the .blendiff file")
+	p_latest.add_argument("--output", metavar="PATH",
+						  help="Write HTML report to this path")
+	p_latest.add_argument("--json", dest="as_json", action="store_true",
+						  help="Print result as JSON to stdout")
+	p_latest.add_argument("--fail-on-changes", action="store_true",
+						  help="Exit with code 1 if changes are detected")
+	p_latest.add_argument("--quiet", action="store_true",
+						  help="Suppress output except errors")
+
+	return parser
+
+
+def _cmd_list(args) -> int:
+	from .api import list_snapshots
+
+	try:
+		snapshots = list_snapshots(args.sidecar)
+	except FileNotFoundError as e:
+		print(f"Error: {e}", file=sys.stderr)
+		return 2
+
+	if args.as_json:
+		print(json.dumps(snapshots, indent=2))
+		return 0
+
+	if not snapshots:
+		print("No snapshots found.")
+		return 0
+
+	print(f"{'#':<4} {'Label':<30} {'Timestamp':<22} {'ID'}")
+	print("-" * 80)
+	for i, s in enumerate(snapshots, 1):
+		print(f"{i:<4} {s['label']:<30} {s['timestamp_display']:<22} {s['id'][:8]}")
+
+	return 0
+
+
+def _cmd_compare(args, use_latest: bool = False) -> int:
+	from .api import compare_snapshots_by_label, compare_latest_two
+	from ..export.html_exporter import export_to_file, build_output_path
+
+	quiet = getattr(args, "quiet", False)
+
+	try:
+		if use_latest:
+			result = compare_latest_two(args.sidecar)
+		else:
+			result = compare_snapshots_by_label(
+				args.sidecar, args.label_a, args.label_b
+			)
+	except FileNotFoundError as e:
+		print(f"Error: {e}", file=sys.stderr)
+		return 2
+	except ValueError as e:
+		print(f"Error: {e}", file=sys.stderr)
+		return 2
+
+	# JSON output
+	if getattr(args, "as_json", False):
+		print(json.dumps(result, indent=2, default=str))
+
+	# HTML output
+	elif getattr(args, "output", None):
+		output_path = args.output
+		snapshot_label = (
+			f"{result['snapshot_a']['label']} → {result['snapshot_b']['label']}"
+		)
+		export_to_file(
+			result=result,
+			snapshot_label=snapshot_label,
+			blend_filepath=args.sidecar,
+			output_path=output_path,
+		)
+		if not quiet:
+			print(f"HTML report written to: {output_path}")
+
+	# Default: human-readable summary
+	else:
+		if not quiet:
+			snap_a = result["snapshot_a"]
+			snap_b = result["snapshot_b"]
+			print(f"\nBlenDiff — comparing snapshots")
+			print(f"  Before : '{snap_a['label']}' ({snap_a['timestamp']})")
+			print(f"  After  : '{snap_b['label']}' ({snap_b['timestamp']})")
+			print(f"\n  {result['summary']}\n")
+
+			added = result["added_objects"]
+			removed = result["removed_objects"]
+			modified = result["modified_objects"]
+			col_diffs = result["collection_diffs"]
+
+			if added:
+				print(f"  Added objects ({len(added)}):")
+				for name in added:
+					print(f"    + {name}")
+
+			if removed:
+				print(f"  Removed objects ({len(removed)}):")
+				for name in removed:
+					print(f"    - {name}")
+
+			if modified:
+				print(f"  Modified objects ({len(modified)}):")
+				for obj in modified:
+					print(f"    ~ {obj['name']}")
+					for c in obj["changes"]:
+						print(f"        {c['property_path']}")
+						print(f"          {c['old_value']}  →  {c['new_value']}")
+
+			if col_diffs:
+				print(f"  Collection changes ({len(col_diffs)}):")
+				for cd in col_diffs:
+					print(f"    {cd['kind'].capitalize()}: {cd['path']}")
+
+			if not result["has_changes"]:
+				print("  No changes detected.")
+
+			print()
+
+	# Exit code
+	if getattr(args, "fail_on_changes", False) and result["has_changes"]:
+		return 1
+
+	return 0
+
+
+def main(argv=None) -> int:
+	parser = _build_parser()
+	args = parser.parse_args(argv)
+
+	if args.command == "list":
+		return _cmd_list(args)
+	elif args.command == "compare":
+		return _cmd_compare(args, use_latest=False)
+	elif args.command == "latest":
+		return _cmd_compare(args, use_latest=True)
+
+	parser.print_help()
+	return 2
+
+
+if __name__ == "__main__":
+	sys.exit(main())

blendiff/cli/api.py

@@ -0,0 +1,281 @@
+"""
+blendiff.cli.api
+~~~~~~~~~~~~~~~~~
+Pure Python API for comparing snapshots outside Blender.
+
+This module is the core of the headless/CI feature. It has:
+  - Zero bpy imports
+  - No argparse / CLI concerns
+  - No side effects — all functions return data, callers decide what to do
+
+Intended usage:
+
+	# In a script or CI pipeline
+	from blendiff.cli.api import compare_snapshots, list_snapshots
+
+	snapshots = list_snapshots("my_scene.blendiff")
+	result = compare_snapshots("my_scene.blendiff", "snap_id_a", "snap_id_b")
+	print(result["summary"])
+
+	# Or by label instead of ID
+	result = compare_snapshots_by_label(
+		"my_scene.blendiff", "Last approved", "Current"
+	)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ..storage.sidecar import SidecarManager, Snapshot
+from ..diff_engine.diff_engine import DiffEngine
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def list_snapshots(sidecar_path: str) -> list[dict]:
+	"""
+	List all snapshots in a .blendiff sidecar file.
+
+	Parameters
+	----------
+	sidecar_path:
+		Path to the .blendiff file.
+
+	Returns
+	-------
+	list of dicts with keys: id, label, timestamp, scene_name
+	Data field is excluded for brevity.
+
+	Raises
+	------
+	FileNotFoundError if sidecar_path does not exist.
+	"""
+	_require_sidecar(sidecar_path)
+	mgr = _manager_for_sidecar(sidecar_path)
+	snapshots = mgr.list_snapshots()
+	return [
+		{
+			"id": s.id,
+			"label": s.label,
+			"timestamp": s.timestamp,
+			"timestamp_display": s.timestamp_display(),
+			"scene_name": s.scene_name,
+		}
+		for s in snapshots
+	]
+
+
+def compare_snapshots(
+	sidecar_path: str,
+	snapshot_id_a: str,
+	snapshot_id_b: str,
+) -> dict:
+	"""
+	Diff two snapshots by UUID.
+
+	Parameters
+	----------
+	sidecar_path:
+		Path to the .blendiff file.
+	snapshot_id_a:
+		UUID of the base snapshot (the "before").
+	snapshot_id_b:
+		UUID of the target snapshot (the "after").
+
+	Returns
+	-------
+	dict with keys:
+		summary        — human-readable summary string
+		added_objects  — list of names
+		removed_objects — list of names
+		modified_objects — list of {name, changes: [{property_path, old_value, new_value}]}
+		collection_diffs — list of {path, kind, changes}
+		has_changes    — bool
+		snapshot_a     — {id, label, timestamp}
+		snapshot_b     — {id, label, timestamp}
+
+	Raises
+	------
+	FileNotFoundError if sidecar_path does not exist.
+	ValueError if either snapshot ID is not found.
+	"""
+	_require_sidecar(sidecar_path)
+	mgr = _manager_for_sidecar(sidecar_path)
+
+	snap_a = mgr.get_snapshot(snapshot_id_a)
+	snap_b = mgr.get_snapshot(snapshot_id_b)
+
+	if snap_a is None:
+		raise ValueError(f"Snapshot not found: {snapshot_id_a}")
+	if snap_b is None:
+		raise ValueError(f"Snapshot not found: {snapshot_id_b}")
+
+	return _run_diff(snap_a, snap_b)
+
+
+def compare_snapshots_by_label(
+	sidecar_path: str,
+	label_a: str,
+	label_b: str,
+) -> dict:
+	"""
+	Diff two snapshots by label.
+
+	If multiple snapshots share a label, the most recent one is used.
+
+	Parameters
+	----------
+	sidecar_path:
+		Path to the .blendiff file.
+	label_a:
+		Label of the base snapshot.
+	label_b:
+		Label of the target snapshot.
+
+	Returns
+	-------
+	Same structure as compare_snapshots().
+
+	Raises
+	------
+	FileNotFoundError if sidecar_path does not exist.
+	ValueError if either label is not found.
+	"""
+	_require_sidecar(sidecar_path)
+	mgr = _manager_for_sidecar(sidecar_path)
+
+	# list_snapshots() returns newest-first, so first match = most recent
+	all_snapshots = mgr.list_snapshots()
+
+	snap_a = _find_by_label(all_snapshots, label_a)
+	snap_b = _find_by_label(all_snapshots, label_b)
+
+	if snap_a is None:
+		raise ValueError(f"No snapshot found with label: '{label_a}'")
+	if snap_b is None:
+		raise ValueError(f"No snapshot found with label: '{label_b}'")
+
+	return _run_diff(snap_a, snap_b)
+
+
+def compare_latest_two(sidecar_path: str) -> dict:
+	"""
+	Diff the two most recent snapshots.
+
+	Useful for CI: "what changed since the last snapshot?"
+
+	Raises
+	------
+	FileNotFoundError if sidecar_path does not exist.
+	ValueError if fewer than 2 snapshots exist.
+	"""
+	_require_sidecar(sidecar_path)
+	mgr = _manager_for_sidecar(sidecar_path)
+	snapshots = mgr.list_snapshots()  # newest first
+
+	if len(snapshots) < 2:
+		raise ValueError(
+			f"Need at least 2 snapshots to diff, found {len(snapshots)}."
+		)
+
+	# newest = snapshots[0], second-newest = snapshots[1]
+	# We diff second-newest → newest (chronological order)
+	return _run_diff(snapshots[1], snapshots[0])
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _manager_for_sidecar(sidecar_path: str) -> SidecarManager:
+	"""
+	Build a SidecarManager from a direct sidecar path.
+
+	SidecarManager normally derives the sidecar path from a .blend path.
+	Here we already have the sidecar path, so we reconstruct a fake blend
+	path just for the manager's internal use — the actual file it reads
+	is set directly.
+	"""
+	# Derive a synthetic blend path so SidecarManager is satisfied
+	base = sidecar_path
+	if base.endswith(".blendiff"):
+		base = base[: -len(".blendiff")]
+	blend_path = base + ".blend"
+
+	mgr = SidecarManager(blend_path)
+	# Override the sidecar path to use the actual file given
+	mgr._sidecar_path = sidecar_path
+	return mgr
+
+
+def _require_sidecar(sidecar_path: str) -> None:
+	if not os.path.exists(sidecar_path):
+		raise FileNotFoundError(f"Sidecar file not found: {sidecar_path}")
+
+
+def _find_by_label(snapshots: list[Snapshot], label: str) -> Optional[Snapshot]:
+	"""Return the first (most recent) snapshot matching label."""
+	for s in snapshots:
+		if s.label == label:
+			return s
+	return None
+
+
+def _run_diff(snap_a: Snapshot, snap_b: Snapshot) -> dict:
+	"""Run DiffEngine on two Snapshot objects and return a result dict."""
+	engine = DiffEngine()
+	diff = engine.compare(snap_a.data, snap_b.data)
+	s = diff.summary()
+
+	return {
+		"summary": (
+			f"Added: {s['added']}  Removed: {s['removed']}  "
+			f"Modified: {s['modified']}  Collections: {s['collection_changes']}"
+		),
+		"has_changes": diff.has_changes,
+		"added_objects": [o.name for o in diff.added_objects],
+		"removed_objects": [o.name for o in diff.removed_objects],
+		"modified_objects": [
+			{
+				"name": o.name,
+				"changes": [
+					{
+						"property_path": c.property_path,
+						"old_value": c.old_value,
+						"new_value": c.new_value,
+					}
+					for c in o.changes
+				],
+			}
+			for o in diff.modified_objects
+		],
+		"collection_diffs": [
+			{
+				"path": cd.path,
+				"kind": cd.kind.value,
+				"changes": [
+					{
+						"property_path": c.property_path,
+						"old_value": c.old_value,
+						"new_value": c.new_value,
+					}
+					for c in cd.changes
+				],
+			}
+			for cd in diff.collection_diffs
+		],
+		"snapshot_a": {
+			"id": snap_a.id,
+			"label": snap_a.label,
+			"timestamp": snap_a.timestamp_display(),
+		},
+		"snapshot_b": {
+			"id": snap_b.id,
+			"label": snap_b.label,
+			"timestamp": snap_b.timestamp_display(),
+		},
+	}

blendiff/data_model/__init__.py

@@ -0,0 +1,13 @@
+from .scene import (
+    Transform, MaterialSlot, SceneObject, CollectionNode, SerializedScene,
+)
+from .diff import (
+    ChangeKind, PropertyChange, ObjectDiff, CollectionDiff, SceneDiff,
+)
+__all__ = [
+    "Transform", "MaterialSlot", "SceneObject", "CollectionNode",
+    "SerializedScene",
+    "RenderDiff",
+    "ChangeKind", "PropertyChange", "ObjectDiff", "CollectionDiff",
+    "SceneDiff",
+]