iplotx 0.3.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

iplotx/{style.py → style/__init__.py}

@@ -1,155 +1,33 @@
 from typing import (
     Any,
+    Iterable,
     Optional,
     Sequence,
 )
+from collections import defaultdict
 from collections.abc import Hashable
-import copy
 from contextlib import contextmanager
 import numpy as np
 import pandas as pd
 
-
-style_leaves = (
-    "cmap",
-    "color",
-    "size",
-    "edgecolor",
-    "facecolor",
-    "linewidth",
-    "linestyle",
-    "alpha",
-    "zorder",
-    "tension",
-    "looptension",
-    "loopmaxangle",
-    "paralleloffset",
-    "offset",
-    "rotate",
-    "marker",
-    "waypoints",
-    "horizontalalignment",
-    "verticalalignment",
-    "boxstyle",
-    "hpadding",
-    "vpadding",
-    "hmargin",
-    "vmargin",
-    "ports",
-    "extend",
-)
-
-# These properties are not allowed to be rotated (global throughout the graph).
-# This might change in the future as the API improves.
-nonrotating_leaves = (
-    "paralleloffset",
-    "looptension",
-    "loopmaxangle",
-    "vertexpadding",
-    "extend",
+from ..utils.style import copy_with_deep_values
+from .library import style_library
+from .leaf_info import (
+    style_leaves,
+    nonrotating_leaves,
 )
 
 
-default = {
-    "vertex": {
-        "size": 20,
-        "facecolor": "black",
-        "marker": "o",
-        "label": {
-            "color": "white",
-            "horizontalalignment": "center",
-            "verticalalignment": "center",
-            "hpadding": 18,
-            "vpadding": 12,
-        },
-    },
-    "edge": {
-        "linewidth": 1.5,
-        "linestyle": "-",
-        "color": "black",
-        "curved": False,
-        "paralleloffset": 3,
-        "tension": 1,
-        "looptension": 4,
-        "loopmaxangle": 60,
-        "label": {
-            "horizontalalignment": "center",
-            "verticalalignment": "center",
-            "rotate": False,
-            "bbox": {
-                "boxstyle": "round",
-                "facecolor": "white",
-                "edgecolor": "none",
-            },
-        },
-        "arrow": {
-            "marker": "|>",
-            "width": 8,
-        },
-    },
-    "grouping": {
-        "facecolor": ["grey", "steelblue", "tomato"],
-        "edgecolor": "black",
-        "linewidth": 1.5,
-        "alpha": 0.5,
-        "vertexpadding": 18,
-    },
-}
-
-
-def copy_with_deep_values(style):
-    """Make a deep copy of the style dict but do not create copies of the keys."""
-    newdict = {}
-    for key, value in style.items():
-        if isinstance(value, dict):
-            newdict[key] = copy_with_deep_values(value)
-        else:
-            newdict[key] = copy.copy(value)
-    return newdict
-
-
-hollow = copy_with_deep_values(default)
-hollow["vertex"]["color"] = None
-hollow["vertex"]["facecolor"] = "none"
-hollow["vertex"]["edgecolor"] = "black"
-hollow["vertex"]["linewidth"] = 1.5
-hollow["vertex"]["marker"] = "r"
-hollow["vertex"]["size"] = "label"
-hollow["vertex"]["label"]["color"] = "black"
-
-tree = copy_with_deep_values(default)
-tree["vertex"]["size"] = 0
-tree["vertex"]["alpha"] = 0
-tree["edge"]["linewidth"] = 2.5
-tree["vertex"]["label"]["bbox"] = {
-    "boxstyle": "square,pad=0.5",
-    "facecolor": "white",
-    "edgecolor": "none",
-}
-tree["vertex"]["label"]["color"] = "black"
-tree["vertex"]["label"]["size"] = 12
-tree["vertex"]["label"]["verticalalignment"] = "center"
-tree["vertex"]["label"]["hmargin"] = 10
-
-
+# Prepopulate default style, it's used later as a backbone for everything else
+default = style_library["default"]
 styles = {
     "default": default,
-    "hollow": hollow,
-    "tree": tree,
 }
 
 
-stylename = "default"
-
-
 current = copy_with_deep_values(styles["default"])
 
 
-def get_stylename():
-    """Return the name of the current iplotx style."""
-    return str(stylename)
-
-
 def get_style(name: str = "", *args) -> dict[str, Any]:
     """Get a *deep copy* of the chosen style.
 
@@ -194,36 +72,33 @@ def get_style(name: str = "", *args) -> dict[str, Any]:
     return style
 
 
-# The following is inspired by matplotlib's style library
-# https://github.com/matplotlib/matplotlib/blob/v3.10.3/lib/matplotlib/style/core.py#L45
-def use(style: Optional[str | dict | Sequence] = None, **kwargs):
-    """Use iplotx style setting for a style specification.
-
-    The style name of 'default' is reserved for reverting back to
-    the default style settings.
+def merge_styles(
+    styles: Sequence[str | dict[str, Any]] | Iterable[str | dict[str, Any]],
+) -> dict[str, Any]:
+    """Merge a sequence of styles into a single one.
 
     Parameters:
-        style: A style specification, currently either a name of an existing style
-            or a dict with specific parts of the style to override. The string
-            "default" resets the style to the default one. If this is a sequence,
-            each style is applied in order.
-        **kwargs: Additional style changes to be applied at the end of any style.
+        styles: Sequence (list, tuple, etc.) of styles, each either the name of an internal
+            style or a dict-like with custom properties.
+    Returns:
+        The composite style as a dict.
     """
     try:
         import networkx as nx
     except ImportError:
         nx = None
 
-    global current
-
     def _sanitize_leaves(style: dict):
         for key, value in style.items():
             if key in style_leaves:
+                # Networkx has a few lazy data structures
+                # TODO: move this code to provider
                 if nx is not None:
                     if isinstance(value, nx.classes.reportviews.NodeView):
                         style[key] = dict(value)
                     elif isinstance(value, nx.classes.reportviews.EdgeViewABC):
                         style[key] = [v for *e, v in value]
+
             elif isinstance(value, dict):
                 _sanitize_leaves(value)
 
@@ -233,37 +108,97 @@ def use(style: Optional[str | dict | Sequence] = None, **kwargs):
                 current[key] = value
                 continue
 
-            # Style leaves are by definition not to be recurred into
-            if isinstance(value, dict) and (key not in style_leaves):
-                _update(value, current[key])
-            elif value is None:
-                del current[key]
+            # Style non-leaves are either recurred into or deleted
+            if key not in style_leaves:
+                if isinstance(value, dict):
+                    _update(value, current[key])
+                elif value is None:
+                    del current[key]
+                else:
+                    raise ValueError(
+                        f"Setting non-leaf style value to a non-dict: {key}, {value}",
+                    )
             else:
-                current[key] = value
+                # Style leaves could be incomplete, ensure a sensible default
+                if value is None:
+                    del current[key]
+                    continue
 
-    old_style = copy_with_deep_values(current)
+                if not isinstance(value, dict):
+                    current[key] = value
+                    continue
 
-    try:
-        if style is None:
-            styles = []
-        elif isinstance(style, (dict, str)):
-            styles = [style]
+                if hasattr(value, "default_factory"):
+                    current[key] = value
+                    continue
+
+                if hasattr(current[key], "default_factory"):
+                    default_value = current[key].default_factory()
+                else:
+                    default_value = current[key]
+                current[key] = defaultdict(
+                    lambda: default_value,
+                    value,
+                )
+
+    merged = {}
+    for style in styles:
+        if isinstance(style, str):
+            style = get_style(style)
         else:
-            styles = list(style)
+            _sanitize_leaves(style)
+            unflatten_style(style)
+        _update(style, merged)
 
-        if kwargs:
-            styles.append(kwargs)
+    return merged
 
-        for style in styles:
-            if style == "default":
-                reset()
-            else:
-                if isinstance(style, str):
-                    current = get_style(style)
-                else:
-                    _sanitize_leaves(style)
-                    unflatten_style(style)
-                    _update(style, current)
+
+# The following is inspired by matplotlib's style library
+# https://github.com/matplotlib/matplotlib/blob/v3.10.3/lib/matplotlib/style/core.py#L45
+def use(
+    style: Optional[
+        str | dict[str, Any] | Sequence[str | dict[str, Any]] | Iterable[str | dict[str, Any]]
+    ] = None,
+    **kwargs,
+):
+    """Use iplotx style setting for a style specification.
+
+    The style name of 'default' is reserved for reverting back to
+    the default style settings.
+
+    Parameters:
+        style: A style specification, currently either a name of an existing style
+            or a dict with specific parts of the style to override. The string
+            "default" resets the style to the default one. If this is a sequence,
+            each style is applied in order.
+        **kwargs: Additional style changes to be applied at the end of any style.
+    """
+    global current
+
+    styles = []
+    if isinstance(style, (dict, str)):
+        styles.append(style)
+    elif style is not None:
+        styles.extend(list(style))
+    if kwargs:
+        styles.append(kwargs)
+
+    # Discard empty styles for speed
+    styles = [style for style in styles if style]
+
+    if len(styles) == 0:
+        return
+
+    # If the first style is a string (internal style), apply it cold. If it's a
+    # dict, apply it hot (on top of the current style(. Any style after the first
+    # is always applied hot - otherwise it would invalidate previous styles.
+    if not isinstance(styles[0], str):
+        # hot insertion on top of current
+        styles.insert(0, current)
+
+    old_style = copy_with_deep_values(current)
+    try:
+        current = merge_styles(styles)
     except:
         current = old_style
         raise
@@ -276,7 +211,12 @@ def reset() -> None:
 
 
 @contextmanager
-def context(style: Optional[str | dict | Sequence] = None, **kwargs):
+def context(
+    style: Optional[
+        str | dict[str, Any] | Sequence[str | dict[str, Any]] | Iterable[str | dict[str, Any]]
+    ] = None,
+    **kwargs,
+):
     """Create a style context for iplotx.
 
     Parameters:
@@ -336,9 +276,7 @@ def unflatten_style(
 
     # top-level adjustments
     if "zorder" in style_flat:
-        style_flat["network_zorder"] = style_flat["grouping_zorder"] = style_flat.pop(
-            "zorder"
-        )
+        style_flat["network_zorder"] = style_flat["grouping_zorder"] = style_flat.pop("zorder")
 
     # Begin recursion
     _inner(style_flat)
@@ -348,6 +286,7 @@ def rotate_style(
     style: dict[str, Any],
     index: Optional[int] = None,
     key: Optional[Hashable] = None,
+    key2: Optional[Hashable] = None,
     props: Optional[Sequence[str]] = None,
 ) -> dict[str, Any]:
     """Rotate leaves of a style for a certain index or key.
@@ -357,6 +296,9 @@ def rotate_style(
         index: The integer to rotate the style leaves into.
         key: For dict-like leaves (e.g. vertex properties specified as a dict-like object over the
             vertices themselves), the key to use for rotation (e.g. the vertex itself).
+        key2: For dict-like leaves, a backup key in case the first key fails. If this is None
+            or also a failure (i.e. KeyError), default to the empty type constructor for the
+            first value of the dict-like style leaf.
         props: The properties to rotate, usually all leaf properties.
 
     Returns:
@@ -369,9 +311,7 @@ def rotate_style(
         {'vertex': {'size': 10}}
     """
     if (index is None) and (key is None):
-        raise ValueError(
-            "At least one of 'index' or 'key' must be provided to rotate_style."
-        )
+        raise ValueError("At least one of 'index' or 'key' must be provided to rotate_style.")
 
     if props is None:
         props = tuple(prop for prop in style_leaves if prop not in nonrotating_leaves)
@@ -383,23 +323,46 @@ def rotate_style(
         if val is None:
             continue
         # Try integer indexing for ordered types
-        if (index is not None) and isinstance(
-            val, (tuple, list, np.ndarray, pd.Index, pd.Series)
-        ):
-            style[prop] = np.asarray(val)[index % len(val)]
+        if (index is not None) and isinstance(val, (tuple, list, np.ndarray, pd.Index, pd.Series)):
+            # NOTE: cannot cast to ndarray because rotation might involve
+            # cross-type lists (e.g. ["none", False])
+            style[prop] = list(val)[index % len(val)]
         # Try key indexing for unordered, dict-like types
         if (
             (key is not None)
             and (not isinstance(val, (str, tuple, list, np.ndarray)))
             and hasattr(val, "__getitem__")
         ):
-            # If only a subset of keys is provided, default the other ones
-            # to the empty type constructor (e.g. 0 for ints, 0.0 for floats,
-            # empty strings).
+            # If only a subset of keys is provided, try the default value a la
+            # defaultdict. If that fails, use an empty constructor
             if key in val:
-                style[prop] = val[key]
+                newval = val[key]
+            elif key2 is not None and (key2 in val):
+                newval = val[key2]
             else:
-                valtype = type(next(iter(val.values())))
-                style[prop] = valtype()
+                try:
+                    newval = val[key]
+                except KeyError:
+                    valtype = type(next(iter(val.values())))
+                    newval = valtype()
+            style[prop] = newval
 
     return style
+
+
+def add_style(name: str, style: dict[str, Any]) -> None:
+    """Add a style to the default dictionary of styles.
+
+    Parameters:
+        name: The name of the style to add.
+        style: A dictionary with the style properties to add.
+    """
+    with context(["default", style]):
+        styles[name] = get_style()
+
+
+# Populate style library (default is already there)
+for name, style in style_library.items():
+    if name != "default":
+        add_style(name, style)
+        del name, style

iplotx/style/leaf_info.py

@@ -0,0 +1,44 @@
+# These properties are at the bottom of a style dictionary. Values corresponding
+# to these keys are rotatable.
+rotating_leaves = (
+    "cmap",
+    "color",
+    "size",
+    "edgecolor",
+    "facecolor",
+    "linewidth",
+    "linestyle",
+    "alpha",
+    "zorder",
+    "tension",
+    "offset",
+    "rotate",
+    "marker",
+    "waypoints",
+    "horizontalalignment",
+    "verticalalignment",
+    "boxstyle",
+    "hpadding",
+    "vpadding",
+    "hmargin",
+    "vmargin",
+    "ports",
+    "width",
+    "height",
+)
+
+# These properties are also terminal style properties, but they cannot be rotated.
+# This might change in the future as the API improves.
+nonrotating_leaves = (
+    "paralleloffset",
+    "looptension",
+    "loopmaxangle",
+    "vertexpadding",
+    "extend",
+    "deep",
+    "angular",
+    "curved",
+)
+
+# Union of all style leaves (rotating and nonrotating)
+style_leaves = tuple(list(rotating_leaves) + list(nonrotating_leaves))