From 70f72fbbd379724265a0975236900f1fafaf0d14 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Thu, 12 Mar 2026 04:33:02 +0300 Subject: [PATCH 1/6] gh-145633: amend dae85c4d939 (refine notes on non-IEEE platforms) * we don't specify what happens on non-IEEE platforms * use rather PY_LITTLE_ENDIAN to get native endianness * mention that unpack functions don't fail in CPython * mention that PyFloat_Pack8 doesn't fail in CPython --- Doc/c-api/float.rst | 43 ++++++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst index ca8d44c25c1ece..8936347112f63c 100644 --- a/Doc/c-api/float.rst +++ b/Doc/c-api/float.rst @@ -192,22 +192,21 @@ string from a C :c:expr:`double`, and the Unpack routines produce a C :c:expr:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the number of bytes in the bytes string. -On platforms that appear to use IEEE 754 formats these functions work by -copying bits. On other platforms, the 2-byte format is identical to the IEEE -754 binary16 half-precision format, the 4-byte format (32-bit) is identical to -the IEEE 754 binary32 single precision format, and the 8-byte format to the -IEEE 754 binary64 double precision format, although the packing of INFs and -NaNs (if such things exist on the platform) isn't handled correctly, and -attempting to unpack a bytes string containing an IEEE INF or NaN will raise an -exception. - -Note that NaNs type may not be preserved on IEEE platforms (signaling NaN become -quiet NaN), for example on x86 systems in 32-bit mode. - +The 2-byte format is the IEEE 754 binary16 half-precision format, the 4-byte +format is the IEEE 754 binary32 single precision format, and the 8-byte format +is the IEEE 754 binary64 double precision format, although the NaNs type may +not be preserved on some platforms while unpacking (signaling NaN become quiet +NaN), for example on x86 systems in 32-bit mode. + +It's assumed, that the :c:expr:`double` type has the IEEE 754 binary64 double +precision format. What happens if it's not true is partly accidental (alas). On non-IEEE platforms with more precision, or larger dynamic range, than IEEE 754 supports, not all values can be packed; on non-IEEE platforms with less -precision, or smaller dynamic range, not all values can be unpacked. What -happens in such cases is partly accidental (alas). +precision, or smaller dynamic range, not all values can be unpacked. The +packing of special numbers like INFs and NaNs (if such things exist on the +platform) may be not handled correctly, and attempting to unpack a bytes string +containing an IEEE INF or NaN may raise an exception. + .. versionadded:: 3.11 @@ -217,13 +216,16 @@ Pack functions The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an :c:expr:`int` argument, non-zero if you want the bytes string in little-endian format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you -want big-endian format (exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN` -constant can be used to use the native endian: it is equal to ``1`` on big -endian processor, or ``0`` on little endian processor. +want big-endian format (exponent first, at *p*). The :c:macro:`PY_LITTLE_ENDIAN` +constant can be used to use the native endian: it is equal to ``0`` on big +endian processor, or ``1`` on little endian processor. Return value: ``0`` if all is OK, ``-1`` if error (and an exception is set, most likely :exc:`OverflowError`). +.. impl-detail:: + The :c:func:`PyFloat_Pack8` function always succeeds in the CPython. + .. c:function:: int PyFloat_Pack2(double x, char *p, int le) Pack a C double as the IEEE 754 binary16 half-precision format. @@ -243,14 +245,17 @@ Unpack functions The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an :c:expr:`int` argument, non-zero if the bytes string is in little-endian format (exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian -(exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN` constant can be used to -use the native endian: it is equal to ``1`` on big endian processor, or ``0`` +(exponent first, at *p*). The :c:macro:`PY_LITTLE_ENDIAN` constant can be used to +use the native endian: it is equal to ``0`` on big endian processor, or ``1`` on little endian processor. Return value: The unpacked double. On error, this is ``-1.0`` and :c:func:`PyErr_Occurred` is true (and an exception is set, most likely :exc:`OverflowError`). +.. impl-detail:: + These functions always succeed in the CPython. + .. c:function:: double PyFloat_Unpack2(const char *p, int le) Unpack the IEEE 754 binary16 half-precision format as a C double. From 11e9292ae4edaafc3a418c58c047c0060a09eb92 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Thu, 12 Mar 2026 05:31:16 +0300 Subject: [PATCH 2/6] -PY_LITTLE_ENDIAN from ignored_c_api.txt --- Tools/check-c-api-docs/ignored_c_api.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index 02a3031e52fb8b..5abf2dc5dcc218 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -31,7 +31,6 @@ PY_DWORD_MAX PY_FORMAT_SIZE_T PY_INT32_T PY_INT64_T -PY_LITTLE_ENDIAN PY_LLONG_MAX PY_LLONG_MIN PY_LONG_LONG From 14f9f5ce26afda752ef3bbdc4461321105b68b7b Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Thu, 12 Mar 2026 05:42:36 +0300 Subject: [PATCH 3/6] +1 --- Tools/check-c-api-docs/ignored_c_api.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index 5abf2dc5dcc218..e464162c52a371 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -38,6 +38,7 @@ PY_SIZE_MAX PY_UINT32_T PY_UINT64_T PY_ULLONG_MAX +PY_BIG_ENDIAN # unicodeobject.h Py_UNICODE_SIZE # cpython/methodobject.h From 9124afb445317f0062bd9c33eff401b1a834bb3e Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 13 Mar 2026 05:31:38 +0300 Subject: [PATCH 4/6] + changes from #140989 --- Doc/c-api/float.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst index 8936347112f63c..0c3e2f387b0860 100644 --- a/Doc/c-api/float.rst +++ b/Doc/c-api/float.rst @@ -194,9 +194,9 @@ number of bytes in the bytes string. The 2-byte format is the IEEE 754 binary16 half-precision format, the 4-byte format is the IEEE 754 binary32 single precision format, and the 8-byte format -is the IEEE 754 binary64 double precision format, although the NaNs type may -not be preserved on some platforms while unpacking (signaling NaN become quiet -NaN), for example on x86 systems in 32-bit mode. +is the IEEE 754 binary64 double precision format, although the NaN type may +not be preserved on some platforms while unpacking (signaling NaNs become quiet +NaNs), for example on x86 systems in 32-bit mode. It's assumed, that the :c:expr:`double` type has the IEEE 754 binary64 double precision format. What happens if it's not true is partly accidental (alas). @@ -215,8 +215,8 @@ Pack functions The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an :c:expr:`int` argument, non-zero if you want the bytes string in little-endian -format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you -want big-endian format (exponent first, at *p*). The :c:macro:`PY_LITTLE_ENDIAN` +format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` and ``p+7``), zero if you +want big-endian format (exponent first, at *p*). The :c:macro:`!PY_LITTLE_ENDIAN` constant can be used to use the native endian: it is equal to ``0`` on big endian processor, or ``1`` on little endian processor. @@ -245,7 +245,7 @@ Unpack functions The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an :c:expr:`int` argument, non-zero if the bytes string is in little-endian format (exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian -(exponent first, at *p*). The :c:macro:`PY_LITTLE_ENDIAN` constant can be used to +(exponent first, at *p*). The :c:macro:`!PY_LITTLE_ENDIAN` constant can be used to use the native endian: it is equal to ``0`` on big endian processor, or ``1`` on little endian processor. From c525e92409896376cfb8e93f40edbb48c9791155 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 13 Mar 2026 06:24:54 +0300 Subject: [PATCH 5/6] -Doc/c-api/float.rst --- Doc/tools/.nitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 54b92f1172e80c..ffe98d332d6e93 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -3,7 +3,6 @@ # Keep lines sorted lexicographically to help avoid merge conflicts. Doc/c-api/descriptor.rst -Doc/c-api/float.rst Doc/c-api/init_config.rst Doc/c-api/intro.rst Doc/c-api/stable.rst From 83b7adb1307c2b302fbabeb6335cb72d7ae0149b Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 13 Mar 2026 10:57:00 +0300 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/c-api/float.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst index 0c3e2f387b0860..aaca0ed6c35038 100644 --- a/Doc/c-api/float.rst +++ b/Doc/c-api/float.rst @@ -198,16 +198,15 @@ is the IEEE 754 binary64 double precision format, although the NaN type may not be preserved on some platforms while unpacking (signaling NaNs become quiet NaNs), for example on x86 systems in 32-bit mode. -It's assumed, that the :c:expr:`double` type has the IEEE 754 binary64 double +It's assumed that the :c:expr:`double` type has the IEEE 754 binary64 double precision format. What happens if it's not true is partly accidental (alas). On non-IEEE platforms with more precision, or larger dynamic range, than IEEE 754 supports, not all values can be packed; on non-IEEE platforms with less precision, or smaller dynamic range, not all values can be unpacked. The packing of special numbers like INFs and NaNs (if such things exist on the -platform) may be not handled correctly, and attempting to unpack a bytes string +platform) may not be handled correctly, and attempting to unpack a bytes string containing an IEEE INF or NaN may raise an exception. - .. versionadded:: 3.11 Pack functions @@ -224,7 +223,7 @@ Return value: ``0`` if all is OK, ``-1`` if error (and an exception is set, most likely :exc:`OverflowError`). .. impl-detail:: - The :c:func:`PyFloat_Pack8` function always succeeds in the CPython. + The :c:func:`PyFloat_Pack8` function always succeeds in CPython. .. c:function:: int PyFloat_Pack2(double x, char *p, int le) @@ -254,7 +253,7 @@ Return value: The unpacked double. On error, this is ``-1.0`` and :exc:`OverflowError`). .. impl-detail:: - These functions always succeed in the CPython. + These functions always succeed in CPython. .. c:function:: double PyFloat_Unpack2(const char *p, int le)