Better document Axes.set() #19884
Comments
|
I like the idea (and really like Artist.set in general). FWIW dynamically rewriting the signature is quite easy, something like: diff --git i/lib/matplotlib/artist.py w/lib/matplotlib/artist.py
index b6f13f898..5e17e3f18 100644
--- i/lib/matplotlib/artist.py
+++ w/lib/matplotlib/artist.py
@@ -1,6 +1,7 @@
from collections import OrderedDict, namedtuple
from functools import wraps
import inspect
+from inspect import Signature, Parameter
import logging
from numbers import Number
import re
@@ -87,6 +88,11 @@ def _stale_axes_callback(self, val):
_XYPair = namedtuple("_XYPair", "x y")
+class _Unset: # Not the same as "None" for many properties...
+ def __repr__(self):
+ return "<UNSET>"
+
+
class Artist:
"""
Abstract base class for objects that render into a FigureCanvas.
@@ -96,6 +102,24 @@ class Artist:
zorder = 0
+ def __init_subclass__(cls):
+ # A wrapper function, so that we can set its signature just for this
+ # subclass.
+
+ def set(self, **kwargs):
+ Artist.set(**kwargs)
+
+ cls.set = set
+ set.__doc__ = Artist.set.__doc__
+ cls._update_set_signature()
+
+ @classmethod
+ def _update_set_signature(cls):
+ cls.set.__signature__ = Signature(
+ [Parameter("self", Parameter.POSITIONAL_OR_KEYWORD),
+ *[Parameter(prop, Parameter.KEYWORD_ONLY, default=_Unset())
+ for prop in ArtistInspector(cls).get_setters()]])
+
def __init__(self):
self._stale = True
self.stale_callback = None
@@ -1565,6 +1589,9 @@ class ArtistInspector:
return lines
+Artist._update_set_signature()
+
+
def getp(obj, property=None):and generating a longer docstring (e.g. with the summary line for each property) is likely doable as well. For auto-ordering, I guess we could arrange so that inherited properties come last (we likely care more about Axes.set_xlim than Axes.set_rasterized) and/or list things in the order in which they appear in the source (there's co_firstlineno or inspect.getsourcelines for that), which should be reasonable... A separate |
|
Order ist necessary, because there are quite a few parameters. Not sure if our code is well organized so that any automatic rule (Inheritance / code-order) gives satisfying results. |
|
At least we could consider reordering the |
|
While I'm not too sensitive on that topic, that'd appears to be too much code churn. (but maybe we are lucky and only need to move one function??). |
|
Closed by #20569. |
Problem
The property batch setter is a nice way for a more compact configuration compared to various lines of
ax.set_*()calls.(Note: using kwargs is quite common with other plotting libraries, so this approach seems generally appealing).
Axes.set()is essentially undocumented:and that content is far too general and too abstract to be of any help.
Suggested Improvement
We should re-introduce
Axes.setinto the API docs.That method needs a more approachable description than "A property batch setter. Pass kwargs to set properties."
Ideally, the signature should be explicit and not
**kwargs, which would enable completion. There are two possible ways of doing this:The first one has the advantage that this would trivially expand to all artists.
The second one has the advantage that we can easily specify a meaningful order. Since we rarely change the available properties, hard-coding with a test would be good enough.
The text was updated successfully, but these errors were encountered: