Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

If this PR is merged, it looks to me like #146402 can (and should) be reverted.

We must handle error in same way for all libm functions.

The mathmodule currently has 3 ways of handling 1-argument libm functions:

• Functions that cannot overflow (e.g., acos, atan) use math_1(arg, func, /*can_overflow=*/0, err_msg)
• Functions that can overflow (e.g., cosh, exp) use math_1(arg, func, /*can_overflow=*/1, err_msg)
• Functions that are known to set errno properly (e.g., erf, gamma) use math_1a(arg, func, err_msg)

Maybe it's not so bad to have math_2ne for 2-argument functions that are known not to need error checking (e.g., atan2) as well as the current math_2 (for the others).

Perhaps, we could modify math_2() helper to check that errno!=EDOM, if inputs and output are finite. When domain error occurs - result should be nan.

But I think that a little wrapper for libm's atan2 is better, if we are going to add some workaround for the given issue.

@vstinner, can you look at this at your convenience?
I anticipate that this PR will also fix Solaris to return the correct results (#138573), so the relevant math/cmath tests will not need to be skipped on that platform. Please advise whether I should revert #146402 as part of this PR. If so, I'll do that and would then ask you to run on the buildbots.

You also could use new helper function for copysign.

On another hand, I would prefer just remove errno stuff from math_2(), per #156145. It should be possible for all two-argument functions: atan2, atan2pi, copysign, remainder and fmod (which could utilize same wrapper).

You also could use new helper function for copysign.

My thinking is only to do what is necessary to fix the bug (the incorrect results when building with Intel or Solaris math libraries). Then, I would recommend applying this fix to Python 3.14 and 3.15. With that in mind, I don't want to make any enhancements that are not necessary to fix the reported bug.

On another hand, I would prefer just remove errno stuff from math_2(), per #156145. It should be possible for all two-argument functions: atan2, atan2pi, copysign, remainder and fmod (which could utilize same wrapper).

Yes, 156145 can have a more ambitious goal.

Can you trigger the buildbots to run this PR? I am not able to check myself that it works on Solaris. (I do think it will work based on what I read in the Solaris bug report.)

My thinking is only to do what is necessary to fix the bug

Then we loose chance of using new helper function for copysign().

Can you trigger the buildbots to run this PR?

!buildbot Solaris

!buildbot Solaris

🤖 New build scheduled with the buildbot fleet by @skirpichev for commit 5b6d005 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F153148%2Fmerge

The command will test the builders whose names match following regular expression: Solaris

The builders matched are:

• SPARCv9 Oracle Solaris 11.4 PR

Then we loose chance of using new helper function for copysign().

OK, I'll add that commit tomorrow. Since it will be a separate commit, it can easily be reverted (or skipped when squashing all the commits before the final merge). The same is true for the comments Victor requested--they're in their own separate commit.

@serhiy-storchaka @skirpichev @picnixz: What is your opinion on changing cmath.phase() behavior?

FWIW, I don't think there is a change in behavior: atan2() shouldn't overflow. Underflows in Python are silent.

I totally forgot about this PR. Let me read the issue and the history first (and now my speech resembles that of an AI...)

I don't think there is a change in behavior

Well, fixing a bug is a change in behavior. But I know what you mean.

Let me walk through an example (using Python 3.13.5 built to use GNU libm).
Consider the following two complex points:

>>> z1 = complex(+1E300, 1E-320)
>>> z2 = complex(-1E300, 1E-320)

and note that, for both of them, imag/real underflows to zero:

>>> 1E-320 / +1E300
0.0
>>> 1E-320 / -1E300
-0.0

The math module's atan2 gives the correct result for the following:

>>> math.atan2(1E-320, +1E300)
0.0
>>> math.atan2(1E-320, -1E300)
3.141592653589793

In the first case, the result underflows to 0.0. The atan2() function in GNU's libm sets errno = ERANGE to indicate underflow. That is, the infinitely precise result is not exactly zero, but libm rounded the result to zero in order to return a double precision result. Python code in mathmodule.c ignores errno == ERANGE on underflow.

The wrapper math_2() calls is_error(), which does the following:

    else if (errno == ERANGE) {
        if (fabs(x) < 1.5)  // <==== x is the atan2 result, which is 0.0
            result = 0;
        else
            PyErr_SetString(PyExc_OverflowError,
                            "math range error");
    }

In the second case, the infinitely precise result is very close to Pi, and libm rounds the result to three point something in order to return a double precision result. The result did not underflow to zero (nor did it overflow to infinity), so GNU's libm leaves errno unchanged. Python code had set errno = 0 before calling libm's atan2(), so it's still zero. Python returns the result.

Now, we get to the bug.

>>> cmath.phase(z1)
Traceback (most recent call last):
  File "<python-input-12>", line 1, in <module>
    cmath.phase(z1)
    ~~~~~~~~~~~^^^^
OverflowError: math range error

Python calls GNU libm's atan2() exactly as before. The result is 0.0 and errno == ERANGE. Python sees that (errno != 0) and raises OverflowError. There's no code in cmathmodule.c to distinguish underflow from overflow.
[Sure, we could fix this by copying the underflow-ignoring code from mathmodule.c, but that wouldn't fix the issue caused by Intel and Solaris math libraries setting errno = EDOM. Also, it would be unnecessarily slow and confusing.]

In the second case,

>>> cmath.phase(z2)
3.141592653589793

GNU's atan2() returns the correct result and leaves errno unchanged, so it's still zero. Python returns the result.

With this PR:

>>> z1 = complex(+1E300, 1E-320)
>>> z2 = complex(-1E300, 1E-320)

>>> math.atan2(1E-320, +1E300)
0.0
>>> math.atan2(1E-320, -1E300)
3.141592653589793

>>> cmath.phase(z1)
0.0
>>> cmath.phase(z2)
3.141592653589793

@picnixz: So did you find time to review this change?

No I'm sorry. I am quite busy in my daily job and haven't found time for that. I think I will have time on Sunday as I'm flying (or next thursday as I'm flying back). But the past weeks have been very busy (I can only do simple triaging or review).

Now, after a quick glance:

• On my system (openSUSE, clang, 3.14.5): math.atan2(1e-320, 1e300) gives 0 but cmath.phase(complex(1e300, 1e-320)) raises. This simple discrepancy bothers me already.
• Now, "A range error occurs if x is positive and nonzero y/x is too close to zero." for atan2(y, x). So I understand this as "a range error occurs", period and that's because we are underflowing, not overflowing (since the domain is bounded as observed).
• So, consideering the only possibility for having a range error is an underflow, we should raise UnderflowError (if it existed). But it doesn't exist. So it's preferrable that we do nothing (PR behavior).

This makes at least cmath.phase(complex(1e300, 1e-320)) and math.atan2(1e-230, 1e300) consistent. However, I would like to make sure that you document the reason why we ignore errno in this case (that is, atan2() can only raise an optional EDOM, which we can ignore, or an errno due to overflow/underflow. Since overflow is not possible for atan2, we only have underflows and since underflows are silent in Python, we don't care.

Did I catch the issue well? we wouldn't break code though, just fixing things. What I'm worried about however is implementations that really want to raise an EDOM for $(\pm0, \pm0)$. According to Wikipedia:

The C function atan2, and most other computer implementations, are designed to reduce the effort of transforming cartesian to polar coordinates and so always define atan2(0, 0). On implementations without signed zero, or when given positive zero arguments, it is normally defined as 0. It will always return a value in the range [−π, π] rather than raising an error or returning a NaN (Not a Number).

In addition, Annex F says what to return when using (0,0). I would have imagined:

• If compiler conforms to Annex F -> ignore EDOM as Annex F tells you what to return. We get a value, that's it. Since we don't detect the error handling for math errors, we don't need to care about an optional error being returned right (and whether that error should be considered fatal).
• If compiler doesn't conform, we forward the EDOM since we don't know whether the returned value is meant to be used or if it's garbage.

But in the second case, we can say it's garbage in-garbage out and it's likely an unsupported compiler (even less supported than icx!) So... I guess we canj ust ignore EDOM?

Did I get it right?

would like to make sure that you document the reason why we ignore errno in this case

Done.

Did I get it right?

Yes. Although, technically, it's about the C math library, not the compiler. (It's possible to mix and match, e.g., use the Intel or Solaris math libraries with GCC.) Perhaps the title of my bug report for icx was too informal.

Note that a math library might not strictly conform to Annex F for many reasons. Here, we only care about the values it returns for atan2(), which I would venture to guess would be correct even if the compiler and math library as a whole cannot claim to be compliant with the entirety of Annex F.
We have tests in Python for phase, which will fail if the C math library's atan2(\pm 0, \pm 0) returns wrong values. If that should happen (for an unsupported build platform), nothing prevents Python from adding some check to configure.ac and providing a m_atan2() and enabling it via #ifndef HAVE_ATAN2 similarly to how it's done for m_atan2pi(). Of course, the better solution would be for the platform's math library to make a fix.
Note that the tests are in Python 3.14, and the only reported failure (prior to my building Python with icx) was on Solaris.

Finally, I would like to suggest that, in my opinion, raising an exception where one should not happen is a serious bug. A Python programmer would not be expected to put cmath.phase() inside a try block. Therefore, this bug in Python leads to a crash.

My understanding is that bugfixes for Python 3.13 must be merged this month.

Do not click the "Update branch" button without a good reason because it notifies everyone watching the PR that there are new changes, when there are not, and it uses up limited CI resources.

We unfortunately get past 3.13 release and it is not security-only. I am ok with putting it in 3.16 and maybe 3.14/3.15 but I would be interested in having some NumPy's opinion just in case (cc @ngoldbaum). I think fixing the phase/atan2 inconsistency takes precedence over other behavioral change concerns.

Thanks for the ping. NumPy already behaves the way CPython will behave after this PR. The only difference is that NumPy can optionally surface the underflow, and it reports it as an underflow, never as an overflow.

Yeah so this matches what users will expect. I am fine with this PR then! thanks for doing it.