Skip to content

Fix inaccurate wording in multiple decimal module docstrings - #155688

Open
lpyu001 wants to merge 1 commit into
python:mainfrom
lpyu001:decimal-docstring-fix
Open

Fix inaccurate wording in multiple decimal module docstrings#155688
lpyu001 wants to merge 1 commit into
python:mainfrom
lpyu001:decimal-docstring-fix

Conversation

@lpyu001

@lpyu001 lpyu001 commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

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.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant