Better signature and docstring for Artist.set

timhoffm · timhoffm · commit 00c92c288ad8 · 2021-07-04T23:19:27.000+02:00
diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
@@ -606,3 +606,4 @@ Other
    Axes.get_default_bbox_extra_artists
    Axes.get_transformed_clip_path_and_affine
    Axes.has_data
+   Axes.set
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -2,6 +2,7 @@
 import contextlib
 from functools import wraps
 import inspect
+from inspect import Signature, Parameter
 import logging
 from numbers import Number
 import re
@@ -10,7 +11,7 @@
 import numpy as np
 
 import matplotlib as mpl
-from . import _api, cbook
+from . import _api, cbook, docstring
 from .path import Path
 from .transforms import (Bbox, IdentityTransform, Transform, TransformedBbox,
                          TransformedPatchPath, TransformedPath)
@@ -84,6 +85,12 @@ def _stale_axes_callback(self, val):
 _XYPair = namedtuple("_XYPair", "x y")
 
 
+class _Unset:
+    def __repr__(self):
+        return "<UNSET>"
+UNSET = _Unset()
+
+
 class Artist:
     """
     Abstract base class for objects that render into a FigureCanvas.
@@ -93,6 +100,56 @@ class Artist:
 
     zorder = 0
 
+    def __init_subclass__(cls):
+        # Inject custom set() methods into the subclass with signature and
+        # docstring based on the subclasses' properties.
+
+        if not hasattr(cls.set, '_autogenerated_signature'):
+            # Don't overwrite cls.set if the subclass or one of its parents
+            # has defined a set method set itself.
+            # If there was no explicit definition, cls.set is inherited from
+            # the hierarchy of auto-generated set methods, which hold the
+            # flag _autogenerated_signature.
+            return
+
+        def set(self, **kwargs):
+            Artist.set(self, **kwargs)
+
+        cls.set = set
+        cls.set.__qualname__ = f"{cls.__qualname__}.set"
+        cls._update_set_signature_and_docstring()
+
+    _PROPERTIES_EXCLUDED_FROM_SET = [
+        'navigate_mode',  # not a user-facing function
+        'figure',         # changing the figure is such a profound operation
+                          # that we don't want this in set()
+        '3d_properties',  # cannot be used as a keyword do to leading digit
+    ]
+
+    @classmethod
+    def _update_set_signature_and_docstring(cls):
+        """
+        Update the signature of the set function to list all properties
+        as keyword arguments.
+
+        Property aliases are not listed in the signature for brevity, but
+        are still accepted as keyword arguments.
+        """
+        cls.set.__signature__ = Signature(
+            [Parameter("self", Parameter.POSITIONAL_OR_KEYWORD),
+             *[Parameter(prop, Parameter.KEYWORD_ONLY, default=UNSET)
+               for prop in ArtistInspector(cls).get_setters()
+               if prop not in Artist._PROPERTIES_EXCLUDED_FROM_SET]])
+        cls.set._autogenerated_signature = True
+
+        cls.set.__doc__ = "\n".join([
+            "Set multiple properties at once.",
+            "",
+            "Supported properties are:",
+            "",
+            f"%({cls.__name__}:kwdoc)s"])
+        docstring.dedent_interpd(cls.set)
+
     def __init__(self):
         self._stale = True
         self.stale_callback = None
@@ -1096,7 +1153,9 @@ def properties(self):
         return ArtistInspector(self).properties()
 
     def set(self, **kwargs):
-        """A property batch setter.  Pass *kwargs* to set properties."""
+        # docstring and signature are auto-generated via
+        # Artist._update_set_signature_and_docstring() at the end of the
+        # module.
         kwargs = cbook.normalize_kwargs(kwargs, self)
         return self.update(kwargs)
 
@@ -1656,3 +1715,7 @@ def kwdoc(artist):
     return ('\n'.join(ai.pprint_setters_rest(leadingspace=4))
             if mpl.rcParams['docstring.hardcopy'] else
             'Properties:\n' + '\n'.join(ai.pprint_setters(leadingspace=4)))
+
+# We defer this to the end of them module, because it needs ArtistInspector
+# to be defined.
+Artist._update_set_signature_and_docstring()
diff --git a/lib/matplotlib/tests/test_artist.py b/lib/matplotlib/tests/test_artist.py
@@ -340,3 +340,38 @@ def func(artist):
     art.remove_callback(oid)
     art.pchanged()  # must not call the callback anymore
     assert func.counter == 2
+
+
+def test_set_signature():
+    """Test autogenerated ``set()`` for Artist subclasses."""
+    class MyArtist1(martist.Artist):
+        def set_myparam1(self, val):
+            pass
+
+    assert hasattr(MyArtist1.set, '_autogenerated_signature')
+    assert 'myparam1' in MyArtist1.set.__doc__
+
+    class MyArtist2(MyArtist1):
+        def set_myparam2(self, val):
+            pass
+
+    assert hasattr(MyArtist2.set, '_autogenerated_signature')
+    assert 'myparam1' in MyArtist2.set.__doc__
+    assert 'myparam2' in MyArtist2.set.__doc__
+
+
+def test_set_is_overwritten():
+    """set() defined in Artist subclasses should not be overwritten."""
+    class MyArtist3(martist.Artist):
+
+        def set(self, **kwargs):
+            """Not overwritten."""
+            pass
+
+    assert not hasattr(MyArtist3.set, '_autogenerated_signature')
+    assert MyArtist3.set.__doc__ == "Not overwritten."
+
+    class MyArtist4(MyArtist3):
+        pass
+
+    assert MyArtist4.set is MyArtist3.set
