Thanks for opening this here. See also #20115 (comment)

xref #20115 (comment)

Matplotlib Artist instances have many properties (approximately the set given by the getter/setters (and we have looked into moving to properties / traitlets / ... for more managed access to them and there are some edge cases like this one that make it hard). As a nice short hand we have a convention that usually **kwargs to the __init__ method of the Artist sub-classes get tossed into self.update which is

Thus we can write things like

ax.plot(x, y, linewidth=5, color='green')

rather than

ln, = ax.plot(x, y)
ln.set_linewidth(5)
ln.set_color('green')

This works on the expectation that a) for a keyword foo there is a method set_foo on the instance b) the method will take 1 positional argument (the value of the keyword) that can be passed in and "do the right thing" (that some of the set_foo methods violate this and take optional arguments is actually one of the biggest sticking points in moving to property-like usage).

One fix would be to exclude constrained_layout_pads from functions that are allowed to be passed to via kwargs (so you would get a clearer exception), but given that we are going to be py38+ for our next release, we have access to positional-only arguements so we can change the signature to

    def set_constrained_layout_pads(self, d=None, /, *,
                                    w_pad=None, h_pad=None,
                                    wspace=None, hspace=None):

which along with a bit of munging in body can make this work as @StefRe expected.

Right, the unexpected thing for me was that this turned up in the docs - obviously we never meant this to be a kwarg for subplots, even if someone could have called it if they knew what to look for. I guess we could have easily made set_constrained_layout_pads something that didn't start with set.

Anyhow, I'm fine w/ the going forward 3.8+ plan. It'd be great to accept a dict as a kwarg. I'm a little concerned that we need to do something for MPL 3.5.x about the documentation. Can we just define FigureBase.set locally, filter out constrained_layout_pads for now, and remember to revert it for 3.6?

I think if we go with @anntzer 's suggestion of filtering on bind(None) rather than parameter count, then we can keep that in place going forward and add the positional-only to make this work for mpl36.

This will be easier to handle once we define artist properties explicitly. Xref proposal in #22749