Skip to content

gh-131885: update function signatures with / in decimal module #131990

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

gh-131885: update function signatures with / in decimal module #131990

wants to merge 2 commits into from

Conversation

donBarbos
Copy link
Contributor

@donBarbos donBarbos commented Apr 1, 2025 •
edited by skirpichev
Loading

@bedevere-app bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Apr 1, 2025
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Apr 1, 2025
@bedevere-app bedevere-app bot mentioned this pull request Apr 1, 2025
Open
5 tasks
@donBarbos donBarbos changed the title gh-131885: Add / for decimal.Context methods docs gh-131885: Document / for decimal.Context methods Apr 1, 2025
skirpichev
skirpichev reviewed Apr 2, 2025
View reviewed changes
Copy link
Contributor

@skirpichev skirpichev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor Author

donBarbos commented Apr 2, 2025 •
edited
Loading

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

@python-cla-bot

This comment was marked as resolved.

Sign in to view
@skirpichev skirpichev self-requested a review August 13, 2025 03:02
@skirpichev skirpichev requested a review from AA-Turner August 13, 2025 03:09
@skirpichev
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Contributor

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.

@skirpichev skirpichev added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Aug 13, 2025
@skirpichev skirpichev changed the title gh-131885: Document / for decimal.Context methods gh-131885: update function signatures with / in decimal module Aug 13, 2025
@skirpichev skirpichev self-requested a review August 13, 2025 07:09
@donBarbos
Copy link
Contributor Author

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
Copy link
Contributor

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

skirpichev
skirpichev approved these changes Aug 13, 2025
View reviewed changes
Copy link
Contributor

@skirpichev skirpichev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think all is fixed.

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

@donBarbos
Copy link
Contributor Author

Thank you for review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@skirpichev skirpichev skirpichev approved these changes

@AA-Turner AA-Turner Awaiting requested review from AA-Turner

Assignees
No one assigned
Labels
awaiting core review docs Documentation in the Doc dir needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes skip news
Projects
Docs PRs
Status: Todo
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@donBarbos @skirpichev