[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.