figpack 0.3.20__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: figpack
-Version: 0.3.20
+Version: 0.4.0
 Summary: A Python package for creating shareable, interactive visualizations in the browser
 Author-email: Jeremy Magland <jmagland@flatironinstitute.org>
 License: Apache-2.0
@@ -86,6 +86,8 @@ A Python package for creating shareable, interactive visualizations in the brows
 
 For detailed guidance, tutorials, and API reference, visit our **[documentation](https://flatironinstitute.github.io/figpack)**.
 
+[Figpack for the Curious](https://jeremy.magland.org/posts/2026-10-02-figpack-for-the-curious/) (blog post)
+
 ## Quick Start
 
 Want to jump right in? Here's how to get started:

{figpack-0.3.20 → figpack-0.4.0}/README.md

@@ -10,6 +10,8 @@ A Python package for creating shareable, interactive visualizations in the brows
 
 For detailed guidance, tutorials, and API reference, visit our **[documentation](https://flatironinstitute.github.io/figpack)**.
 
+[Figpack for the Curious](https://jeremy.magland.org/posts/2026-10-02-figpack-for-the-curious/) (blog post)
+
 ## Quick Start
 
 Want to jump right in? Here's how to get started:

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

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

{figpack-0.3.20 → figpack-0.4.0}/figpack/cli.py

@@ -18,6 +18,7 @@ import requests
 
 from . import __version__
 from .core._view_figure import view_figure
+from .core._remix_figure import remix_figure
 from .core._patch_figure import patch_figure as core_patch_figure
 from .core._revert_patch_figure import revert_patch_figure as core_revert_patch_figure
 from .core._figure_utils import get_figure_base_url, download_file
@@ -430,7 +431,7 @@ def upload_figure(dir_path: str, title: str, description: str = None) -> None:
 
         for file_path in dir_pathlib.rglob("*"):
             if file_path.is_file():
-                rel_path = str(file_path.relative_to(dir_pathlib))
+                rel_path = file_path.relative_to(dir_pathlib).as_posix()
                 file_size = file_path.stat().st_size
                 manifest["files"].append({"path": rel_path, "size": file_size})
                 manifest["total_size"] += file_size
@@ -553,7 +554,7 @@ def _old_revert_figure(
         for item in backup_subdir.rglob("*"):
             if item.is_file() and item.name != "backup_info.json":
                 rel_path = item.relative_to(backup_subdir)
-                backed_up_files.append(str(rel_path))
+                backed_up_files.append(rel_path.as_posix())
     else:
         with open(backup_info_path) as f:
             backup_info = json.load(f)
@@ -715,6 +716,20 @@ def main():
         "--port", type=int, help="Port number to serve on (default: auto-select)"
     )
 
+    # Remix command
+    remix_parser = subparsers.add_parser(
+        "remix",
+        help="Download a figure's index.html and serve it locally for remixing",
+    )
+    remix_parser.add_argument("figure_url", help="The figpack URL to remix")
+    remix_parser.add_argument(
+        "--dir",
+        help="Local directory for the remix (default: ~/.figpack/remixes/<figure id>)",
+    )
+    remix_parser.add_argument(
+        "--port", type=int, help="Port number to serve on (default: auto-select)"
+    )
+
     # Patch figure command
     patch_figure_parser = subparsers.add_parser(
         "patch-figure", help="Update a figure's rendering code to the latest version"
@@ -797,6 +812,8 @@ def main():
             download_and_view_archive(args.archive, port=args.port)
         else:
             view_figure(args.archive, port=args.port)
+    elif args.command == "remix":
+        remix_figure(args.figure_url, dir_path=args.dir, port=args.port)
     elif args.command == "patch-figure":
         patch_figure(args.figure_url, admin_override=args.admin_override)
     elif args.command == "revert-patch-figure":

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

@@ -10,6 +10,11 @@ from .figpack_extension import FigpackExtension
 from .extension_view import ExtensionView
 from .zarr import Group, _check_zarr_version
 from ._zarr_consolidate import consolidate_zarr_chunks
+from ._figure_spec import (
+    build_figure_spec,
+    build_figure_spec_docs,
+    insert_figure_spec_into_html,
+)
 
 thisdir = pathlib.Path(__file__).parent.resolve()
 
@@ -28,8 +33,9 @@ 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. Discovers and writes extension JavaScript files
-    4. Consolidates zarr metadata
+    3. Writes the figure spec (layout and settings) into index.html
+    4. Discovers and writes extension JavaScript files
+    5. Consolidates zarr metadata
 
     Args:
         view: The figpack view to prepare
@@ -74,6 +80,19 @@ def prepare_figure_bundle(
         if script:
             zarr_group.attrs["script"] = script
 
+        # Write the figure spec (layout and settings) into index.html
+        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)
+        index_html_path.write_text(
+            insert_figure_spec_into_html(
+                index_html_path.read_text(encoding="utf-8"),
+                figure_spec,
+                figure_spec_docs,
+            ),
+            encoding="utf-8",
+        )
+
         # Discover and write extension JavaScript files
         required_extensions = _discover_required_extensions(view)
         _write_extension_files(required_extensions, tmpdir)

figpack-0.4.0/figpack/core/_figure_spec.py

@@ -0,0 +1,281 @@
+"""
+Figure spec written into index.html
+
+The spec lists the layout and the user-facing settings of a figure, on top of
+the data in data.zarr. Each node's props are merged over the attributes of the
+matching zarr group by the frontend (figpack-figure/src/figureSpec.ts), so
+editing a prop value in index.html changes the figure.
+
+Which attributes appear is decided by per-view schemas (SpecSchema), declared
+as the `spec_schema` class attribute of view classes. Attributes that describe
+the stored data (sizes, sampling rates, downsampling factors, ...) are left
+out, and so are views without a schema. A short reference for the view types
+used in the figure is written into index.html next to the spec, so the figure
+stays self-contained.
+"""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional
+
+FIGURE_SPEC_VERSION = 1
+
+# Warn when the spec gets large, since it is meant to be read and edited (often
+# by an AI agent, where it costs input tokens)
+SPEC_SIZE_WARNING_CHARS = 20000
+
+# Line width used when formatting the spec JSON
+_SPEC_LINE_WIDTH = 120
+
+# Props of the root node that belong to the figure rather than its root view
+_FIGURE_PROPS = {"title"}
+
+
+@dataclass
+class SpecProp:
+    """A user-facing attribute of a view (or of a child group of a view)"""
+
+    name: str
+    type: str
+    description: str
+
+
+@dataclass
+class SpecSchema:
+    """
+    Describes which zarr attributes of a view are exposed in the figure spec
+
+    children:
+        "none": the view has no configurable child groups
+        "views": child groups are views (e.g. layouts); each uses its own schema
+        "groups": child groups are configurable parts of this view (e.g. the
+            series of a TimeseriesGraph), with props given by child_props
+    """
+
+    view_type: str
+    description: str
+    props: List[SpecProp] = field(default_factory=list)
+    children: Literal["none", "views", "groups"] = "none"
+    children_description: str = ""
+    child_props: List[SpecProp] = field(default_factory=list)
+
+
+def get_spec_schemas() -> Dict[str, SpecSchema]:
+    """Collect the spec schemas of all imported view classes, keyed by view type"""
+    from .figpack_view import FigpackView
+
+    schemas: Dict[str, SpecSchema] = {}
+    stack = list(FigpackView.__subclasses__())
+    seen = set()
+    while stack:
+        cls = stack.pop()
+        if cls in seen:
+            continue
+        seen.add(cls)
+        stack.extend(cls.__subclasses__())
+        schema = cls.__dict__.get("spec_schema")
+        if isinstance(schema, SpecSchema):
+            schemas[schema.view_type] = schema
+    return schemas
+
+
+def build_figure_spec(
+    zarr_group, schemas: Optional[Dict[str, SpecSchema]] = None
+) -> Dict[str, Any]:
+    """
+    Build the figure spec from the (raw) root zarr group of a figure
+
+    Args:
+        zarr_group: The root zarr group of the figure
+        schemas: Spec schemas by view type (default: get_spec_schemas())
+
+    Returns:
+        The spec as a JSON-serializable dict
+    """
+    if schemas is None:
+        schemas = get_spec_schemas()
+    node = _build_view_node(zarr_group, schemas)
+    figure_props = {
+        k: zarr_group.attrs[k] for k in sorted(_FIGURE_PROPS) if k in zarr_group.attrs
+    }
+    if figure_props:
+        node["props"] = {**figure_props, **node.get("props", {})}
+    return node
+
+
+def _select_props(attrs, props: List[SpecProp]) -> Dict[str, Any]:
+    return {p.name: attrs[p.name] for p in props if p.name in attrs}
+
+
+def _build_view_node(group, schemas: Dict[str, SpecSchema]) -> Dict[str, Any]:
+    schema = schemas.get(group.attrs.get("view_type", ""))
+    if schema is None:
+        return {}
+    node: Dict[str, Any] = {}
+    props = _select_props(group.attrs, schema.props)
+    if props:
+        node["props"] = props
+    children = {}
+    for name, subgroup in group.groups():
+        if schema.children == "views":
+            child = _build_view_node(subgroup, schemas)
+        elif schema.children == "groups":
+            child_props = _select_props(subgroup.attrs, schema.child_props)
+            child = {"props": child_props} if child_props else {}
+        else:
+            child = {}
+        if child:
+            children[name] = child
+    if children:
+        node["children"] = children
+    return node
+
+
+def _collect_view_types(zarr_group) -> List[str]:
+    view_types = []
+
+    def visit(group):
+        vt = group.attrs.get("view_type")
+        if vt and vt not in view_types:
+            view_types.append(vt)
+        for _, subgroup in group.groups():
+            visit(subgroup)
+
+    visit(zarr_group)
+    return view_types
+
+
+def build_figure_spec_docs(
+    zarr_group, schemas: Optional[Dict[str, SpecSchema]] = None
+) -> str:
+    """
+    Build a short markdown reference for the spec, covering the view types
+    used in the figure
+
+    Args:
+        zarr_group: The root zarr group of the figure
+        schemas: Spec schemas by view type (default: get_spec_schemas())
+
+    Returns:
+        The reference as markdown text
+    """
+    if schemas is None:
+        schemas = get_spec_schemas()
+    lines = [
+        f"# Figure spec reference (spec version {FIGURE_SPEC_VERSION})",
+        "",
+        "The figpack.render(spec) script below defines this figure's layout and settings on top of the data in data.zarr.",
+        "A spec node is {data?, view_type?, props?, children?}:",
+        "- props: values that replace the attributes of the node's zarr group (whole values are replaced; objects and lists are not merged).",
+        "- children: child nodes by name, matched to the subgroups of the node's zarr group.",
+        '- data: path of a group in data.zarr for this node (e.g. "/item_0"), or null for a node defined only by the spec (then view_type is required). If omitted, the node uses its counterpart in the original figure: the root group, or the parent\'s subgroup with the same name.',
+        "- view_type: the view type of the node.",
+        "Only the props documented here are listed in the spec. Other attributes in data.zarr describe the stored data and should not be changed.",
+        "Root node: props.title (string) is the figure title.",
+    ]
+    view_types = _collect_view_types(zarr_group)
+    documented = [vt for vt in view_types if vt in schemas]
+    for vt in documented:
+        schema = schemas[vt]
+        lines += ["", f"## {vt}", "", schema.description]
+        if schema.props:
+            lines.append("Props:")
+            lines += [f"- {p.name} ({p.type}): {p.description}" for p in schema.props]
+        else:
+            lines.append("No configurable props.")
+        if schema.children_description:
+            lines.append(f"Children: {schema.children_description}")
+        if schema.child_props:
+            lines.append("Child props:")
+            lines += [
+                f"- {p.name} ({p.type}): {p.description}" for p in schema.child_props
+            ]
+    undocumented = [vt for vt in view_types if vt not in schemas]
+    if undocumented:
+        lines += [
+            "",
+            "View types without documented props (they are rendered from data.zarr as is): "
+            + ", ".join(undocumented),
+        ]
+    return "\n".join(lines) + "\n"
+
+
+def format_spec_json(value: Any, *, indent: int = 0, prefix_len: int = 0) -> str:
+    """
+    Format JSON with one entry per line, except that values short enough to
+    fit on the current line are written inline
+
+    Args:
+        value: JSON-serializable value
+        indent: Current indentation (spaces)
+        prefix_len: Length of the text before the value on its first line
+
+    Returns:
+        The formatted JSON
+    """
+    compact = json.dumps(value, ensure_ascii=False)
+    if (
+        not isinstance(value, (dict, list))
+        or not value
+        or indent + prefix_len + len(compact) <= _SPEC_LINE_WIDTH
+    ):
+        return compact
+    pad = " " * (indent + 2)
+    if isinstance(value, dict):
+        entries = []
+        for k, v in value.items():
+            key = json.dumps(k, ensure_ascii=False) + ": "
+            entries.append(
+                pad + key + format_spec_json(v, indent=indent + 2, prefix_len=len(key))
+            )
+        return "{\n" + ",\n".join(entries) + "\n" + " " * indent + "}"
+    entries = [pad + format_spec_json(v, indent=indent + 2) for v in value]
+    return "[\n" + ",\n".join(entries) + "\n" + " " * indent + "]"
+
+
+def _escape_for_script(text: str) -> str:
+    # Make text safe to embed in a <script> element
+    return (
+        text.replace("</", "<\\/")
+        .replace("\u2028", "\\u2028")
+        .replace("\u2029", "\\u2029")
+    )
+
+
+def insert_figure_spec_into_html(
+    html: str, spec: Dict[str, Any], docs: Optional[str] = None
+) -> str:
+    """
+    Insert the spec reference and a figpack.render(spec) script at the end of
+    the body of index.html
+
+    Args:
+        html: The contents of index.html
+        spec: The figure spec
+        docs: Optional markdown reference for the spec
+
+    Returns:
+        The updated html
+    """
+    spec_json = _escape_for_script(format_spec_json(spec, indent=4))
+    if len(spec_json) > SPEC_SIZE_WARNING_CHARS:
+        print(
+            f"Warning: the figure spec in index.html is {len(spec_json)} characters "
+            f"(more than {SPEC_SIZE_WARNING_CHARS})"
+        )
+    script = ""
+    if docs:
+        script += (
+            '    <script type="text/markdown" data-figpack-spec-docs>\n'
+            + _escape_for_script(docs)
+            + "    </script>\n"
+        )
+    script += (
+        '    <script type="module" data-figpack-spec>\n'
+        + f"    figpack.render({spec_json}, {{ specVersion: {FIGURE_SPEC_VERSION} }});\n"
+        + "    </script>\n"
+    )
+    idx = html.rfind("</body>")
+    if idx < 0:
+        return html + script
+    return html[:idx] + script + html[idx:]

{figpack-0.3.20 → figpack-0.4.0}/figpack/core/_file_handler.py

@@ -81,7 +81,7 @@ class FileUploadCORSRequestHandler(CORSRequestHandler):
                 self.send_header("Content-Type", "application/json")
                 self.end_headers()
 
-                response_data = f'{{"status": "success", "path": "{file_path.relative_to(pathlib.Path(self.directory))}"}}'
+                response_data = f'{{"status": "success", "path": "{file_path.relative_to(pathlib.Path(self.directory)).as_posix()}"}}'
                 self.wfile.write(response_data.encode("utf-8"))
 
         except Exception as e:

{figpack-0.3.20 → figpack-0.4.0}/figpack/core/_patch_figure.py

@@ -9,7 +9,10 @@ Core functionality for patching figpack figures
 import json
 import os
 import pathlib
+import re
+import tempfile
 import time
+from typing import Optional, Tuple
 from urllib.parse import urljoin
 
 import requests
@@ -18,6 +21,58 @@ from .. import __version__
 from .config import FIGPACK_API_BASE_URL
 from ._figure_utils import get_figure_base_url
 
+# A reference to a hashed bundle asset in a src/href attribute, e.g.
+# src="./assets/index-CSMGUquF.js" (Vite names assets <name>-<8-char hash>.<ext>)
+_ASSET_REF_RE = re.compile(
+    r"""((?:src|href)=["'])((?:\./)?assets/)([A-Za-z0-9_.-]+)-([A-Za-z0-9_-]{8})\.([A-Za-z0-9]+)(["'])"""
+)
+
+
+def swap_bundle_references(page_html: str, new_index_html: str) -> Tuple[str, int]:
+    """
+    Point the bundle asset references of a figure page to the assets of a new
+    figpack-figure bundle, leaving the rest of the page (such as the figure
+    spec, its reference docs, and any edits) unchanged
+
+    Args:
+        page_html: The html of the figure page to patch
+        new_index_html: The index.html of the new figpack-figure bundle
+
+    Returns:
+        The patched html and the number of references replaced
+    """
+    new_refs = {}
+    for m in _ASSET_REF_RE.finditer(new_index_html):
+        new_refs[(m.group(3), m.group(5))] = m.group(3) + "-" + m.group(4)
+
+    count = 0
+
+    def replace(m):
+        nonlocal count
+        key = (m.group(3), m.group(5))
+        if key not in new_refs:
+            return m.group(0)
+        count += 1
+        return m.group(1) + m.group(2) + new_refs[key] + "." + m.group(5) + m.group(6)
+
+    return _ASSET_REF_RE.sub(replace, page_html), count
+
+
+def _patched_page_html(path: str, page_html: str, new_index_html: str) -> Optional[str]:
+    """
+    The patched contents of a figure page, or None if it cannot be patched
+
+    An index.html without a figure spec (from figpack versions before figure
+    specs) is replaced by the new bundle's index.html, as before. Other pages
+    keep their contents, with the bundle references swapped.
+    """
+    if path == "index.html" and "data-figpack-spec" not in page_html:
+        return new_index_html
+    patched, count = swap_bundle_references(page_html, new_index_html)
+    if count == 0:
+        return None
+    return patched
+
 
 def patch_figure(
     figure_url: str,
@@ -93,7 +148,7 @@ def patch_figure(
             if admin_override and figure_owner:
                 print(f"⚠️  ADMIN OVERRIDE: Modifying figure owned by {figure_owner}")
             print(
-                f"This will update the rendering code (index.html, assets/*, extension-*.js)"
+                f"This will update the rendering code (assets/*, and the bundle references in the figure's .html pages)"
             )
             print(f"to figpack version {__version__}")
             print(
@@ -128,7 +183,7 @@ def patch_figure(
         file_path = file_info["path"]
         # Only backup rendering files
         if (
-            file_path == "index.html"
+            file_path.endswith(".html")
             or file_path.startswith("assets/")
             or file_path.startswith("extension-")
             or file_path == "extension_manifest.json"
@@ -205,8 +260,36 @@ def patch_figure(
     # Collect all files to upload
     files_to_upload = []
 
+    new_index_html = (html_dir / "index.html").read_text(encoding="utf-8")
+    patched_pages_dir = pathlib.Path(tempfile.mkdtemp(prefix="figpack_patch_"))
+    page_paths = [
+        f["path"]
+        for f in rendering_files
+        if f["path"].endswith(".html") and f["path"] not in failed_backups
+    ]
+    if "index.html" not in page_paths:
+        page_paths.append("index.html")
+    for page_path in page_paths:
+        backup_page = backup_subdir / page_path
+        page_html = (
+            backup_page.read_text(encoding="utf-8") if backup_page.exists() else ""
+        )
+        patched = _patched_page_html(page_path, page_html, new_index_html)
+        if patched is None:
+            if verbose:
+                print(
+                    f"Warning: {page_path} has no bundle references to update; leaving it unchanged"
+                )
+            continue
+        patched_page = patched_pages_dir / page_path
+        patched_page.parent.mkdir(parents=True, exist_ok=True)
+        patched_page.write_text(patched, encoding="utf-8")
+        files_to_upload.append((page_path, patched_page))
+
     for item in html_dir.iterdir():
         if item.is_file():
+            if item.name.endswith(".html"):
+                continue  # pages are patched above
             files_to_upload.append((str(item.name), item))
         elif item.is_dir() and item.name == "assets":
             for subitem in item.iterdir():
@@ -339,8 +422,6 @@ def patch_figure(
         manifest["total_size"] = sum(f.get("size", 0) for f in updated_files)
 
         # Upload manifest.json
-        import tempfile
-
         manifest_content = json.dumps(manifest, indent=2)
 
         with tempfile.NamedTemporaryFile(