figpack 0.4.0__tar.gz → 0.4.2__tar.gz

{figpack-0.4.0/figpack.egg-info → figpack-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: figpack
-Version: 0.4.0
+Version: 0.4.2
 Summary: A Python package for creating shareable, interactive visualizations in the browser
 Author-email: Jeremy Magland <jmagland@flatironinstitute.org>
 License: Apache-2.0

{figpack-0.4.0 → figpack-0.4.2}/figpack/__init__.py

@@ -2,7 +2,7 @@
 figpack - A Python package for creating shareable, interactive visualizations in the browser
 """
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 from .cli import view_figure
 from .core import FigpackView, FigpackExtension, ExtensionView

{figpack-0.4.0 → figpack-0.4.2}/figpack/core/_bundle_utils.py

@@ -3,6 +3,8 @@ import pathlib
 import json
 from typing import Optional, List
 
+from ._remix_patch import RemixArg, apply_remix_patch
+
 import zarr
 
 from .figpack_view import FigpackView
@@ -26,6 +28,7 @@ def prepare_figure_bundle(
     title: str,
     description: Optional[str] = None,
     script: Optional[str] = None,
+    remix: Optional[RemixArg] = None,
 ) -> None:
     """
     Prepare a figure bundle in the specified temporary directory.
@@ -33,7 +36,8 @@ def prepare_figure_bundle(
     This function:
     1. Copies all files from the figpack-figure-dist directory to tmpdir
     2. Writes the view data to a zarr group
-    3. Writes the figure spec (layout and settings) into index.html
+    3. Writes the figure spec (layout and settings) into index.html, with a
+       remix patch merged in if given
     4. Discovers and writes extension JavaScript files
     5. Consolidates zarr metadata
 
@@ -43,6 +47,8 @@ def prepare_figure_bundle(
         title: Title for the figure (required)
         description: Optional description for the figure (markdown supported)
         script: Optional script text used to generate the figure
+        remix: Optional remix patch (a file path or a loaded dict) to merge
+            into the figure spec
     """
     html_dir = thisdir / ".." / "figpack-figure-dist"
     if not os.path.exists(html_dir):
@@ -84,11 +90,17 @@ def prepare_figure_bundle(
         index_html_path = pathlib.Path(tmpdir) / "index.html"
         figure_spec = build_figure_spec(zarr_group._zarr_group)
         figure_spec_docs = build_figure_spec_docs(zarr_group._zarr_group)
+        remix_record = None
+        if remix is not None:
+            figure_spec, remix_record = apply_remix_patch(
+                figure_spec, remix, zarr_group._zarr_group
+            )
         index_html_path.write_text(
             insert_figure_spec_into_html(
                 index_html_path.read_text(encoding="utf-8"),
                 figure_spec,
                 figure_spec_docs,
+                remix_record,
             ),
             encoding="utf-8",
         )

{figpack-0.4.0 → figpack-0.4.2}/figpack/core/_figure_spec.py

@@ -243,7 +243,10 @@ def _escape_for_script(text: str) -> str:
 
 
 def insert_figure_spec_into_html(
-    html: str, spec: Dict[str, Any], docs: Optional[str] = None
+    html: str,
+    spec: Dict[str, Any],
+    docs: Optional[str] = None,
+    remix_record: Optional[Dict[str, Any]] = None,
 ) -> str:
     """
     Insert the spec reference and a figpack.render(spec) script at the end of
@@ -253,6 +256,9 @@ def insert_figure_spec_into_html(
         html: The contents of index.html
         spec: The figure spec
         docs: Optional markdown reference for the spec
+        remix_record: Optional record of a remix patch applied to the spec,
+            written as a <script type="application/json"
+            data-figpack-remix-patch> element
 
     Returns:
         The updated html
@@ -270,6 +276,12 @@ def insert_figure_spec_into_html(
             + _escape_for_script(docs)
             + "    </script>\n"
         )
+    if remix_record is not None:
+        script += (
+            '    <script type="application/json" data-figpack-remix-patch>\n    '
+            + _escape_for_script(format_spec_json(remix_record, indent=4))
+            + "\n    </script>\n"
+        )
     script += (
         '    <script type="module" data-figpack-spec>\n'
         + f"    figpack.render({spec_json}, {{ specVersion: {FIGURE_SPEC_VERSION} }});\n"

figpack-0.4.2/figpack/core/_remix_patch.py

@@ -0,0 +1,228 @@
+"""
+Remix patches: applying a remix's changes when a figure is made
+
+A remix patch carries the changes a remix makes to a figure's spec, keyed by
+the figure's structure (child names and props) rather than by the code that
+built the figure. It is exported from the remix page (Export patch) and
+applied with view.show(..., remix=...) or view.save(..., remix=...). Format
+(version 1):
+
+    {
+      "figpack_remix_patch": 1,
+      "source": {"figureUrl": "...", "createdAt": "2026-10-23T12:00:00.000Z"},
+      "patch": <spec diff>
+    }
+
+The spec diff has the shape of a spec node, {data?, view_type?, props?,
+children?}, with only what the remix changed. It is merged into the figure's
+spec with the same rules as the spec itself:
+
+- props replace per key (whole values; lists and objects are not merged)
+- children merge by name
+- data and view_type replace; a data path must exist in data.zarr
+
+Parts that do not match the figure are reported as warnings and skipped: a
+child that is neither in the spec nor a subgroup in data.zarr (unless the
+patch gives it its own data), a data path that does not exist, or a value of
+the wrong type. The figpack-manage remix page applies patches with the same
+rules (figpack-manage/src/pages/RemixPage/remixPatch.ts); both are tested
+against the shared cases in tests/remix_patch_cases. See
+docs/remix_patches.md.
+"""
+
+import copy
+import json
+import os
+import pathlib
+from typing import Any, Dict, List, Optional, Set, Tuple, Union
+
+REMIX_PATCH_VERSION = 1
+
+_NODE_KEYS = {"data", "view_type", "props", "children"}
+
+RemixArg = Union[str, os.PathLike, Dict[str, Any]]
+
+
+def load_remix_patch(remix: RemixArg) -> Tuple[Dict[str, Any], Optional[str]]:
+    """
+    Load a remix patch from a file path, or check an already-loaded dict
+
+    Args:
+        remix: Path to a patch file, or the patch as a dict
+
+    Returns:
+        (patch, file name or None)
+    """
+    file_name = None
+    if isinstance(remix, dict):
+        patch = remix
+    else:
+        path = pathlib.Path(remix)
+        file_name = path.name
+        patch = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(patch, dict) or "figpack_remix_patch" not in patch:
+        raise ValueError("Not a remix patch (missing figpack_remix_patch)")
+    version = patch["figpack_remix_patch"]
+    if not isinstance(version, int) or version > REMIX_PATCH_VERSION:
+        raise ValueError(
+            f"Remix patch version {version} is not supported by this figpack "
+            f"(supports {REMIX_PATCH_VERSION}); upgrade figpack"
+        )
+    if not isinstance(patch.get("patch"), dict):
+        raise ValueError("Remix patch has no 'patch' object")
+    return patch, file_name
+
+
+def get_group_paths(zarr_group) -> Set[str]:
+    """The paths of all groups in a zarr tree, relative to its root ("" for the root)"""
+    paths = {""}
+
+    def visit(group, prefix):
+        for name, subgroup in group.groups():
+            path = prefix + name
+            paths.add(path)
+            visit(subgroup, path + "/")
+
+    visit(zarr_group, "")
+    return paths
+
+
+def merge_remix_patch(
+    spec: Dict[str, Any], patch: Dict[str, Any], group_paths: Set[str]
+) -> Tuple[Dict[str, Any], List[str]]:
+    """
+    Merge a spec diff into a figure spec
+
+    Args:
+        spec: The figure spec (not modified)
+        patch: The spec diff (the "patch" field of a remix patch)
+        group_paths: Paths of the groups in data.zarr (see get_group_paths)
+
+    Returns:
+        (merged spec, warnings for the parts that were skipped)
+    """
+    warnings: List[str] = []
+    merged = _merge_node(spec, patch, "", "", group_paths, warnings)
+    return merged, warnings
+
+
+def _normalize_path(path: str) -> str:
+    return path.strip("/")
+
+
+def _where(spec_path: str) -> str:
+    return spec_path or "root"
+
+
+def _merge_node(
+    node: Dict[str, Any],
+    patch: Dict[str, Any],
+    base: Optional[str],
+    spec_path: str,
+    group_paths: Set[str],
+    warnings: List[str],
+) -> Dict[str, Any]:
+    # base: path of the node's counterpart group in data.zarr, if any
+    where = _where(spec_path)
+    result = copy.deepcopy(node)
+    for key in patch:
+        if key not in _NODE_KEYS:
+            warnings.append(f"remix: unknown key '{key}' at '{where}'; skipped")
+    if "data" in patch:
+        data = patch["data"]
+        if data is None:
+            result["data"] = None
+        elif isinstance(data, str) and _normalize_path(data) in group_paths:
+            result["data"] = data
+        elif isinstance(data, str):
+            warnings.append(
+                f"remix: data path '{data}' at '{where}' is not in data.zarr; skipped"
+            )
+        else:
+            warnings.append(f"remix: data at '{where}' is not a string; skipped")
+    if "view_type" in patch:
+        if isinstance(patch["view_type"], str):
+            result["view_type"] = patch["view_type"]
+        else:
+            warnings.append(f"remix: view_type at '{where}' is not a string; skipped")
+    if "props" in patch:
+        if isinstance(patch["props"], dict):
+            result["props"] = {**result.get("props", {}), **patch["props"]}
+        else:
+            warnings.append(f"remix: props at '{where}' is not an object; skipped")
+    if "data" in result:
+        base = None if result["data"] is None else _normalize_path(result["data"])
+    if "children" in patch:
+        if isinstance(patch["children"], dict):
+            children = result.get("children", {})
+            for name, child_patch in patch["children"].items():
+                child_path = f"{spec_path}/{name}" if spec_path else name
+                if not isinstance(child_patch, dict):
+                    warnings.append(
+                        f"remix: child '{_where(child_path)}' is not an object; skipped"
+                    )
+                    continue
+                counterpart = None
+                if base is not None:
+                    p = f"{base}/{name}" if base else name
+                    counterpart = p if p in group_paths else None
+                if name not in children and counterpart is None:
+                    if not _has_own_data(child_patch, group_paths):
+                        warnings.append(
+                            f"remix: no child '{name}' under '{where}'; skipped"
+                        )
+                        continue
+                children[name] = _merge_node(
+                    children.get(name, {}),
+                    child_patch,
+                    counterpart,
+                    child_path,
+                    group_paths,
+                    warnings,
+                )
+            if children:
+                result["children"] = children
+        else:
+            warnings.append(f"remix: children at '{where}' is not an object; skipped")
+    return result
+
+
+def _has_own_data(patch: Dict[str, Any], group_paths: Set[str]) -> bool:
+    # Whether a patch node defines its own base: data null (a node defined
+    # only by the spec) or an existing data path
+    if "data" not in patch:
+        return False
+    data = patch["data"]
+    return data is None or (
+        isinstance(data, str) and _normalize_path(data) in group_paths
+    )
+
+
+def apply_remix_patch(
+    spec: Dict[str, Any], remix: RemixArg, zarr_group
+) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """
+    Apply a remix patch to a figure spec, printing a warning for each part
+    that was skipped
+
+    Args:
+        spec: The figure spec built from the zarr tree
+        remix: Path to a patch file, or the patch as a dict
+        zarr_group: The (raw) root zarr group of the figure
+
+    Returns:
+        (merged spec, record of the applied patch for index.html)
+    """
+    patch, file_name = load_remix_patch(remix)
+    merged, warnings = merge_remix_patch(
+        spec, patch["patch"], get_group_paths(zarr_group)
+    )
+    for w in warnings:
+        print(f"Warning: {w}")
+    record = {
+        "file": file_name,
+        "source": patch.get("source"),
+        "patch": patch["patch"],
+        "skipped": warnings,
+    }
+    return merged, record

{figpack-0.4.0 → figpack-0.4.2}/figpack/core/_save_figure.py

@@ -1,7 +1,9 @@
 import pathlib
 import tempfile
+from typing import Optional
 
 from ._bundle_utils import prepare_figure_bundle
+from ._remix_patch import RemixArg
 from .figpack_view import FigpackView
 
 
@@ -12,6 +14,7 @@ def _save_figure(
     title: str,
     description: str = "",
     script: str = "",
+    remix: Optional[RemixArg] = None,
 ) -> None:
     """
     Save the figure to a folder or a .tar.gz file
@@ -22,6 +25,7 @@ def _save_figure(
         title: Title for the figure
         description: Description text with markdown support
         script: Optional script text used to generate the figure
+        remix: Optional remix patch to apply (a file path or a loaded dict)
     """
     output_path_2 = pathlib.Path(output_path)
     if (output_path_2.suffix == ".gz" and output_path_2.suffixes[-2] == ".tar") or (
@@ -30,7 +34,12 @@ def _save_figure(
         # It's a .tar.gz file
         with tempfile.TemporaryDirectory(prefix="figpack_save_") as tmpdir:
             prepare_figure_bundle(
-                view, tmpdir, title=title, description=description, script=script
+                view,
+                tmpdir,
+                title=title,
+                description=description,
+                script=script,
+                remix=remix,
             )
             # Create tar.gz file
             import tarfile
@@ -46,4 +55,5 @@ def _save_figure(
             title=title,
             description=description,
             script=script,
+            remix=remix,
         )

{figpack-0.4.0 → figpack-0.4.2}/figpack/core/_show_view.py

@@ -5,6 +5,7 @@ import webbrowser
 from typing import Union
 
 from ._bundle_utils import prepare_figure_bundle
+from ._remix_patch import RemixArg
 from ._server_manager import ProcessServerManager
 from ._upload_bundle import _upload_bundle
 from .figpack_view import FigpackView
@@ -92,6 +93,7 @@ def _show_view(
     title: str,
     description: Union[str, None],
     script: Union[str, None],
+    remix: Union[RemixArg, None],
     inline: bool,
     inline_height: int,
     wait_for_input: bool,
@@ -101,7 +103,12 @@ def _show_view(
         # Upload behavior: create temporary directory for this upload only
         with tempfile.TemporaryDirectory(prefix="figpack_upload_") as tmpdir:
             prepare_figure_bundle(
-                view, tmpdir, title=title, description=description, script=script
+                view,
+                tmpdir,
+                title=title,
+                description=description,
+                script=script,
+                remix=remix,
             )
 
             # Check for API key - required for regular uploads, optional for ephemeral
@@ -146,7 +153,12 @@ def _show_view(
 
         # Prepare the figure bundle in the subdirectory
         prepare_figure_bundle(
-            view, str(figure_dir), title=title, description=description, script=script
+            view,
+            str(figure_dir),
+            title=title,
+            description=description,
+            script=script,
+            remix=remix,
         )
 
         # Start or get existing server

{figpack-0.4.0 → figpack-0.4.2}/figpack/core/figpack_view.py

@@ -5,10 +5,13 @@ Base view class for figpack visualization components
 import os
 import random
 import string
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
 
 from .zarr import Group
 
+if TYPE_CHECKING:
+    from ._remix_patch import RemixArg
+
 
 class FigpackView:
     """
@@ -21,6 +24,7 @@ class FigpackView:
         title: str,
         description: Optional[str] = None,
         script: Optional[str] = None,
+        remix: Optional["RemixArg"] = None,
         port: Optional[int] = None,
         open_in_browser: Optional[bool] = None,
         upload: Optional[bool] = None,
@@ -43,6 +47,9 @@ class FigpackView:
             title: Title for browser tab and figure (required)
             description: Description text with markdown support (optional)
             script: Optional script text used to generate the figure
+            remix: Optional remix patch to apply to the figure spec: a path to a
+                patch file exported from the remix page, or the loaded dict (see
+                https://flatironinstitute.github.io/figpack/remix_patches.html)
             port: Local server port, random if None
             open_in_browser: Auto-open in browser, auto-detects by environment
             upload: Upload figure to figpack servers, auto-detects by environment
@@ -164,6 +171,7 @@ class FigpackView:
             title=title,
             description=description,
             script=script,
+            remix=remix,
             inline=inline,
             inline_height=inline_height,
             wait_for_input=wait_for_input,
@@ -171,7 +179,13 @@ class FigpackView:
         )
 
     def save(
-        self, output_path: str, *, title: str, description: str = "", script: str = ""
+        self,
+        output_path: str,
+        *,
+        title: str,
+        description: str = "",
+        script: str = "",
+        remix: Optional["RemixArg"] = None,
     ) -> None:
         """
         Save as figure either to a folder or to a .tar.gz file
@@ -180,11 +194,18 @@ class FigpackView:
             title: Title for the figure
             description: Description text with markdown support
             script: Optional script text used to generate the figure
+            remix: Optional remix patch to apply to the figure spec: a path to a
+                patch file exported from the remix page, or the loaded dict
         """
         from ._save_figure import _save_figure
 
         _save_figure(
-            self, output_path, title=title, description=description, script=script
+            self,
+            output_path,
+            title=title,
+            description=description,
+            script=script,
+            remix=remix,
         )
 
     def write_to_zarr_group(self, group: Group) -> None: