[3.12] gh-71966: Move the module docstring from _pydecimal to decimal (GH-117919)

[miss-islington]

Now it is set even if the C implementation is used.

Also add a one-line synopsis.
(cherry picked from commit c69968f)

Co-authored-by: Serhiy Storchaka [email protected]

• Issue: Sync-up docstrings in C version of the the decimal module #71966

[Yhg1s]

This change has broken sequential test running (and thus the 3.12.4 release):

% ./python -m test test_decimal test_statistics test_time test_tokenize Using random seed: 1104459681 0:00:00 load avg: 0.13 Run 4 tests sequentially 0:00:00 load avg: 0.13 [1/4] test_decimal 0:00:02 load avg: 0.13 [2/4] test_statistics test test_statistics failed -- multiple errors occurred; run in verbose mode for details 0:00:02 load avg: 0.20 [3/4/1] test_time -- test_statistics failed (1 error, 1 failure) test test_time failed -- Traceback (most recent call last): File "/home/thomas/python/python/3.12/Lib/test/test_time.py", line 859, in _check_rounding expected = expected_func(value) ^^^^^^^^^^^^^^^^^^^^ File "/home/thomas/python/python/3.12/Lib/test/test_time.py", line 924, in <lambda> lambda ns: self.decimal_round(ns * SEC_TO_NS)) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/thomas/python/python/3.12/Lib/test/test_time.py", line 889, in decimal_round return int(d) ^^^^^^ ValueError: cannot convert NaN to integer During handling of the above exception, another exception occurred: Traceback (most recent call last): File "/home/thomas/python/python/3.12/Lib/test/test_time.py", line 922, in test_FromSecondsObject self.check_float_rounding( File "/home/thomas/python/python/3.12/Lib/test/test_time.py", line 883, in check_float_rounding self._check_rounding(pytime_converter, expected_func, File "/home/thomas/python/python/3.12/Lib/test/test_time.py", line 861, in _check_rounding self.fail("Error on timestamp conversion: %s" % debug_info) AssertionError: Error on timestamp conversion:{'value': -9223372036.0, 'rounding': 'ROUND_FLOOR'} 0:00:04 load avg: 0.20 [4/4/2] test_tokenize -- test_time failed (1 failure) test test_tokenize failed -- Traceback (most recent call last): File "/home/thomas/python/python/3.12/Lib/test/test_tokenize.py", line 1250, in test_decistmt self.assertEqual(eval(decistmt(s)), AssertionError: Decimal('-3.21716034271725826E-7') != Decimal('-3.217160342717258261933904529E-7') test_tokenize failed (1 failure) == Tests result: FAILURE == 3 tests failed: test_statistics test_time test_tokenize 1 test OK. Total duration: 5.1 sec Total tests: run=1,255 failures=3 skipped=17 Total test files: run=4/4 failed=3 Result: FAILURE 

I believe it's because the (new) decimal.py docstring fiddles with the default context. Making the docstring restore the context fixes the other test failures, but causes decimal's class doctests to fail:

% ./python -m test test_decimal test_statistics test_time test_tokenize Using random seed: 971918697 0:00:00 load avg: 0.02 Run 4 tests sequentially 0:00:00 load avg: 0.02 [1/4] test_decimal test test_decimal failed -- Traceback (most recent call last): File "/home/thomas/python/python/3.12/Lib/doctest.py", line 2256, in runTest raise self.failureException(self.format_failure(new.getvalue())) AssertionError: Failed doctest test for decimal.Decimal.__round__ File "/home/thomas/python/python/3.12/Lib/decimal.py", line unknown line number, in __round__ ---------------------------------------------------------------------- File "/home/thomas/python/python/3.12/Lib/decimal.py", line ?, in decimal.Decimal.__round__ Failed example: round(Decimal('-Infinity'), 37) Exception raised: Traceback (most recent call last): File "/home/thomas/python/python/3.12/Lib/doctest.py", line 1368, in __run exec(compile(example.source, filename, "single", File "<doctest decimal.Decimal.__round__[10]>", line 1, in <module> round(Decimal('-Infinity'), 37) File "/home/thomas/python/python/3.12/Lib/_pydecimal.py", line 1795, in __round__ return self.quantize(exp) ^^^^^^^^^^^^^^^^^^ File "/home/thomas/python/python/3.12/Lib/_pydecimal.py", line 2480, in quantize return context._raise_error(InvalidOperation, ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/thomas/python/python/3.12/Lib/_pydecimal.py", line 3972, in _raise_error raise error(explanation) decimal.InvalidOperation: quantize with one INF ---------------------------------------------------------------------- File "/home/thomas/python/python/3.12/Lib/decimal.py", line ?, in decimal.Decimal.__round__ Failed example: round(Decimal('sNaN123'), 0) Exception raised: Traceback (most recent call last): File "/home/thomas/python/python/3.12/Lib/doctest.py", line 1368, in __run exec(compile(example.source, filename, "single", File "<doctest decimal.Decimal.__round__[11]>", line 1, in <module> round(Decimal('sNaN123'), 0) File "/home/thomas/python/python/3.12/Lib/_pydecimal.py", line 1795, in __round__ return self.quantize(exp) ^^^^^^^^^^^^^^^^^^ File "/home/thomas/python/python/3.12/Lib/_pydecimal.py", line 2473, in quantize ans = self._check_nans(exp, context) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/thomas/python/python/3.12/Lib/_pydecimal.py", line 679, in _check_nans return context._raise_error(InvalidOperation, 'sNaN', ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/thomas/python/python/3.12/Lib/_pydecimal.py", line 3972, in _raise_error raise error(explanation) decimal.InvalidOperation: sNaN 0:00:02 load avg: 0.02 [2/4/1] test_statistics -- test_decimal failed (1 failure) 0:00:02 load avg: 0.10 [3/4/1] test_time 0:00:04 load avg: 0.10 [4/4/1] test_tokenize == Tests result: FAILURE == 1 test failed: test_decimal 3 tests OK. Total duration: 5.0 sec Total tests: run=1,255 failures=1 skipped=17 Total test files: run=4/4 failed=1 Result: FAILURE 

@serhiy-storchaka do you have time to look at this today? (I'm in California right now and it's evening already, so unless there's an obvious quick fix I'm overlooking I'll have to delay the 3.12.4 release by another day anyway.)

[Yhg1s]

(Rolling back may also be an option?)

[serhiy-storchaka]

It is strange that this only affects 3.12. For now I have not found anything in the difference between 3.12 and 3.13 in _pydecimal, test_decimal, libregrtest, unittest and doctest that could explain this. This only happens with the C implementation of decimal.

P.S. I finally found how to fix this (see #120147), but I have no idea why is this only needed in 3.12.