gh-133895: provide C99 Annex G return values for cmath's functions

Doc/library/cmath.rst

@@ -38,6 +38,14 @@ the function is then applied to the result of the conversion.
       1.4142135623730951j
 
 
+Most functions compute and return the C99 Annex G recommended result.
+If the standard recommends raising ``FE_DIVBYZERO`` or ``FE_INVALID``
+floating-point exceptions, a :exc:`ValueError` is raised and the recommended
+result is available as the ``value`` attribute of the exception object.
+If a range error occurs due to an overflow in any component of the result,
+an :exc:`OverflowError` is raised.
+
+
 ====================================================  ============================================
 **Conversions to and from polar coordinates**
 --------------------------------------------------------------------------------------------------

Doc/whatsnew/3.15.rst

@@ -324,6 +324,12 @@ calendar
   dark mode and have been migrated to the HTML5 standard for improved accessibility.
   (Contributed by Jiahao Li and Hugo van Kemenade in :gh:`137634`.)
 
+cmath
+-----
+
+* Provide C99 Annex G return values for :mod:`cmath`'s functions as the
+  ``value`` attribute of exception objects.
+  (Contributed by Sergey B Kirpichev in :gh:`133895`.)
 
 collections
 -----------

Lib/test/test_cmath.py

@@ -318,22 +318,23 @@ def polar_complex(z):
             if 'divide-by-zero' in flags or 'invalid' in flags:
                 try:
                     actual = function(arg)
-                except ValueError:
-                    continue
+                except ValueError as exc:
+                    actual = exc.value
                 else:
                     self.fail('ValueError not raised in test '
                           '{}: {}(complex({!r}, {!r}))'.format(id, fn, ar, ai))
 
-            if 'overflow' in flags:
+            elif 'overflow' in flags:
                 try:
                     actual = function(arg)
-                except OverflowError:
-                    continue
+                except OverflowError as exc:
+                    actual = exc.value if fn != 'polar' else complex(*exc.value)
                 else:
                     self.fail('OverflowError not raised in test '
                           '{}: {}(complex({!r}, {!r}))'.format(id, fn, ar, ai))
 
-            actual = function(arg)
+            else:
+                actual = function(arg)
 
             if 'ignore-real-sign' in flags:
                 actual = complex(abs(actual.real), actual.imag)

Misc/NEWS.d/next/Library/2025-06-01-10-38-00.gh-issue-133895.0X7c-V.rst

@@ -0,0 +1,2 @@
+Provide C99 Annex G return values for :mod:`cmath`'s functions as the
+``value`` attribute of exception objects.  Patch by Sergey B Kirpichev.