added support for list of dicts of paths to path.effects rcparams

story645 · anntzer · story645 · commit a5a75766a077 · 2023-09-28T13:11:02.000-04:00
new path.effects validation of list of patheffect functions and/or
dicts specifying functions
created xkcd.mplstyle and shimmed it into plt.xkcd()
new validate_anydict and validate_path_effects methods in rcsetup

Co-authored-by: Antony Lee &lt;anntzer.lee@gmail.com&gt;
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -137,6 +137,7 @@
 from collections import namedtuple
 from collections.abc import MutableMapping
 import contextlib
+import copy
 import functools
 import importlib
 import inspect
@@ -163,7 +164,6 @@
 from matplotlib._api import MatplotlibDeprecationWarning
 from matplotlib.rcsetup import validate_backend, cycler
 
-
 _log = logging.getLogger(__name__)
 
 __bibtex__ = r"""@Article{Hunter:2007,
@@ -759,6 +759,10 @@ def __getitem__(self, key):
                 from matplotlib import pyplot as plt
                 plt.switch_backend(rcsetup._auto_backend_sentinel)
 
+        elif key == "path.effects" and self is globals().get("rcParams"):
+            # to avoid circular imports
+            return self._load_path_effects()
+
         return self._get(key)
 
     def _get_backend_or_none(self):
@@ -809,6 +813,14 @@ def copy(self):
             rccopy._set(k, self._get(k))
         return rccopy
 
+    def _load_path_effects(self):
+        """defers loading of patheffects to avoid circular imports"""
+        import matplotlib.patheffects as path_effects
+
+        return [pe if isinstance(pe, path_effects.AbstractPathEffect)
+                else getattr(path_effects, pe.pop('name'))(**pe)
+                for pe in copy.deepcopy(self._get('path.effects'))]
+
 
 def rc_params(fail_on_error=False):
     """Construct a `RcParams` instance from the default Matplotlib rc file."""
diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
@@ -677,7 +677,10 @@
                     #         line (in pixels).
                     #     - *randomness* is the factor by which the length is
                     #         randomly scaled.
-#path.effects:
+#path.effects:      # patheffects functions, args, and, kwargs, e.g 
+                    # {'name': 'withStroke', 'linewidth': 4},
+                    # {'name': 'SimpleLineShadow'}
+
 
 
 ## ***************************************************************************
diff --git a/lib/matplotlib/mpl-data/stylelib/xkcd.mplstyle b/lib/matplotlib/mpl-data/stylelib/xkcd.mplstyle
@@ -0,0 +1,30 @@
+## default xkcd style
+
+# line
+lines.linewidth : 2.0
+
+# font
+font.family : xkcd, xkcd Script, Humor Sans, Comic Neue, Comic Sans MS
+font.size   : 14.0
+
+# axes
+axes.linewidth  : 1.5
+axes.grid       : False
+axes.unicode_minus: False
+axes.edgecolor: black
+
+# ticks
+xtick.major.size : 8
+xtick.major.width: 3
+ytick.major.size : 8
+ytick.major.width: 3
+
+# grids
+grid.linewidth: 0.0
+
+# figure
+figure.facecolor: white
+
+# path
+path.sketch : 1, 100, 2
+path.effects: {'name': 'withStroke', 'linewidth': 4, 'foreground': 'w' }
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -747,27 +747,8 @@ def xkcd(
     stack = ExitStack()
     stack.callback(dict.update, rcParams, rcParams.copy())  # type: ignore
 
-    from matplotlib import patheffects
-    rcParams.update({
-        'font.family': ['xkcd', 'xkcd Script', 'Humor Sans', 'Comic Neue',
-                        'Comic Sans MS'],
-        'font.size': 14.0,
-        'path.sketch': (scale, length, randomness),
-        'path.effects': [
-            patheffects.withStroke(linewidth=4, foreground="w")],
-        'axes.linewidth': 1.5,
-        'lines.linewidth': 2.0,
-        'figure.facecolor': 'white',
-        'grid.linewidth': 0.0,
-        'axes.grid': False,
-        'axes.unicode_minus': False,
-        'axes.edgecolor': 'black',
-        'xtick.major.size': 8,
-        'xtick.major.width': 3,
-        'ytick.major.size': 8,
-        'ytick.major.width': 3,
-    })
-
+    rcParams.update({**style.library["xkcd"],
+                    'path.sketch': (scale, length, randomness)})
     return stack
 
 
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -97,6 +97,10 @@ def f(s):
                     val = [scalar_validator(v.strip()) for v in s if v.strip()]
                 else:
                     raise
+        elif isinstance(s, dict):
+            # assume dict is a value in the iterator and not the iterator
+            # since iterating over dict only iterates over keys
+            val = [scalar_validator(s)]
         # Allow any ordered sequence type -- generators, np.ndarray, pd.Series
         # -- but not sets, whose iteration order is non-deterministic.
         elif np.iterable(s) and not isinstance(s, (set, frozenset)):
@@ -125,9 +129,35 @@ def f(s):
 
 def validate_any(s):
     return s
+
 validate_anylist = _listify_validator(validate_any)
 
 
+def validate_anydict(allow_none=True, required_keys=None):
+    """Validate dictionary, check if keys are missing"""
+
+    required_keys = required_keys if required_keys else set()
+
+    def _validate_dict(d):
+        try:
+            d = ast.literal_eval(d)
+        except ValueError:
+            pass
+
+        if allow_none and d is None:
+            return d
+
+        if isinstance(d, dict):
+            if missing_keys := (required_keys - d.keys()):
+                raise ValueError(f"Missing required key: {missing_keys!r}")
+            return d
+
+        raise ValueError(f"Input {d!r} must be a dictionary {{'k': v}} "
+                         f"{'or None' if allow_none else ''}")
+
+    return _validate_dict
+
+
 def _validate_date(s):
     try:
         np.datetime64(s)
@@ -565,6 +595,23 @@ def validate_sketch(s):
         raise ValueError("Expected a (scale, length, randomness) triplet")
 
 
+def validate_path_effects(s):
+    if not s:
+        return []
+
+    _validate = validate_anydict(allow_none=True, required_keys={'name'})
+    # string list of dict {k1: 1, k2:2}, {k1:2}
+    # validate_anylist relies on , for parsing so parse here instead
+    if isinstance(s, str) and s.startswith("{"):
+        s = ast.literal_eval(s)
+        if isinstance(s, dict):
+            # list of one dict
+            return _validate(s)
+
+    return [pe if getattr(pe, '__module__', "") == 'matplotlib.patheffects'
+            else _validate(pe) for pe in validate_anylist(s)]
+
+
 def _validate_greaterthan_minushalf(s):
     s = validate_float(s)
     if s > -0.5:
@@ -1290,7 +1337,7 @@ def _convert_validator_spec(key, conv):
     "path.simplify_threshold": _validate_greaterequal0_lessequal1,
     "path.snap":               validate_bool,
     "path.sketch":             validate_sketch,
-    "path.effects":            validate_anylist,
+    "path.effects":            validate_path_effects,
     "agg.path.chunksize":      validate_int,  # 0 to disable chunking
 
     # key-mappings (multi-character mappings should be a list/tuple)
diff --git a/lib/matplotlib/rcsetup.pyi b/lib/matplotlib/rcsetup.pyi
@@ -2,6 +2,7 @@ from cycler import Cycler
 
 from collections.abc import Callable, Iterable
 from typing import Any, Literal, TypeVar
+from matplotlib.patheffects import AbstractPathEffect
 from matplotlib.typing import ColorType, LineStyleType, MarkEveryType
 
 interactive_bk: list[str]
@@ -28,6 +29,8 @@ class ValidateInStrings:
 
 def validate_any(s: Any) -> Any: ...
 def validate_anylist(s: Any) -> list[Any]: ...
+def validate_anydict(allow_none: bool = True, required_keys: set[str]|None = None
+) -> Callable[[dict[str, Any]|None], dict[str, Any]]: ...
 def validate_bool(b: Any) -> bool: ...
 def validate_axisbelow(s: Any) -> bool | Literal["line"]: ...
 def validate_dpi(s: Any) -> Literal["figure"] | float: ...
@@ -140,6 +143,7 @@ def _validate_linestyle(s: Any) -> LineStyleType: ...
 def validate_markeverylist(s: Any) -> list[MarkEveryType]: ...
 def validate_bbox(s: Any) -> Literal["tight", "standard"] | None: ...
 def validate_sketch(s: Any) -> None | tuple[float, float, float]: ...
+def validate_path_effects(s: Any) -> list[AbstractPathEffect] | list[dict]: ...
 def validate_hatch(s: Any) -> str: ...
 def validate_hatchlist(s: Any) -> list[str]: ...
 def validate_dashlist(s: Any) -> list[list[float]]: ...
diff --git a/lib/matplotlib/tests/test_rcparams.py b/lib/matplotlib/tests/test_rcparams.py
@@ -12,8 +12,12 @@
 from matplotlib import _api, _c_internal_utils
 import matplotlib.pyplot as plt
 import matplotlib.colors as mcolors
+import matplotlib.patheffects as path_effects
+from matplotlib.testing.decorators import check_figures_equal
+
 import numpy as np
 from matplotlib.rcsetup import (
+    validate_anydict,
     validate_bool,
     validate_color,
     validate_colorlist,
@@ -27,8 +31,10 @@
     validate_int,
     validate_markevery,
     validate_stringlist,
+    validate_path_effects,
     _validate_linestyle,
-    _listify_validator)
+    _listify_validator,
+    )
 
 
 def test_rcparams(tmpdir):
@@ -628,3 +634,88 @@ def test_rcparams_legend_loc_from_file(tmpdir, value):
 
     with mpl.rc_context(fname=rc_path):
         assert mpl.rcParams["legend.loc"] == value
+
+
+@pytest.mark.parametrize("allow_none", [True, False])
+def test_validate_dict(allow_none):
+    fval = validate_anydict(allow_none)
+    assert fval("{'a': 1, 'b': 2}") == {'a': 1, 'b': 2}
+    with pytest.raises(ValueError, match=r"Input \['a', 'b'\] "):
+        fval(['a', 'b'])
+
+    fval = validate_anydict(allow_none, required_keys={'a'})
+    assert fval({'a': 1}) == {'a': 1}
+    with pytest.raises(ValueError, match="Missing required key: {'a'}"):
+        fval({'b': 1})
+
+
+def test_validate_dict_none():
+    assert validate_anydict()(None) is None
+    assert validate_anydict(required_keys={'a'})(None) is None
+
+    with pytest.raises(ValueError,
+                       match=r"Input None must be a dictionary "):
+        validate_anydict(False)(None)
+    with pytest.raises(ValueError,
+                       match=r"Input 0 must be a dictionary {'k': v} or None"):
+        validate_anydict(True)(0)
+
+
+ped = [{'name': 'Normal'},
+       {'name': 'Stroke', 'offset': (1, 2)},
+       {'name': 'withStroke', 'linewidth': 4, 'foreground': 'w'}]
+
+pel = [path_effects.Normal(),
+       path_effects.Stroke((1, 2)),
+       path_effects.withStroke(linewidth=4, foreground='w')]
+
+
+@pytest.mark.parametrize("value", [pel, ped], ids=["func", "dict"])
+def test_path_effects(value):
+    assert validate_path_effects(value) == value
+    for v in value:
+        assert validate_path_effects(value) == value
+
+
+def test_path_effects_string_dict():
+    """test list of dicts properly parsed"""
+    pstr = "{'name': 'Normal'},"
+    pstr += "{'name': 'Stroke', 'offset': (1, 2)},"
+    pstr += "{'name': 'withStroke', 'linewidth': 4, 'foreground': 'w'}"
+    assert validate_path_effects(pstr) == ped
+
+
+@pytest.mark.parametrize("fdict, flist",
+                         [([ped[0]], [pel[0]]),
+                          ([ped[1]], [pel[1]]),
+                          ([ped[2]], [ped[2]]),
+                          (ped, pel)],
+                         ids=['function', 'args', 'kwargs', 'all'])
+@check_figures_equal()
+def test_path_effects_picture(fig_test, fig_ref, fdict, flist):
+    with mpl.rc_context({'path.effects': fdict}):
+        fig_test.subplots().plot([1, 2, 3])
+
+    with mpl.rc_context({'path.effects': flist}):
+        fig_ref.subplots().plot([1, 2, 3])
+
+
+def test_path_effect_errors():
+    with pytest.raises(ValueError, match="Missing required key: {'name'}"):
+        mpl.rcParams['path.effects'] = [{'kwargs': {1, 2, 3}}]
+
+    with pytest.raises(ValueError, match=r"Key path.effects: Input 1 "):
+        mpl.rcParams['path.effects'] = [1, 2, 3]
+
+
+def test_path_effects_from_file(tmpdir):
+    # rcParams['legend.loc'] should be settable from matplotlibrc.
+    # if any of these are not allowed, an exception will be raised.
+    # test for gh issue #22338
+    rc_path = tmpdir.join("matplotlibrc")
+    rc_path.write("path.effects: "
+                  "{'name': 'Normal'}, {'name': 'withStroke', 'linewidth': 2}")
+
+    with mpl.rc_context(fname=rc_path):
+        assert isinstance(mpl.rcParams["path.effects"][0], path_effects.Normal)
+        assert isinstance(mpl.rcParams["path.effects"][1], path_effects.withStroke)
