From a9b68972276d3ce10aa934a30435d089bd359d2a Mon Sep 17 00:00:00 2001 From: lipengyu Date: Thu, 13 Aug 2026 18:07:05 +0800 Subject: [PATCH 1/3] Fix inaccurate wording in multiple decimal module docstrings --- Lib/_pydecimal.py | 9 +++++---- Modules/_decimal/_decimal.c | 12 ++++++------ Modules/_decimal/clinic/_decimal.c.h | 8 ++++---- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/Lib/_pydecimal.py b/Lib/_pydecimal.py index 57d6143daea43a3..e260e512718387f 100644 --- a/Lib/_pydecimal.py +++ b/Lib/_pydecimal.py @@ -5076,8 +5076,8 @@ def number_class(self, a): """Returns an indication of the class of the operand. The class is one of the following strings: - -sNaN - -NaN + sNaN + NaN -Infinity -Normal -Subnormal @@ -5586,8 +5586,9 @@ def to_integral_value(self, a): When the operand has a negative exponent, the result is the same as using the quantize() operation using the given operand as the left-hand-operand, 1E+0 as the right-hand-operand, and the precision - of the operand as the precision setting, except that no flags will - be set. The rounding mode is taken from the context. + of the operand as the precision setting, except that the Inexact and + Rounded flags will not be set. The rounding mode is taken from the + context. >>> ExtendedContext.to_integral_value(Decimal('2.1')) Decimal('2') diff --git a/Modules/_decimal/_decimal.c b/Modules/_decimal/_decimal.c index ada9b02d690717f..b5e752cad4491aa 100644 --- a/Modules/_decimal/_decimal.c +++ b/Modules/_decimal/_decimal.c @@ -940,12 +940,12 @@ _decimal.Context.Etop Return a value equal to Emax - prec + 1. This is the maximum exponent if the _clamp field of the context is -set to 1 (IEEE clamp mode). Etop() must not be negative. +set to 1 (IEEE clamp mode). [clinic start generated code]*/ static PyObject * _decimal_Context_Etop_impl(PyObject *self) -/*[clinic end generated code: output=f0a3f6e1b829074e input=35b9defc69d5e5d1]*/ +/*[clinic end generated code: output=f0a3f6e1b829074e input=a3e53bbf31ffd330]*/ { return PyLong_FromSsize_t(mpd_etop(CTX(self))); } @@ -6785,7 +6785,7 @@ _decimal.Context.power Compute a**b. If 'a' is negative, then 'b' must be integral. The result will be -inexact unless 'a' is integral and the result is finite and can be +inexact unless 'b' is integral and the result is finite and can be expressed exactly in 'precision' digits. In the Python version the result is always correctly rounded, in the C version the result is almost always correctly rounded. @@ -6803,7 +6803,7 @@ restrictions hold: static PyObject * _decimal_Context_power_impl(PyObject *context, PyTypeObject *cls, PyObject *base, PyObject *exp, PyObject *mod) -/*[clinic end generated code: output=d06d40c37cdd69dc input=178a254468ec189b]*/ +/*[clinic end generated code: output=d06d40c37cdd69dc input=660210a6607ca4b0]*/ { PyObject *a, *b, *c = NULL; PyObject *result; @@ -7063,13 +7063,13 @@ _decimal_Context_apply_impl(PyObject *context, PyTypeObject *cls, /*[clinic input] _decimal.Context.canonical = _decimal.Context.is_normal -Return a new instance of x. +Return x unchanged. [clinic start generated code]*/ static PyObject * _decimal_Context_canonical_impl(PyObject *context, PyTypeObject *cls, PyObject *x) -/*[clinic end generated code: output=f213e433e2032e5e input=025ecb106ac15bff]*/ +/*[clinic end generated code: output=f213e433e2032e5e input=f8fd49573263a2b6]*/ { decimal_state *state = PyType_GetModuleState(cls); if (!PyDec_Check(state, x)) { diff --git a/Modules/_decimal/clinic/_decimal.c.h b/Modules/_decimal/clinic/_decimal.c.h index 8ad883d8a2d14dc..53d4ab59f53470f 100644 --- a/Modules/_decimal/clinic/_decimal.c.h +++ b/Modules/_decimal/clinic/_decimal.c.h @@ -37,7 +37,7 @@ PyDoc_STRVAR(_decimal_Context_Etop__doc__, "Return a value equal to Emax - prec + 1.\n" "\n" "This is the maximum exponent if the _clamp field of the context is\n" -"set to 1 (IEEE clamp mode). Etop() must not be negative."); +"set to 1 (IEEE clamp mode)."); #define _DECIMAL_CONTEXT_ETOP_METHODDEF \ {"Etop", (PyCFunction)_decimal_Context_Etop, METH_NOARGS, _decimal_Context_Etop__doc__}, @@ -5444,7 +5444,7 @@ PyDoc_STRVAR(_decimal_Context_power__doc__, "Compute a**b.\n" "\n" "If \'a\' is negative, then \'b\' must be integral. The result will be\n" -"inexact unless \'a\' is integral and the result is finite and can be\n" +"inexact unless \'b\' is integral and the result is finite and can be\n" "expressed exactly in \'precision\' digits. In the Python version the\n" "result is always correctly rounded, in the C version the result is\n" "almost always correctly rounded.\n" @@ -6139,7 +6139,7 @@ PyDoc_STRVAR(_decimal_Context_canonical__doc__, "canonical($self, x, /)\n" "--\n" "\n" -"Return a new instance of x."); +"Return x unchanged."); #define _DECIMAL_CONTEXT_CANONICAL_METHODDEF \ {"canonical", _PyCFunction_CAST(_decimal_Context_canonical), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _decimal_Context_canonical__doc__}, @@ -7100,4 +7100,4 @@ _decimal_Context_same_quantum(PyObject *context, PyTypeObject *cls, PyObject *co #ifndef _DECIMAL_CONTEXT_APPLY_METHODDEF #define _DECIMAL_CONTEXT_APPLY_METHODDEF #endif /* !defined(_DECIMAL_CONTEXT_APPLY_METHODDEF) */ -/*[clinic end generated code: output=718b1f6c20412350 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=98b3741f9f7a95fd input=a9049054013a1b77]*/ From f1ca0843b1ddee6929f82021760a45e297297e2f Mon Sep 17 00:00:00 2001 From: lipengyu Date: Sun, 16 Aug 2026 09:24:04 +0800 Subject: [PATCH 2/3] address review --- Modules/_decimal/_decimal.c | 14 ++++++++++---- Modules/_decimal/clinic/_decimal.c.h | 12 +++++++++--- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/Modules/_decimal/_decimal.c b/Modules/_decimal/_decimal.c index b5e752cad4491aa..4233f88acd931e9 100644 --- a/Modules/_decimal/_decimal.c +++ b/Modules/_decimal/_decimal.c @@ -940,12 +940,12 @@ _decimal.Context.Etop Return a value equal to Emax - prec + 1. This is the maximum exponent if the _clamp field of the context is -set to 1 (IEEE clamp mode). +set to 1 (IEEE clamp mode). Etop() must not be negative. [clinic start generated code]*/ static PyObject * _decimal_Context_Etop_impl(PyObject *self) -/*[clinic end generated code: output=f0a3f6e1b829074e input=a3e53bbf31ffd330]*/ +/*[clinic end generated code: output=f0a3f6e1b829074e input=35b9defc69d5e5d1]*/ { return PyLong_FromSsize_t(mpd_etop(CTX(self))); } @@ -7063,13 +7063,19 @@ _decimal_Context_apply_impl(PyObject *context, PyTypeObject *cls, /*[clinic input] _decimal.Context.canonical = _decimal.Context.is_normal -Return x unchanged. +Returns the same Decimal object. + +As we do not have different encodings for the same number, the +received object already is in its canonical form. + + >>> ExtendedContext.canonical(Decimal('2.50')) + Decimal('2.50') [clinic start generated code]*/ static PyObject * _decimal_Context_canonical_impl(PyObject *context, PyTypeObject *cls, PyObject *x) -/*[clinic end generated code: output=f213e433e2032e5e input=f8fd49573263a2b6]*/ +/*[clinic end generated code: output=f213e433e2032e5e input=12735851b2e36f1c]*/ { decimal_state *state = PyType_GetModuleState(cls); if (!PyDec_Check(state, x)) { diff --git a/Modules/_decimal/clinic/_decimal.c.h b/Modules/_decimal/clinic/_decimal.c.h index 53d4ab59f53470f..ca9c162544c1455 100644 --- a/Modules/_decimal/clinic/_decimal.c.h +++ b/Modules/_decimal/clinic/_decimal.c.h @@ -37,7 +37,7 @@ PyDoc_STRVAR(_decimal_Context_Etop__doc__, "Return a value equal to Emax - prec + 1.\n" "\n" "This is the maximum exponent if the _clamp field of the context is\n" -"set to 1 (IEEE clamp mode)."); +"set to 1 (IEEE clamp mode). Etop() must not be negative."); #define _DECIMAL_CONTEXT_ETOP_METHODDEF \ {"Etop", (PyCFunction)_decimal_Context_Etop, METH_NOARGS, _decimal_Context_Etop__doc__}, @@ -6139,7 +6139,13 @@ PyDoc_STRVAR(_decimal_Context_canonical__doc__, "canonical($self, x, /)\n" "--\n" "\n" -"Return x unchanged."); +"Returns the same Decimal object.\n" +"\n" +"As we do not have different encodings for the same number, the\n" +"received object already is in its canonical form.\n" +"\n" +" >>> ExtendedContext.canonical(Decimal(\'2.50\'))\n" +" Decimal(\'2.50\')"); #define _DECIMAL_CONTEXT_CANONICAL_METHODDEF \ {"canonical", _PyCFunction_CAST(_decimal_Context_canonical), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _decimal_Context_canonical__doc__}, @@ -7100,4 +7106,4 @@ _decimal_Context_same_quantum(PyObject *context, PyTypeObject *cls, PyObject *co #ifndef _DECIMAL_CONTEXT_APPLY_METHODDEF #define _DECIMAL_CONTEXT_APPLY_METHODDEF #endif /* !defined(_DECIMAL_CONTEXT_APPLY_METHODDEF) */ -/*[clinic end generated code: output=98b3741f9f7a95fd input=a9049054013a1b77]*/ +/*[clinic end generated code: output=24a2345f1ce03ca1 input=a9049054013a1b77]*/ From 2db362fbc25e320a0f3554c7fe136f5511f6dc40 Mon Sep 17 00:00:00 2001 From: lipengyu Date: Sun, 16 Aug 2026 09:43:00 +0800 Subject: [PATCH 3/3] Remove indentation --- Modules/_decimal/_decimal.c | 6 +++--- Modules/_decimal/clinic/_decimal.c.h | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Modules/_decimal/_decimal.c b/Modules/_decimal/_decimal.c index 4233f88acd931e9..b2e6b66a5573c37 100644 --- a/Modules/_decimal/_decimal.c +++ b/Modules/_decimal/_decimal.c @@ -7068,14 +7068,14 @@ Returns the same Decimal object. As we do not have different encodings for the same number, the received object already is in its canonical form. - >>> ExtendedContext.canonical(Decimal('2.50')) - Decimal('2.50') +>>> ExtendedContext.canonical(Decimal('2.50')) +Decimal('2.50') [clinic start generated code]*/ static PyObject * _decimal_Context_canonical_impl(PyObject *context, PyTypeObject *cls, PyObject *x) -/*[clinic end generated code: output=f213e433e2032e5e input=12735851b2e36f1c]*/ +/*[clinic end generated code: output=f213e433e2032e5e input=d9f19ee3e7ed9433]*/ { decimal_state *state = PyType_GetModuleState(cls); if (!PyDec_Check(state, x)) { diff --git a/Modules/_decimal/clinic/_decimal.c.h b/Modules/_decimal/clinic/_decimal.c.h index ca9c162544c1455..8a76b53f6256c19 100644 --- a/Modules/_decimal/clinic/_decimal.c.h +++ b/Modules/_decimal/clinic/_decimal.c.h @@ -6144,8 +6144,8 @@ PyDoc_STRVAR(_decimal_Context_canonical__doc__, "As we do not have different encodings for the same number, the\n" "received object already is in its canonical form.\n" "\n" -" >>> ExtendedContext.canonical(Decimal(\'2.50\'))\n" -" Decimal(\'2.50\')"); +">>> ExtendedContext.canonical(Decimal(\'2.50\'))\n" +"Decimal(\'2.50\')"); #define _DECIMAL_CONTEXT_CANONICAL_METHODDEF \ {"canonical", _PyCFunction_CAST(_decimal_Context_canonical), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _decimal_Context_canonical__doc__}, @@ -7106,4 +7106,4 @@ _decimal_Context_same_quantum(PyObject *context, PyTypeObject *cls, PyObject *co #ifndef _DECIMAL_CONTEXT_APPLY_METHODDEF #define _DECIMAL_CONTEXT_APPLY_METHODDEF #endif /* !defined(_DECIMAL_CONTEXT_APPLY_METHODDEF) */ -/*[clinic end generated code: output=24a2345f1ce03ca1 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=d56f7a18603f50c6 input=a9049054013a1b77]*/