https://github.com/python/cpython/commit/52c01864c4778a351e5aa3584e86ed6fd212a5a4 commit: 52c01864c4778a351e5aa3584e86ed6fd212a5a4 branch: main author: Sergey B Kirpichev <[email protected]> committer: vstinner <[email protected]> date: 2026-03-19T11:42:25Z summary:
gh-145633: Refine notes on non-IEEE platforms (#145845) * 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. Co-authored-by: Stan Ulbrych <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Victor Stinner <[email protected]> files: M Doc/c-api/float.rst M Doc/tools/.nitignore M Tools/check-c-api-docs/ignored_c_api.txt diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst index 6e83e01344a9b2..929b56bd8e8203 100644 --- a/Doc/c-api/float.rst +++ b/Doc/c-api/float.rst @@ -190,24 +190,23 @@ The pack and unpack functions provide an efficient platform-independent way to store floating-point values as byte strings. The Pack routines produce a bytes 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. +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. +* The 2-byte format is the IEEE 754 binary16 half-precision format. +* The 4-byte format is the IEEE 754 binary32 single-precision format. +* The 8-byte format is the IEEE 754 binary64 double-precision format. -Note that NaN type may not be preserved on IEEE platforms (signaling NaNs become -quiet NaNs), for example on x86 systems in 32-bit mode. +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). 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 not be handled correctly, and attempting to unpack a bytes string +containing an IEEE INF or NaN may raise an exception. .. versionadded:: 3.11 @@ -217,9 +216,9 @@ 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`` and ``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*). Use the :c:macro:`!PY_LITTLE_ENDIAN` +constant to select 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`). @@ -236,6 +235,9 @@ most likely :exc:`OverflowError`). Pack a C double as the IEEE 754 binary64 double precision format. + .. impl-detail:: + This function always succeeds in CPython. + Unpack functions ^^^^^^^^^^^^^^^^ @@ -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*). Use the :c:macro:`!PY_LITTLE_ENDIAN` constant to +select 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 CPython. + .. c:function:: double PyFloat_Unpack2(const char *p, int le) Unpack the IEEE 754 binary16 half-precision format as a C double. 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 diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index 02a3031e52fb8b..e464162c52a371 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 @@ -39,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 _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
