That looks like a terrible signature (enough that I am willing to block on it). Yes it's too bad that so many functions can take either a tuple or two arguments, but that's what we have to work with.
I would just keep it (x=None, y=None) and document in the docstring that x can also be "both". If not, even the original *args, **kwargs seems less terrible.

That looks like a terrible signature (enough that I am willing to block on it).

I agree! This is a awful API! Unfortunately, it's also the exact API that exists right now.

Yes it's too bad that so many functions can take either a tuple or two arguments, but that's what we have to work with. I would just keep it (x=None, y=None) and document in the docstring that x can also be "both".

x_or_both (better names welcome) is always a scalar; it's not one of those that can be a tuple of scalars. If only one positional argument is provided, that argument is used for both x and y - so if we call the first argument x, it becomes impossible to specify (x=1, y=None) 😭

If not, even the original *args, **kwargs seems less terrible.

I don't like this interface, but I think hiding it behind *args, **kwargs is even worse.

The API is quite unpythonic in the sense that it cannot be easily expressed as an explicit function signature. Unfortunately, we have to live with that.

We're mainly changing to explicit signatures so that they are easier to understand for the user. IMO this is not the case for the proposed signature.

In this case, I would just go for margins(*args, *, tight=True, *kw) And describe the possible signatures in a Call signatures block in the docstring.

I consider the new signature to have negative informativity. At least with the old one you just accept that you have to read the docstring and move on...

I agree that the proposed API is pretty confusing.

Is one or two positional args really unpythonic? I agree that I hate *args as much as the next person, but sometimes its useful, as is being able to pop a kwarg to see if it was passed. Would the pythonic way of doing this just be to force both positional args to be passed with the same value? (Not being argumentative, truly curious how this can/should be done in future).

Oh, sorry. I was confusing the situation with xlim(), which can take xlim(a, b) or xlim((a, b)).

Here what we really have is broadcasting, which is a bit different. I can't say I really like any of the options, with still a mild preference for *args, **kwargs, but I guess the proposal is not as bad as what I thought :-)

@jklymak I would say that one or two positional args is not unpythonic per se. What's really making things difficult is that the semantics of argument i depends on the number of arguments. This implies that you cannot give it a reasonable explicit name in the signature.

Other languages can do this by method overloading. However, Python does not support method overloading because it's not needed for the typical use cases that require method overloading in other languages. This use case here may be one of the few examples, where actually method overloading could add a benefit in Python.

You really have two semantically different signatures for the same functions. That's rarely what you want (and probably also a reason Python doesn't have method overloading), but I sort of see the point here.

Since we only have one signature to state, it should not give raise to misleading code. All these calls should work:

margins(margin)
margins(xmargin, ymargin)
margins(x=xmargin)
margins(y=ymargin)
margins(x=xmargin, y=ymargin)

In particular, the first three cannot be fulfilled simultaneously with a single explicit signature. Therefore, I've propsed above to keep *args and *kw for this mechanism and document the possibilities in the docstring.

Not sure referring a 10 (or so) year old PEP is really helpful, but ymmv :)

Linked mostly for the motivations section, and to provide context that this is a Py3-only feature. MM does V, but happy to edit if requested.