gh-117056: fix discrepancy in _decimal/_pydecimal public signatures

[skirpichev]

• Issue: _decimal and _pydecimal compatibility differences #117056

[serhiy-storchaka]

It is unusual to make only self parameter positional-only (unless it conflicts with var-keyword parameter). This looks like code churn. In any case, pydoc removes it, so it doesn't affect its output. I suggest to remove / after self, but leave it for other parameters. It is perhaps fine to keep it in dunder methods.

[serhiy-storchaka]

This is not a public method.

[skirpichev]

In any case, pydoc removes it, so it doesn't affect its output.

Does it?

>>> classA:
... deffoo(self, /):
... pass
... defbar(self):
... pass
... >>> help(A)
Help on class A in module __main__:
class A(builtins.object)
| Methods defined here:
|
| bar(self)
|
| foo(self, /)
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
>>> help(A.foo)
Help on function foo in module __main__:
foo(self, /)
>>> help(A.bar)
Help on function bar in module __main__:
bar(self)

It's removed in the Python sphinx docs, yes, together with self parameter. (By hand. Or using autodoc, e.g. as this toy extension: https://python-gmp.readthedocs.io/en/latest/)

[serhiy-storchaka]

You are right. But this does not affect common use.

BTW, please update also the documentation if all these parameters are not already marked as positional-only.

[AA-Turner]

I agree with Serhiy, I think the self, / is distracting.

[skirpichev]

But this does not affect common use.

I agree with Serhiy, I think the self, / is distracting.

Huh, distracting "/" will anyway appear in the help() output or in the inspect.signature()'s. Per default (C implementation).

I think people who read sources will be less surprised by usual python syntax. And it's just a matter of time when they will come with new bug about incompatible API.

BTW, please update also the documentation if all these parameters are not already marked as positional-only.

There is a ready for review pr: #131990. I hope it does all on sphinx side.

[AA-Turner]

def f(self, /, ...) is generally only used when self might be a valid keyword argument. It isn't needed here, please revert the changes.

[skirpichev]

Then lets close this pr (and, perhaps, issue as well). If API of _pydecimal and _decimal will be incompatible - it's not better than current state of art.

Perhaps, issue will be solved later, when core devs will end war with Python syntax.