[lpyu001]

Summary

Fix five inaccurate or misleading decimal.Context docstrings. These changes only update documentation and generated Argument Clinic output; runtime behavior is unchanged.

1. Context.Etop() can return a negative value

Remove the statement that Etop() must not be negative. A valid custom context can have Emax < prec - 1, so Emax - prec + 1 can be negative.

from decimal import Context

c = Context(prec=10, Emax=0, clamp=1)
print(c.Etop())
# -9

2. Context.power() exactness depends on exponent b

Correct the exactness condition from base a being integral to exponent b being integral. A non-integral base raised to an integral exponent can produce an exact result.

from decimal import Context, Decimal, Inexact, Rounded

c = Context()
c.clear_flags()
print(c.power(Decimal("1.5"), 2))
print(c.flags[Inexact], c.flags[Rounded])
# 2.25
# False False

3. Context.canonical() returns its argument unchanged

Clarify that canonical() returns x unchanged. The C implementation returns another reference to the original object rather than creating a new Decimal instance.

from decimal import Context, Decimal

x = Decimal("2.50")
print(Context().canonical(x) is x)
# True

4. _pydecimal.Context.number_class() returns unsigned NaN class names

Correct the documented class names from -NaN and -sNaN to NaN and sNaN. The sign of a NaN is not included in the returned classification string.

from _pydecimal import Context, Decimal

c = Context()
print(c.number_class(Decimal("-NaN")))
print(c.number_class(Decimal("-sNaN")))
# NaN
# sNaN

5. _pydecimal.Context.to_integral_value() can signal other conditions

Clarify that to_integral_value() suppresses only the Inexact and Rounded flags, not all flags. For example, an sNaN still signals InvalidOperation.

from _pydecimal import Context, Decimal, InvalidOperation

c = Context(traps=[])
c.clear_flags()
print(c.to_integral_value(Decimal("sNaN")))
print(bool(c.flags[InvalidOperation]))
# NaN
# True

Argument Clinic output is regenerated for the C docstring changes.

[lpyu001]

Hi, I’m not sure which core developers are most familiar with this module. Would it be possible to invite someone with relevant experience to take a look at this PR? I’m concerned it might otherwise be overlooked ：) @skirpichev

[miss-islington-app]

Thanks @lpyu001 for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14, 3.15.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @lpyu001 and @JelleZijlstra, I could not cleanly backport this to 3.15 due to a conflict.

Please backport manually with cherry_picker, see the devguide for more information.

cherry_picker e03def8c233ead2e6d22fa6d91540d405b2bbeef 3.15

[miss-islington-app]

Sorry, @lpyu001 and @JelleZijlstra, I could not cleanly backport this to 3.14 due to a conflict.

Please backport manually with cherry_picker, see the devguide for more information.

cherry_picker e03def8c233ead2e6d22fa6d91540d405b2bbeef 3.14

[lpyu001]

backport to 3.15 in #160658
backport to 3.14 in #160657

[bedevere-app]

GH-160658 is a backport of this pull request to the 3.15 branch.

[bedevere-app]

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