Description
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:
- It doesn't show up in the API docs anymore https://matplotlib.org/devdocs/api/axes_api.html. It used to here https://matplotlib.org/3.2.2/api/axes_api.html#bulk-property-manipulation, but was removed as part of Don't generate individual doc entries for inherited Axes/Axis/Tick methods #14960.
- Currently there is only https://matplotlib.org/devdocs/api/_as_gen/matplotlib.artist.Artist.set.html
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:- Dynamically rewrite the signature.
- Hard-code the signature and add a test, that the parameters match the available properties.
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.