Customize and improve error messages in the math module.

[rhettinger]

The default error messages on a several math functions are mostly opaque and and unhelpful.

>>> sqrt(-5)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: math domain error

It would require some effort, but the code could be refactored to give a customized and helpful response, a least in common cases (falling back to the C error code message when the cause is not known):

ValueError:  math.sqrt() expects a non-negative input.  See cmath.sqrt() for variation that supports complex numbers
ValueError:  math.log() requires a non-negative input.   

Linked PRs

• gh-101410: Improve error messages in math module #101492
• gh-101410: support custom messages for domain errors in the math module #124299
• gh-101410: customize error messages for 1-arg math functions #129497
• gh-101410: revert loghelper() change in 75f59bb for integer input #132625

[CharlieZhao95]

I checked the error message of sqrt in Julia and here is the result:

julia> sqrt(-5)
ERROR: DomainError with -5.0:
sqrt will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).

Maybe we can also consider adding error messages for input parameters, such as

>>> sqrt(-5)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError:  math.sqrt() expects a non-negative input, got '-5.0'.  
See cmath.sqrt() for variation that supports complex numbers

It seems that we need to expand the macro FUNC1 and the function math_1_to_whatever to add the parameter error_msg to them. Is this a feasible solution? I want to try to work for it. :)

[serhiy-storchaka]

Should the error message contain the value? There is a difference between sqrt() taking -5 and -2.220446049250313e-16. Knowing this difference can help to find an error. Especially if the function definition range is limited from two sides.

On other side, formatting the repr takes a time, and if the exception is common (it is the result of limited precision in other computations), this can harm the average performance. And for math.log() the input can be an arbitrary large integer. Its decimal representation can be arbitrary long and take arbitrary long time for calculation.

[skirpichev]

And for math.log() the input can be an arbitrary large integer.

math.log() is a special snowflake. I think here we should keep here just a basic message like "expected a positive input" in the branch, that handle large integers.