Repository navigation
[MNT]: API consistency for Figure layout_engine #29636
Description
Summary
Summary
Split out of #24617. Before we can implement this, we need a though API discussion (#24617 (comment)).
Current state:
- We have figure(..., layout=...)
- But set/get_layout_engine().
I'm opposed to creating an alias set_layout/set_layout_engine.
We should converge to one name. While layout_engine is more explicit layout seems good enough. If the name would only be used rarely I'd go with the longer option, but since we don't have a layout engine by default, people must often use plt.subplots(..., layout="constrained") and plt.subplots(..., layout_engine="constrained") is way too long to just create a figure.
Semi-OT: I'm tempted to start a discussion whether we can make constrained layout the default. It is what people would want most of the time, and having to always explicitly enable it is a nuissance. Of course it's a significant change and imacts basically all figures created with matplotlib. OTOH it's "only" a shift of some of the graphic elements, which does not affect the visual expression of the figure - I claim most people would not notice. And if you want the previous behavior, you can set the layout engine to none.
Either way, if we want to move forward on the layout topic, we should agree on one name and slowly phase out the other. At least discourage, but possibly pending deprecate.
Proposed fix
No response
Activity
anntzer commented on Feb 17, 2025
I think that having a layout = layout_engine alias is really the easiest way forward here. We can even specify a preference for one of them but it's not even clear that we need one, e.g. we don't bother stating whether one should prefer c=... or color=....
Semi-OT: I think the "only one way to do it" philosophy is getting pushed a bit far here. I believe that what is confusing to end users is not having multiple strict aliases for the same function/property/kwarg (strict alias: whereever one sees "layout_engine" in an API name, it can be replaced by "layout"), so they are fine to have (within reason) and we should not break backcompat on these gratuitiously. Rather, it is having multiple similarly named things that behave in subtly different manners (ax.set_xlabel vs. plt.xlabel, the c argument to plot() vs. the c argument to scatter (#27765), etc.), and that is what we should try to improve.
timhoffm commented on Feb 17, 2025
Even strict aliases are a disadvantage:
While for a single case that may be acceptable, it adds up when we do if often. So we should really try to avoid aliases unless there are very good reasons. API consistency, API stability and small API size are all values which we cannot always have all at once. It must be conscious trade off. The weak variant on stability and small API size is to discourage certain APIs, which I think would be an appropriate way forward for set_layout_engine() - if we value consistency higher and want set_layout.