gh-131885: Use positional-only markers for the decimal module

[donbarbos]

also noticed a missing default value num='0' for create_decimal

• Issue: Update function signatures to use * and / as needed #131885

---

📚 Documentation preview 📚: https://cpython-previews--131990.org.readthedocs.build/en/131990/library/decimal.html#decimal-objects

[skirpichev]

Note that signatures for pure-Python versions differ wrt C-coded extension:

>>> import _decimal, _pydecimal
>>> help(_decimal.getcontext().plus)
Help on built-in function plus:

plus(x, /) method of decimal.Context instance
    Plus corresponds to the unary prefix plus operator in Python, but applies
    the context to the result.

>>> help(_pydecimal.getcontext().plus)
Help on method plus:

plus(a) method of decimal.Context instance
    Plus corresponds to unary prefix plus in Python.

    The operation is evaluated using the same rules as add; the
    operation plus(a) is calculated as add('0', a) where the '0'
    has the same exponent as the operand.

    >>> ExtendedContext.plus(Decimal('1.3'))
    Decimal('1.3')
    >>> ExtendedContext.plus(Decimal('-1.3'))
    Decimal('-1.3')
    >>> ExtendedContext.plus(-1)
    Decimal('-1')

If we are going to add slashes - pure-Python version should be fixed. Or vice-versa.

[donbarbos]

although I'm not a fan of using /, I think it will be easier to make the only positional arguments in pure-Python implementation

and I think here we will need ping more core members

[skirpichev]

Sorry for a delay, it's look ok for me.

Would you like to fix the rest of the decimal sphinx docs in another pr?

[donbarbos]

Would you like to fix the rest of the decimal sphinx docs in another pr?

Sorry, but I don't understand what you mean by "rest of the decimal sphinx docs". Do you mean some new functions like from_number?
If so, then it is probably really worth doing this in a separate PR so that there is still the possibility for bacports here, although maybe it is possible to make backports just more carefully and manually

[skirpichev]

Sorry, but I don't understand what you mean by "rest of the decimal sphinx docs".

For example, setcontext() function:

>>> import _decimal, _pydecimal, inspect
>>> inspect.signature(_decimal.setcontext)
<Signature (context, /)>
>>> inspect.signature(_pydecimal.setcontext)
<Signature (context)>

You should also check Decimal methods.

[donbarbos]

I also thought that there is a lot of / before arguments, but documenting it doesn't seem useful unless I'm missing something

For example, fma method has next signature: fma(self, /, other, third, context=None)

[skirpichev]

Sphinx docs don't include self arguments, so we omit leading /.

[skirpichev]

Yes, I think all is fixed.

There is an odd description of the round() builtin, but it probably should be fixed separately.

[donbarbos]

Thank you for review

[miss-islington-app]

Thanks @donbarbos for the PR, and @AA-Turner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @donbarbos and @AA-Turner, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 043f251154fbac9a4e66243b8cae220a284ed1c4 3.13

[bedevere-app]

GH-137902 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-137904 is a backport of this pull request to the 3.13 branch.