Better signature and docstring for Artist.set

timhoffm · timhoffm · commit 7bffaa26f67e · 2021-07-04T01:09:40.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,51 @@ class Artist:
 
     zorder = 0
 
+    def __init_subclass__(cls):
+        # Inject custom set() methods into the subclass with signature and
+        # docstring based on the subclasses' properties.
+        # docstring based on the subclasses' properties.
+
+        if 'set' in cls.__dict__:
+            return  # don't overwrite set if the subclass defines set itself.
+
+        def set(self, **kwargs):
+            Artist.set(self, **kwargs)
+
+        cls.set = 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.__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 +1148,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 +1710,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()
