gh-73487: Convert _decimal to use Argument Clinic (part 5)

[skirpichev]

• Issue: decimal: Use Argument Clinic #73487

[AA-Turner]

Do you plan to add the remaining macros to this PR?:

• Dec_CONTEXT_GET_SSIZE
• Dec_CONTEXT_GET_ULONG
• Dec_UnaryNumberMethod
• Dec_BinaryNumberMethod
• DecCtx_BoolFunc
• DecCtx_BoolFunc_NO_CTX
• DecCtx_BinaryFunc_NO_CTX

[skirpichev]

Do you plan to add the remaining macros to this PR?:

Yes. I think nothing left now.

[skirpichev]

Docstrings diff:

--- ref.txt 2025-08-21 06:56:01.528958090 +0300+++ patch.txt 2025-08-21 06:54:44.217569503 +0300@@ -268,8 +268,9 @@
| Compare the values numerically with their sign ignored.
|
| minus(self, x, /)
- | Minus corresponds to the unary prefix minus operator in Python, but applies- | the context to the result.+ | Minus corresponds to unary prefix minus in Python.+ |+ | This operation applies the context to the result.
|
| multiply(self, x, y, /)
| Return the product of x and y.
@@ -290,8 +291,9 @@
| Return an indication of the class of x.
|
| plus(self, x, /)
- | Plus corresponds to the unary prefix plus operator in Python, but applies- | the context to the result.+ | Plus corresponds to the unary prefix plus operator in Python.+ |+ | This operation applies the context to the result.
|
| power(self, /, a, b, modulo=None)
| Compute a**b.
@@ -317,12 +319,16 @@
| Return 10.
|
| remainder(self, x, y, /)
- | Return the remainder from integer division. The sign of the result,- | if non-zero, is the same as that of the original dividend.+ | Return the remainder from integer division.+ |+ | The sign of the result, if non-zero, is the same as that of the+ | original dividend.
|
| remainder_near(self, x, y, /)
- | Return x - y * n, where n is the integer nearest the exact value of x / y- | (if the result is 0 then its sign will be the sign of x).+ | Return x - y * n.+ |+ | Here n is the integer nearest the exact value of x / y (if the result+ | is 0 then its sign will be the sign of x).
|
| rotate(self, x, y, /)
| Return a copy of x, rotated by y places.
@@ -605,8 +611,9 @@
| Identical to compare, except that all NaNs signal.
|
| compare_total(self, /, other, context=None)
- | Compare two operands using their abstract representation rather than- | their numerical value. Similar to the compare() method, but the result+ | Compare two operands using their abstract representation.+ |+ | Similar to the compare() method, but the result
| gives a total ordering on Decimal instances. Two Decimal instances with
| the same numeric value but different representations compare unequal
| in this ordering:
@@ -614,25 +621,28 @@
| >>> Decimal('12.0').compare_total(Decimal('12'))
| Decimal('-1')
|
- | Quiet and signaling NaNs are also included in the total ordering. The result- | of this function is Decimal('0') if both operands have the same representation,- | Decimal('-1') if the first operand is lower in the total order than the second,- | and Decimal('1') if the first operand is higher in the total order than the- | second operand. See the specification for details of the total order.- |- | This operation is unaffected by context and is quiet: no flags are changed- | and no rounding is performed. As an exception, the C version may raise- | InvalidOperation if the second operand cannot be converted exactly.+ | Quiet and signaling NaNs are also included in the total ordering. The+ | result of this function is Decimal('0') if both operands have the same+ | representation, Decimal('-1') if the first operand is lower in the+ | total order than the second, and Decimal('1') if the first operand is+ | higher in the total order than the second operand. See the+ | specification for details of the total order.+ |+ | This operation is unaffected by context and is quiet: no flags are+ | changed and no rounding is performed. As an exception, the C version+ | may raise InvalidOperation if the second operand cannot be converted+ | exactly.
|
| compare_total_mag(self, /, other, context=None)
- | Compare two operands using their abstract representation rather than their- | value as in compare_total(), but ignoring the sign of each operand.+ | As compare_total(), but ignores the sign of each operand.
|
- | x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.copy_abs()).+ | x.compare_total_mag(y) is equivalent to+ | x.copy_abs().compare_total(y.copy_abs()).
|
- | This operation is unaffected by context and is quiet: no flags are changed- | and no rounding is performed. As an exception, the C version may raise- | InvalidOperation if the second operand cannot be converted exactly.+ | This operation is unaffected by context and is quiet: no flags are+ | changed and no rounding is performed. As an exception, the C version+ | may raise InvalidOperation if the second operand cannot be converted+ | exactly.
|
| conjugate(self, /)
| Return self.
@@ -678,21 +688,19 @@
| Decimal('11')
|
| is_canonical(self, /)
- | Return True if the argument is canonical and False otherwise. Currently,- | a Decimal instance is always canonical, so this operation always returns- | True.+ | Return True if the argument is canonical and False otherwise.+ |+ | Currently, a Decimal instance is always canonical, so this operation+ | always returns True.
|
| is_finite(self, /)
- | Return True if the argument is a finite number, and False if the argument- | is infinite or a NaN.+ | Return True if the argument is a finite number, and False otherwise.
|
| is_infinite(self, /)
- | Return True if the argument is either positive or negative infinity and- | False otherwise.+ | Return True if the argument is infinite, and False otherwise.
|
| is_nan(self, /)
- | Return True if the argument is a (quiet or signaling) NaN and False- | otherwise.+ | Return True if the argument is a (quiet or signaling) NaN, else False.
|
| is_normal(self, /, context=None)
| Return True if the argument is a normal number and False otherwise.
@@ -704,6 +712,7 @@
|
| is_signed(self, /)
| Return True if the argument has a negative sign and False otherwise.
+ |
| Note that both zeros and NaNs can carry signs.
|
| is_snan(self, /)
@@ -716,8 +725,7 @@
| exponent less than Emin.
|
| is_zero(self, /)
- | Return True if the argument is a (positive or negative) zero and False- | otherwise.+ | Return True if the argument is a zero and False otherwise.
|
| ln(self, /, context=None)
| Return the natural (base e) logarithm of the operand.

[serhiy-storchaka]

LGTM. 👍