figpack 0.4.2__tar.gz → 0.4.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: figpack
-Version: 0.4.2
+Version: 0.4.3
 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.2 → figpack-0.4.3}/figpack/__init__.py

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

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

@@ -40,6 +40,70 @@ class SpecProp:
     description: str
 
 
+# Style keys shared by all views. A view's `style` attr holds any of them, and
+# it cascades: each view's effective style is its parent view's with its own
+# keys merged over it (figpack-figure/src/inheritedStyle.ts). A view ignores
+# the keys it does not use and lists the ones it uses in SpecSchema.style_keys.
+STYLE_KEYS: Dict[str, SpecProp] = {
+    p.name: p
+    for p in [
+        SpecProp("label_font_size", "number", "Axis label font size in pixels."),
+        SpecProp("tick_font_size", "number", "Tick label font size in pixels."),
+        SpecProp("legend_font_size", "number", "Legend text font size in pixels."),
+        SpecProp(
+            "font_family",
+            "string",
+            'CSS font family of all text, e.g. "serif" or "Georgia, serif".',
+        ),
+        SpecProp(
+            "text_color",
+            "string (CSS color)",
+            "Main text color: axis labels, major tick labels, legend text, captions and markdown text.",
+        ),
+        SpecProp(
+            "background_color",
+            "string (CSS color)",
+            "Background color of plot areas (and legends), captions, markdown and the active tab.",
+        ),
+        SpecProp(
+            "gridline_color",
+            "string (CSS color)",
+            "Color of the major gridlines and ticks.",
+        ),
+        SpecProp(
+            "minor_gridline_color",
+            "string (CSS color)",
+            "Color of the minor gridlines and ticks and of the time axis line.",
+        ),
+        SpecProp(
+            "title_font_size",
+            "number",
+            "Font size in pixels of layout item titles and tabs (defaults 12 and 14); a layout's own title is 2 px larger. Title bars and tab bars grow to fit.",
+        ),
+        SpecProp(
+            "title_color",
+            "string (CSS color)",
+            "Text color of layout title bars and tabs.",
+        ),
+        SpecProp(
+            "title_background_color",
+            "string (CSS color)",
+            "Background color of layout title bars and tab bars.",
+        ),
+        SpecProp(
+            "colormap",
+            '"viridis" | "plasma" | "inferno" | "magma" | "gray"',
+            'Colormap of heatmaps; add "_r" to reverse it (e.g. "gray_r").',
+        ),
+        SpecProp(
+            "border_color",
+            "string (CSS color)",
+            "Color of layout borders, splitter bars and caption borders.",
+        ),
+    ]
+}
+
+
 @dataclass
 class SpecSchema:
     """
@@ -50,6 +114,7 @@ class SpecSchema:
         "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
+    style_keys: the keys of STYLE_KEYS that the view uses
     """
 
     view_type: str
@@ -58,6 +123,7 @@ class SpecSchema:
     children: Literal["none", "views", "groups"] = "none"
     children_description: str = ""
     child_props: List[SpecProp] = field(default_factory=list)
+    style_keys: List[str] = field(default_factory=list)
 
 
 def get_spec_schemas() -> Dict[str, SpecSchema]:
@@ -113,6 +179,9 @@ def _build_view_node(group, schemas: Dict[str, SpecSchema]) -> Dict[str, Any]:
         return {}
     node: Dict[str, Any] = {}
     props = _select_props(group.attrs, schema.props)
+    # Any view may set a style, since it cascades to the views inside it
+    if group.attrs.get("style"):
+        props["style"] = group.attrs["style"]
     if props:
         node["props"] = props
     children = {}
@@ -175,6 +244,23 @@ def build_figure_spec_docs(
     ]
     view_types = _collect_view_types(zarr_group)
     documented = [vt for vt in view_types if vt in schemas]
+    style_users = {
+        key: [vt for vt in documented if key in schemas[vt].style_keys]
+        for key in STYLE_KEYS
+    }
+    if any(style_users.values()):
+        lines += [
+            "",
+            "## Style",
+            "",
+            "Any view node may set props.style to an object of the style keys below. It applies to that view and to every view inside it: styles merge key by key from the root down, and inner values win. Set it on the root node to style the whole figure. Views ignore keys they do not use.",
+            "Style keys:",
+        ]
+        lines += [
+            f"- {p.name} ({p.type}): {p.description} Used by: {', '.join(style_users[key])}."
+            for key, p in STYLE_KEYS.items()
+            if style_users[key]
+        ]
     for vt in documented:
         schema = schemas[vt]
         lines += ["", f"## {vt}", "", schema.description]
@@ -183,6 +269,8 @@ def build_figure_spec_docs(
             lines += [f"- {p.name} ({p.type}): {p.description}" for p in schema.props]
         else:
             lines.append("No configurable props.")
+        if schema.style_keys:
+            lines.append(f"Style keys: {', '.join(schema.style_keys)}.")
         if schema.children_description:
             lines.append(f"Children: {schema.children_description}")
         if schema.child_props:

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

@@ -2,11 +2,13 @@
 Base view class for figpack visualization components
 """
 
+import functools
 import os
 import random
 import string
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Any, Dict, Optional
 
+from ._figure_spec import STYLE_KEYS
 from .zarr import Group
 
 if TYPE_CHECKING:
@@ -18,6 +20,44 @@ class FigpackView:
     Base class for all figpack visualization components
     """
 
+    # Set with set_style(); replaced, never mutated, so the class default is safe
+    _style: Dict[str, Any] = {}
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        # Every view writes its style attr after its own attrs, without each
+        # write_to_zarr_group having to do it
+        write = cls.__dict__.get("write_to_zarr_group")
+        if write is None:
+            return
+
+        @functools.wraps(write)
+        def write_with_style(self, group: Group) -> None:
+            write(self, group)
+            if self._style:
+                group.attrs["style"] = dict(self._style)
+
+        cls.write_to_zarr_group = write_with_style
+
+    def set_style(self, **style: Any) -> "FigpackView":
+        """
+        Set style keys (e.g. label_font_size=16) for this view and every view
+        inside it. Views inside it inherit the keys unless they set their own.
+        Call it on the root view to style the whole figure. Keys given here are
+        merged over those set before.
+
+        Returns:
+            The view itself, so that calls can be chained
+        """
+        unknown = [k for k in style if k not in STYLE_KEYS]
+        if unknown:
+            raise ValueError(
+                f"Unknown style keys: {', '.join(unknown)}. "
+                f"Known keys: {', '.join(STYLE_KEYS)}"
+            )
+        self._style = {**self._style, **style}
+        return self
+
     def show(
         self,
         *,