gh-150534: Add C23 half-turn trigonometric `*pi` functions by jepler · Pull Request #150555 · python/cpython

jepler · 2026-05-28T14:09:42Z

See #150534 and https://discuss.python.org/t/add-half-turns-functions-cospi-et-al-to-math-module-following-c23-ieee754-2019/107550/5 for discussion and context.

The following functions are added to the math module:

acospi
asinpi
atanpi
atan2pi
cospi
sinpi
tanpi

The following aspects of a new feature are covered in this pull request:

Add tests
Add documentation including NEWS.d & whatsnew
Add configure-time checks for function presence
Regenerate configure

The math_testcases.txt cases are based on glibc's test cases, and their input & output values have been used. I supplemented this with tests of inf/nan arguments.

I extended math_testcases.txt so that it can test n-arg functions, and used it to test atan2pi.

Issue: Add 'half turns' functions (cospi et al) to math module following C23 & IEEE754-2019 #150534

Closes: #150534

* Add tests * Add documentation * Add configure-time checks for function presence * Regenerate configure No news item added, pending creation of a github issue. As committed, the local implementation of the functions is always used. For production, the #undefs should be removed so that the presence of the functions is detected by configure and used by mathmodule.

read-the-docs-community · 2026-05-28T14:16:19Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32917581 | 📁 Comparing 56da6fc against main (f386f1f)

🔍 Preview build

11 files changed · ± 11 modified

± Modified

skirpichev · 2026-05-29T04:53:25Z

+
+acospi10000 acospi 0.0 -> 0.5
+acospi10001 acospi -0.0 -> 0.5
+acospi10002 acospi 1.0 -> 0.0


Please also test infinite/nan input and values with magnitude > 1. Include appropriate FPE flags, where it's required by the C23 Annex F.

With this, I think you can drop separate tests in the test_math.py for new functions.

skirpichev · 2026-05-29T04:57:09Z

+   The vector in the plane from the origin to point ``(x, y)`` makes this angle
+   with the positive X axis. The point of :func:`atan2pi` is that the signs of both
+   inputs are known to it, so it can compute the correct quadrant for the angle.
+   For example, ``atanpi(1)`` and ``atanpi2(1, 1)`` are both ``1/4``, but
+   ``atanpi2(-1, -1)`` is ``-3/4``.


Suggested change

The vector in the plane from the origin to point ``(x, y)`` makes this angle

with the positive X axis. The point of :func:`atan2pi` is that the signs of both

inputs are known to it, so it can compute the correct quadrant for the angle.

For example, ``atanpi(1)`` and ``atanpi2(1, 1)`` are both ``1/4``, but

``atanpi2(-1, -1)`` is ``-3/4``.

thank you, committed locally and will push shortly. (atanpi2 -> atan2pi)

skirpichev · 2026-05-29T05:00:18Z

+#undef HAVE_ACOSPI
+#undef HAVE_ASINPI
+#undef HAVE_ATANPI
+#undef HAVE_ATAN2PI
+#undef HAVE_COSPI
+#undef HAVE_SINPI
+#undef HAVE_TANPI


Why you did this? libm functions will be not used, isn't?

mistake, deleted. I add/remove this block for local testing to make sure that my implementations of the new functions are being tested.

skirpichev · 2026-05-29T05:04:49Z

+   integral or close to an integer).  It conforms to IEEE 754-2008.
+   Special cases are handled as for glibc 2.41 __acospi.


Are you sure? I don't see this function in the IEEE 754-2008. I think it come with the IEEE 754-2019 (Table 9.1).

I think it's better to reference the Annex F of C23 standard. Same below.

I finally noticed that I copypasted "IEEE 754-2008" from an old internal comment on m_sinpi without checking. It'll be good to have this corrected.

skirpichev · 2026-05-29T05:06:14Z

+        return cos(x);
+    }
+    x = fabs(x - 2.0 * round(0.5 * x));
+    if (islessequal(x, 0.25)) {


As argument is finite - it doesn't make sense to use "silent" comparison functions:

Suggested change

if (islessequal(x, 0.25)) {

if (x <= 0.25) {

skirpichev · 2026-05-29T05:06:31Z

+    if (x == 0.5) {
+        return 0.0;
+    }
+    if (islessequal(x, 0.75)) {


Suggested change

if (islessequal(x, 0.75)) {

if (x <= 0.75) {

skirpichev · 2026-05-29T05:07:37Z

    {"asinh",           math_asinh,     METH_O,         math_asinh_doc},
+    {"asinpi",          math_asinpi,    METH_O,         math_asinpi_doc},
    {"atan",            math_atan,      METH_O,         math_atan_doc},
-    {"atan2",           _PyCFunction_CAST(math_atan2),     METH_FASTCALL,  math_atan2_doc},


This is unrelated change.

skirpichev · 2026-05-29T05:12:31Z

+   acos(x)/pi, giving accurate results for all finite x (especially x
+   integral or close to an integer).  It conforms to IEEE 754-2008.


This is misleading. Apparently, it's copy-pasted stub from sinpi/cospi, etc. Please correct this. Same below for other arc-functions.

serhiy-storchaka

Please add also a What's New entry.

serhiy-storchaka · 2026-05-29T17:44:42Z


+.. function:: atanpi(x)
+
+   Return the arc tangent of *x*, in half-turns. The result is between ``-1/2`` and


Since the result is a float, should not we use 0.5 instead 0f 1/2? The same question for other documentation and examples.

That's a great question. These doc blocks were made by copypaste of the existing block (e.g., atan) then removing pi.

It's clear why an expression using pi is used in the existing atan2 docs. However, it's possible to ask which would be clearer in the atan2 comment: -.75*pi or -3*pi/4. I feel like the answer to this might make it clear whether -.75 or -3/4 is clearer in the new function's documentation.

Thoughts?

-3*pi/4 is an expression. I think it is clearer in such way. But for atan2pi we can use exact number: -0.75.

I don't have a firm opinion, I'm just pointing out a possible option. I am fine with any option.

.. as suggested in review

jepler · 2026-05-29T18:49:33Z

Branch updated based on review comments. Thank you for your reviews.

serhiy-storchaka

LGTM. 👍

skirpichev · 2026-05-29T21:27:21Z

+   acos(x)/pi, giving accurate results for all finite x (especially x
+   integral or close to an integer). It conforms to C23 Annex 'F'.


This still is misleading, just as for other arc-functions.

skirpichev · 2026-05-29T21:28:06Z

+/*
+   acos(x)/pi, giving accurate results for all finite x (especially x
+   integral or close to an integer). It conforms to C23 Annex 'F'.
+   Special cases are handled as for glibc 2.41 __acospi.


This is redundant, special cases described by Annex:

Suggested change

Special cases are handled as for glibc 2.41 __acospi.

Same for all comments.

Also use the surrounding style of two spaces after a sentence- ending period.

jepler · 2026-05-30T17:29:51Z

I've updated the PR with additional comment changes as requested.

picnixz · 2026-05-30T17:32:24Z

+   For example, ``atanpi(1)`` and ``atan2pi(1, 1)`` are both ``.25``, but
+   ``atan2pi(-1, -1)`` is ``-.75``.


Suggested change

For example, ``atanpi(1)`` and ``atan2pi(1, 1)`` are both ``.25``, but

``atan2pi(-1, -1)`` is ``-.75``.

For example, ``atanpi(1)`` and ``atan2pi(1, 1)`` are both ``0.25``, but

``atan2pi(-1, -1)`` is ``-0.75``.

Let's be consistent with fractional values.

picnixz · 2026-05-30T17:35:09Z

    {"atan2",           _PyCFunction_CAST(math_atan2),     METH_FASTCALL,  math_atan2_doc},
    {"atanh",           math_atanh,     METH_O,         math_atanh_doc},
+    {"atan2pi",         _PyCFunction_CAST(math_atan2pi),   METH_FASTCALL,  math_atan2pi_doc},
+    {"atanpi",          math_atanpi,      METH_O,       math_atanpi_doc},


{"atanpi", math_atanpi, METH_O, math_atanpi_doc},

make it aligned with METH_O of atanh

jepler added 4 commits May 27, 2026 12:41

Add news item and remove testing code

03808d6

tests: Add math_testcases for the new *pi functions

e9ec2b6

fix discussion of atan2pi

bb57325

jepler requested review from AA-Turner, corona10, emmatyping and erlend-aasland as code owners May 28, 2026 14:09

bedevere-app Bot mentioned this pull request May 28, 2026

Add 'half turns' functions (cospi et al) to math module following C23 & IEEE754-2019 #150534

Open

bedevere-app Bot added the awaiting review label May 28, 2026

jepler added 2 commits May 28, 2026 12:16

fix wrongly changed m_sinpi

7650fa5

regenerate autoconf files with make regen-configure

86de1c0

skirpichev requested changes May 29, 2026

View reviewed changes

bedevere-app Bot added awaiting core review and removed awaiting review labels May 29, 2026

skirpichev requested a review from picnixz May 29, 2026 05:14

skirpichev reviewed May 29, 2026

View reviewed changes

Comment thread Doc/library/math.rst

serhiy-storchaka reviewed May 29, 2026

View reviewed changes

jepler added 11 commits May 29, 2026 13:04

remove accidentally-committed code

be980bf

mathdata: Add +-inf, nan tests for new functions

d3254cd

test_math: Let "mtestfile" test 2-arg functions

6d8dd17

math_testcases: Add testcases for atan2pi

0c7fdfb

These are now tested in math_testcases.txt

aa93326

Add whatsnew entry for math module changes

e0ede77

Correct doc typos (atanpi2 -> atan2pi)

694f479

Correct comment about which standard this conforms to

ab68cdc

Add 'versionadded' notes to new functions

359ac19

Use float constants, not expressions, for simple values.

6cec4b8

.. as suggested in review

as x is finite, regular comparisons can be used here

d66a2c3

Merge remote-tracking branch 'origin/main' into c23-math-pifuns

dcc5040

serhiy-storchaka approved these changes May 29, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels May 29, 2026

skirpichev reviewed May 29, 2026

View reviewed changes

hugovk reviewed May 30, 2026

View reviewed changes

Comment thread Doc/library/math.rst

jepler added 3 commits May 30, 2026 10:47

remove comment about glibc

1f98ce6

Update comments based on review.

12fcd24

Also use the surrounding style of two spaces after a sentence- ending period.

math_methods: Re-sort and conform to surrounding spacing

56da6fc

jepler requested a review from skirpichev May 30, 2026 17:32

picnixz reviewed May 30, 2026

View reviewed changes

picnixz changed the title ~~gh-150534: Add C23 math "*pi" functions~~ gh-150534: Add C23 half-turn trigonometric *pi functions May 30, 2026

		integral or close to an integer). It conforms to IEEE 754-2008.
		Special cases are handled as for glibc 2.41 __acospi.

		acos(x)/pi, giving accurate results for all finite x (especially x
		integral or close to an integer). It conforms to IEEE 754-2008.


		.. function:: atanpi(x)

		Return the arc tangent of x, in half-turns. The result is between ``-1/2`` and

		For example, ``atanpi(1)`` and ``atan2pi(1, 1)`` are both ``.25``, but
		``atan2pi(-1, -1)`` is ``-.75``.

Uh oh!

Conversation

jepler commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jepler May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jepler commented May 29, 2026

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jepler commented May 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jepler commented May 28, 2026 •

edited

Loading

read-the-docs-community Bot commented May 28, 2026 •

edited

Loading

jepler May 29, 2026 •

edited

Loading