PEP 757: Rename endian to endianness (#3973)

* Rephrase "Optimize small integers" section for import.
* Elaborate on PyLong_GetNativeLayout() validity.
* Mention PyLong_FreeExport() in the specification.
* Update benchmarks.

Author: vstinner

peps/pep-0757.rst

@@ -63,10 +63,10 @@ API::
         // * -1 for least significant digit first
         int8_t digits_order;
 
-        // Endian:
+        // Endianness:
         // * 1 for most significant byte first (big endian)
         // * -1 for least significant byte first (little endian)
-        int8_t endian;
+        int8_t endianness;
     } PyLongLayout;
 
     PyAPI_FUNC(const PyLongLayout*) PyLong_GetNativeLayout(void);
@@ -82,6 +82,11 @@ API::
 
 Get the native layout of Python :class:`int` objects.
 
+The function must not be called before Python initialization nor after
+Python finalization. The returned layout is valid until Python is
+finalized. The layout is the same for all Python sub-interpreters and
+so it can be cached.
+
 
 Export API
 ----------
@@ -106,6 +111,7 @@ Export a Python integer as a digits array::
     } PyLongExport;
 
     int PyLong_Export(PyObject *obj, PyLongExport *array);
+    void PyLong_FreeExport(PyLongExport *array);
 
 On CPython 3.14, no memory copy is needed, it's just a thin wrapper to
 expose Python int internal digits array.
@@ -215,21 +221,19 @@ API::
 Discard the internal object and destroy the writer instance.
 
 
-Optimize small integers
-=======================
+Optimize import for small integers
+==================================
 
-Proposed API are efficient for large integers. Compared to accessing
-directly Python internals, the proposed API can have a significant
-performance overhead on small integers.
+Proposed import API is efficient for large integers. Compared to
+accessing directly Python internals, the proposed import API can have a
+significant performance overhead on small integers.
 
 For small integers of a few digits (for example, 1 or 2 digits), existing APIs
-can be used
+can be used:
 
-* :external+py3.14:c:func:`PyLong_FromUInt64()` / :external+py3.14:c:func:`PyLong_AsUInt64()`;
-* :c:func:`PyLong_FromLong()` / :c:func:`PyLong_AsLong()` or :c:func:`PyLong_AsInt()`;
-* :external+py3.13:c:func:`PyUnstable_Long_IsCompact()` and
-  :external+py3.13:c:func:`PyUnstable_Long_CompactValue()`;
-* :c:func:`PyLong_FromNativeBytes()` / :c:func:`PyLong_AsNativeBytes()`;
+* :external+py3.14:c:func:`PyLong_FromUInt64()`;
+* :c:func:`PyLong_FromLong()`;
+* :c:func:`PyLong_FromNativeBytes()`.
 
 
 Implementation
@@ -262,7 +266,7 @@ Code::
         PyLong_Export(obj, &long_export);
         if (long_export.digits) {
             mpz_import(z, long_export.ndigits, layout->digits_order,
-                       layout->digit_size, layout->endian,
+                       layout->digit_size, layout->endianness,
                        layout->digit_size*8 - layout->bits_per_digit,
                        long_export.digits);
             if (long_export.negative) {
@@ -307,15 +311,15 @@ mode:
 +----------------+---------+-----------------------+
 | Benchmark      | ref     | pep757                |
 +================+=========+=======================+
-| 1<<7           | 94.3 ns | 96.8 ns: 1.03x slower |
+| 1<<7           | 91.3 ns | 89.9 ns: 1.02x faster |
 +----------------+---------+-----------------------+
-| 1<<38          | 127 ns  | 99.7 ns: 1.28x faster |
+| 1<<38          | 120 ns  | 94.9 ns: 1.27x faster |
 +----------------+---------+-----------------------+
-| 1<<300         | 209 ns  | 222 ns: 1.06x slower  |
+| 1<<300         | 196 ns  | 203 ns: 1.04x slower  |
 +----------------+---------+-----------------------+
-| 1<<3000        | 955 ns  | 963 ns: 1.01x slower  |
+| 1<<3000        | 939 ns  | 945 ns: 1.01x slower  |
 +----------------+---------+-----------------------+
-| Geometric mean | (ref)   | 1.04x faster          |
+| Geometric mean | (ref)   | 1.05x faster          |
 +----------------+---------+-----------------------+
 
 
@@ -341,7 +345,7 @@ Code::
             return NULL;
         }
 
-        mpz_export(digits, NULL, layout->endian,
+        mpz_export(digits, NULL, layout->endianness,
                    layout->digit_size, layout->digits_order,
                    layout->digit_size*8 - layout->bits_per_digit,
                    obj->z);
@@ -365,17 +369,17 @@ Benchmark:
 Results on Linux Fedora 40 with CPU isolation, Python built in release
 mode:
 
-+----------------+--------+----------------------+
-| Benchmark      | ref    | pep757               |
-+================+========+======================+
-| 1<<300         | 193 ns | 215 ns: 1.11x slower |
-+----------------+--------+----------------------+
-| 1<<3000        | 927 ns | 943 ns: 1.02x slower |
-+----------------+--------+----------------------+
-| Geometric mean | (ref)  | 1.03x slower         |
-+----------------+--------+----------------------+
++----------------+---------+-----------------------+
+| Benchmark      | ref     | pep757                |
++================+=========+=======================+
+| 1<<7           | 56.7 ns | 56.2 ns: 1.01x faster |
++----------------+---------+-----------------------+
+| 1<<300         | 191 ns  | 213 ns: 1.12x slower  |
++----------------+---------+-----------------------+
+| Geometric mean | (ref)   | 1.03x slower          |
++----------------+---------+-----------------------+
 
-Benchmark hidden because not significant (2): 1<<7, 1<<38.
+Benchmark hidden because not significant (2): 1<<38, 1<<3000.
 
 
 Backwards Compatibility
@@ -388,7 +392,7 @@ added.
 Open Questions
 ==============
 
-* Should we add *digits_order* and *endian* members to :data:`sys.int_info`
+* Should we add *digits_order* and *endianness* members to :data:`sys.int_info`
   and remove ``PyLong_GetNativeLayout()``? The
   ``PyLong_GetNativeLayout()`` function returns a C structure
   which is more convenient to use in C than :data:`sys.int_info` which uses