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

[skirpichev]

• Issue: decimal: Use Argument Clinic #73487

[skirpichev]

Docstrings diff

--- ref.txt 2025-08-18 17:44:04.254784483 +0300+++ patch.txt 2025-08-18 17:10:44.875040300 +0300@@ -582,12 +582,14 @@
| so this operation returns its argument unchanged.
|
| compare(self, /, other, context=None)
- | Compare self to other. Return a decimal value:+ | Compare self to other.
|
- | a or b is a NaN ==> Decimal('NaN')- | a < b ==> Decimal('-1')- | a == b ==> Decimal('0')- | a > b ==> Decimal('1')+ | Return a decimal value:+ |+ | a or b is a NaN ==> Decimal('NaN')+ | a < b ==> Decimal('-1')+ | a == b ==> Decimal('0')+ | a > b ==> Decimal('1')
|
| compare_signal(self, /, other, context=None)
| Identical to compare, except that all NaNs signal.
@@ -651,13 +653,16 @@
| exactly.
|
| exp(self, /, context=None)
- | Return the value of the (natural) exponential function e**x at the given- | number. The function always uses the ROUND_HALF_EVEN mode and the result- | is correctly rounded.+ | Return the value of the (natural) exponential function e**x.+ |+ | The function always uses the ROUND_HALF_EVEN mode and the result is+ | correctly rounded.
|
| fma(self, /, other, third, context=None)
- | Fused multiply-add. Return self*other+third with no rounding of the- | intermediate product self*other.+ | Fused multiply-add.+ |+ | Return self*other+third with no rounding of the intermediate product+ | self*other.
|
| >>> Decimal(2).fma(3, 5)
| Decimal('11')
@@ -680,9 +685,9 @@
| otherwise.
|
| is_normal(self, /, context=None)
- | Return True if the argument is a normal finite non-zero number with an- | adjusted exponent greater than or equal to Emin. Return False if the- | argument is zero, subnormal, infinite or a NaN.+ | Return True if the argument is a normal number and False otherwise.+ |+ | Normal number is a finite nonzero number, which is not subnormal.
|
| is_qnan(self, /)
| Return True if the argument is a quiet NaN, and False otherwise.
@@ -695,27 +700,33 @@
| Return True if the argument is a signaling NaN and False otherwise.
|
| is_subnormal(self, /, context=None)
- | Return True if the argument is subnormal, and False otherwise. A number is- | subnormal if it is non-zero, finite, and has an adjusted exponent less- | than Emin.+ | Return True if the argument is subnormal, and False otherwise.+ |+ | A number is subnormal if it is non-zero, finite, and has an adjusted+ | exponent less than Emin.
|
| is_zero(self, /)
| Return True if the argument is a (positive or negative) zero and False
| otherwise.
|
| ln(self, /, context=None)
- | Return the natural (base e) logarithm of the operand. The function always- | uses the ROUND_HALF_EVEN mode and the result is correctly rounded.+ | Return the natural (base e) logarithm of the operand.+ |+ | The function always uses the ROUND_HALF_EVEN mode and the result is+ | correctly rounded.
|
| log10(self, /, context=None)
- | Return the base ten logarithm of the operand. The function always uses the- | ROUND_HALF_EVEN mode and the result is correctly rounded.+ | Return the base ten logarithm of the operand.+ |+ | The function always uses the ROUND_HALF_EVEN mode and the result is+ | correctly rounded.
|
| logb(self, /, context=None)
- | For a non-zero number, return the adjusted exponent of the operand as a- | Decimal instance. If the operand is a zero, then Decimal('-Infinity') is- | returned and the DivisionByZero condition is raised. If the operand is- | an infinity then Decimal('Infinity') is returned.+ | Return the adjusted exponent of the operand as a Decimal instance.+ |+ | If the operand is a zero, then Decimal('-Infinity') is returned and the+ | DivisionByZero condition is raised. If the operand is an infinity then+ | Decimal('Infinity') is returned.
|
| logical_and(self, /, other, context=None)
| Return the digit-wise 'and' of the two (logical) operands.
@@ -727,46 +738,47 @@
| Return the digit-wise 'or' of the two (logical) operands.
|
| logical_xor(self, /, other, context=None)
- | Return the digit-wise 'exclusive or' of the two (logical) operands.+ | Return the digit-wise 'xor' of the two (logical) operands.
|
| max(self, /, other, context=None)
- | Maximum of self and other. If one operand is a quiet NaN and the other is- | numeric, the numeric operand is returned.+ | Maximum of self and other.+ |+ | If one operand is a quiet NaN and the other is numeric, the numeric+ | operand is returned.
|
| max_mag(self, /, other, context=None)
- | Similar to the max() method, but the comparison is done using the absolute- | values of the operands.+ | As the max() method, but compares the absolute values of the operands.
|
| min(self, /, other, context=None)
- | Minimum of self and other. If one operand is a quiet NaN and the other is- | numeric, the numeric operand is returned.+ | Minimum of self and other.+ |+ | If one operand is a quiet NaN and the other is numeric, the numeric+ | operand is returned.
|
| min_mag(self, /, other, context=None)
- | Similar to the min() method, but the comparison is done using the absolute- | values of the operands.+ | As the min() method, but compares the absolute values of the operands.
|
| next_minus(self, /, context=None)
- | Return the largest number representable in the given context (or in the- | current default context if no context is given) that is smaller than the- | given operand.+ | Returns the largest representable number smaller than itself.
|
| next_plus(self, /, context=None)
- | Return the smallest number representable in the given context (or in the- | current default context if no context is given) that is larger than the- | given operand.+ | Returns the smallest representable number larger than itself.
|
| next_toward(self, /, other, context=None)
+ | Returns the number closest to self, in the direction towards other.+ |
| If the two operands are unequal, return the number closest to the first
| operand in the direction of the second operand. If both operands are
| numerically equal, return a copy of the first operand with the sign set
| to be the same as the sign of the second operand.
|
| normalize(self, /, context=None)
- | Normalize the number by stripping the rightmost trailing zeros and- | converting any result equal to Decimal('0') to Decimal('0e0'). Used- | for producing canonical values for members of an equivalence class.- | For example, Decimal('32.100') and Decimal('0.321000e+2') both normalize- | to the equivalent value Decimal('32.1').+ | Normalize the number by stripping trailing 0s+ |+ | This also change anything equal to 0 to 0e0. Used for producing+ | canonical values for members of an equivalence class. For example,+ | Decimal('32.100') and Decimal('0.321000e+2') both normalize to+ | the equivalent value Decimal('32.1').
|
| number_class(self, /, context=None)
| Return a string describing the class of the operand.
@@ -819,23 +831,25 @@
| all its arithmetic. Included for compatibility with the specification.
|
| remainder_near(self, /, other, context=None)
- | Return the remainder from dividing self by other. This differs from- | self % other in that the sign of the remainder is chosen so as to minimize- | its absolute value. More precisely, the return value is self - n * other- | where n is the integer nearest to the exact value of self / other, and- | if two integers are equally near then the even one is chosen.+ | Return the remainder from dividing self by other.+ |+ | This differs from self % other in that the sign of the remainder is+ | chosen so as to minimize its absolute value. More precisely, the return+ | value is self - n * other where n is the integer nearest to the exact+ | value of self / other, and if two integers are equally near then the+ | even one is chosen.
|
| If the result is zero then its sign will be the sign of self.
|
| rotate(self, /, other, context=None)
- | Return the result of rotating the digits of the first operand by an amount- | specified by the second operand. The second operand must be an integer in- | the range -precision through precision. The absolute value of the second- | operand gives the number of places to rotate. If the second operand is- | positive then rotation is to the left; otherwise rotation is to the right.- | The coefficient of the first operand is padded on the left with zeros to- | length precision if necessary. The sign and exponent of the first operand are- | unchanged.+ | Returns a rotated copy of self's digits, value-of-other times.+ |+ | The second operand must be an integer in the range -precision through+ | precision. The absolute value of the second operand gives the number of+ | places to rotate. If the second operand is positive then rotation is to+ | the left; otherwise rotation is to the right. The coefficient of the+ | first operand is padded on the left with zeros to length precision if+ | necessary. The sign and exponent of the first operand are unchanged.
|
| same_quantum(self, /, other, context=None)
| Test whether self and other have the same exponent or both are NaN.
@@ -846,22 +860,25 @@
| exactly.
|
| scaleb(self, /, other, context=None)
- | Return the first operand with the exponent adjusted the second. Equivalently,- | return the first operand multiplied by 10**other. The second operand must be- | an integer.+ | Return the first operand with the exponent adjusted the second.+ |+ | Equivalently, return the first operand multiplied by 10**other. The+ | second operand must be an integer.
|
| shift(self, /, other, context=None)
- | Return the result of shifting the digits of the first operand by an amount- | specified by the second operand. The second operand must be an integer in- | the range -precision through precision. The absolute value of the second- | operand gives the number of places to shift. If the second operand is- | positive, then the shift is to the left; otherwise the shift is to the- | right. Digits shifted into the coefficient are zeros. The sign and exponent- | of the first operand are unchanged.+ | Returns a shifted copy of self's digits, value-of-other times.+ |+ | The second operand must be an integer in the range -precision through+ | precision. The absolute value of the second operand gives the number+ | of places to shift. If the second operand is positive, then the shift+ | is to the left; otherwise the shift is to the right. Digits shifted+ | into the coefficient are zeros. The sign and exponent of the first+ | operand are unchanged.
|
| sqrt(self, /, context=None)
- | Return the square root of the argument to full precision. The result is- | correctly rounded using the ROUND_HALF_EVEN rounding mode.+ | Return the square root of the argument to full precision.+ |+ | The result is correctly rounded using the ROUND_HALF_EVEN rounding mode.
|
| to_eng_string(self, /, context=None)
| Convert to an engineering-type string.

[AA-Turner]

Why rename?

[skirpichev]

It's how actually spec variable named. Mostly useful for search now.

[AA-Turner]

The docstring changes all look reasonable to me.

[serhiy-storchaka]

LGTM with @AA-Turner's suggestions. 👍

[skirpichev]

Next step: #137931