PEP 757: address review, sync with PR and prettify (#3975)

Author: skirpichev

peps/conf.py

@@ -52,6 +52,17 @@
 # Warn on missing references
 nitpicky = True
 
+nitpick_ignore = [
+    # Standard C types
+    ("c:type", "int8_t"),
+    ("c:type", "uint8_t"),
+    ("c:type", "int64_t"),
+]
+for role, name in list(nitpick_ignore):
+    if role in ("c:type", "c:struct"):
+        nitpick_ignore.append(("c:identifier", name))
+del role, name
+
 # Intersphinx configuration
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),

peps/pep-0757.rst

@@ -17,7 +17,7 @@ Abstract
 ========
 
 Add a new C API to import and export Python integers, :class:`int` objects:
-especially ``PyLongWriter_Create()`` and ``PyLong_Export()`` functions.
+especially :c:func:`PyLongWriter_Create()` and :c:func:`PyLong_Export()` functions.
 
 
 Rationale
@@ -26,12 +26,12 @@ Rationale
 Projects such as `gmpy2 <https://github.com/aleaxit/gmpy>`_, `SAGE
 <https://www.sagemath.org/>`_ and `Python-FLINT
 <https://github.com/flintlib/python-flint>`_ access directly Python
-"internals" (the ``PyLongObject`` structure) or use an inefficient
+"internals" (the :c:type:`PyLongObject` structure) or use an inefficient
 temporary format (hex strings for Python-FLINT) to import and
 export Python :class:`int` objects.  The Python :class:`int` implementation
 changed in Python 3.12 to add a tag and "compact values".
 
-In the 3.13 alpha 1 release, the private undocumented ``_PyLong_New()``
+In the 3.13 alpha 1 release, the private undocumented :c:func:`!_PyLong_New()`
 function had been removed, but it is being used by these projects to
 import Python integers. The private function has been restored in 3.13
 alpha 2.
@@ -49,38 +49,46 @@ Specification
 Layout API
 ----------
 
-API::
+Data needed by `GMP <https://gmplib.org/>`_-like import-export functions.
 
-    typedef struct PyLongLayout {
-        // Bits per digit
-        uint8_t bits_per_digit;
+.. c:struct:: PyLongLayout
 
-        // Digit size in bytes
-        uint8_t digit_size;
+   Layout of an array of digits, used by Python :class:`int` object.
 
-        // Digits order:
-        // * 1 for most significant digit first
-        // * -1 for least significant digit first
-        int8_t digits_order;
+   Use :c:func:`PyLong_GetNativeLayout` to get the native layout of Python
+   :class:`int` objects.
 
-        // Endianness:
-        // * 1 for most significant byte first (big endian)
-        // * -1 for least significant byte first (little endian)
-        int8_t endianness;
-    } PyLongLayout;
+   See also :data:`sys.int_info` which exposes similar information to Python.
 
-    PyAPI_FUNC(const PyLongLayout*) PyLong_GetNativeLayout(void);
+   .. c:member:: uint8_t bits_per_digit
 
-Data needed by `GMP <https://gmplib.org/>`_-like import-export functions.
+      Bits per digit.
+
+   .. c:member:: uint8_t digit_size
+
+      Digit size in bytes.
+
+   .. c:member:: int8_t digits_order
+
+      Digits order:
+
+      - ``1`` for most significant digit first
+      - ``-1`` for least significant digit first
 
-PyLong_GetNativeLayout()
-^^^^^^^^^^^^^^^^^^^^^^^^
+   .. c:member:: int8_t endian
 
-API::
+      Digit endianness:
 
-    const PyLongLayout* PyLong_GetNativeLayout(void)
+      - ``1`` for most significant byte first (big endian)
+      - ``-1`` for least significant first (little endian)
+
+
+.. c:function:: const PyLongLayout* PyLong_GetNativeLayout(void)
+
+   Get the native layout of Python :class:`int` objects.
+
+   See the :c:struct:`PyLongLayout` structure.
 
-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
@@ -91,134 +99,112 @@ so it can be cached.
 Export API
 ----------
 
-Export a Python integer as a digits array::
+.. c:struct:: PyLongExport
 
-    typedef struct PyLongExport {
-        // use value, if digits set to NULL.
-        int64_t value;
+   Export of a Python :class:`int` object.
 
-        // 1 if the number is negative, 0 otherwise.
-        uint8_t negative;
+   There are two cases:
 
-        // Number of digits in the 'digits' array.
-        Py_ssize_t ndigits;
+   * If :c:member:`digits` is ``NULL``, only use the :c:member:`value` member.
+     Calling :c:func:`PyLong_FreeExport` is optional in this case.
+   * If :c:member:`digits` is not ``NULL``, use :c:member:`negative`,
+     :c:member:`ndigits` and :c:member:`digits` members.
+     Calling :c:func:`PyLong_FreeExport` is mandatory in this case.
 
-        // Read-only array of unsigned digits.
-        const void *digits;
+   .. c:member:: int64_t value
 
-        // Member used internally, must not be used for other purpose.
-        Py_uintptr_t _reserved;
-    } PyLongExport;
+      The native integer value of the exported :class:`int` object.
+      Only valid if :c:member:`digits` is ``NULL``.
 
-    int PyLong_Export(PyObject *obj, PyLongExport *array);
-    void PyLong_FreeExport(PyLongExport *array);
+   .. c:member:: uint8_t negative
 
-On CPython 3.14, no memory copy is needed, it's just a thin wrapper to
-expose Python int internal digits array.
+      1 if the number is negative, 0 otherwise.
+      Only valid if :c:member:`digits` is not ``NULL``.
 
-``PyLongExport._reserved``, if ``digits`` not ``NULL``, stores a strong
-reference to the Python :class:`int` object to make sure that that structure
-remains valid until ``PyLong_FreeExport()`` is called.
+   .. c:member:: Py_ssize_t ndigits
 
+      Number of digits in :c:member:`digits` array.
+      Only valid if :c:member:`digits` is not ``NULL``.
 
-PyLong_Export()
-^^^^^^^^^^^^^^^
+   .. c:member:: const void *digits
 
-API::
+      Read-only array of unsigned digits. Can be ``NULL``.
 
-    int PyLong_Export(PyObject *obj, PyLongExport *array)
 
-Export a Python :class:`int` object as a digits array.
+.. c:function:: int PyLong_Export(PyObject *obj, PyLongExport *export_long)
 
-On success, set *\*array* and return 0.
-On error, set an exception and return -1.
+   Export a Python :class:`int` object.
 
-If ``array->digits`` set to ``NULL``, caller must use instead ``array->value``
-to get value of an :class:`int` object.
+   On success, set *\*export_long* and return 0.
+   On error, set an exception and return -1.
 
-CPython implementation detail: This function always succeeds if *obj* is a
-Python :class:`int` object or a subclass.
+   This function always succeeds if *obj* is a Python :class:`int` object or a
+   subclass.
 
-``PyLong_FreeExport()`` must be called once done with using *array*.
+   If *export_long.digits* is not ``NULL``, :c:func:`PyLong_FreeExport` must be
+   called when the export is no longer needed.
 
+On CPython 3.14, no memory copy is needed, it's just a thin wrapper to
+expose Python int internal digits array.
 
-PyLong_FreeExport()
-^^^^^^^^^^^^^^^^^^^
+A private field of the :c:struct:`PyLongExport`, if
+:c:member:`~PyLongExport.digits` not ``NULL``, stores a strong reference to the
+Python :class:`int` object to make sure that that structure remains valid until
+:c:func:`PyLong_FreeExport()` is called.
 
-API::
 
-    void PyLong_FreeExport(PyLongExport *array)
+.. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
 
-Free the export *array* created by ``PyLong_Export()``.
+   Release the export *export_long* created by :c:func:`PyLong_Export`.
 
 
 Import API
 ----------
 
-Import a Python integer from a digits array::
-
-    // A Python integer writer instance.
-    // The instance must be destroyed by PyLongWriter_Finish().
-    typedef struct PyLongWriter PyLongWriter;
-
-    PyAPI_FUNC(PyLongWriter*) PyLongWriter_Create(
-        int negative,
-        Py_ssize_t ndigits,
-        void **digits);
-    PyAPI_FUNC(PyObject*) PyLongWriter_Finish(PyLongWriter *writer);
-    PyAPI_FUNC(void) PyLongWriter_Discard(PyLongWriter *writer);
+The :c:type:`PyLongWriter` API can be used to import an integer.
 
-On CPython 3.14, the implementation is a thin wrapper to the private
-``_PyLong_New()`` function.
-
-``PyLongWriter_Finish()`` takes care of normalizing the digits and
-converts the object to a compact integer if needed.
+.. c:struct:: PyLongWriter
 
+   A Python :class:`int` writer instance.
 
-PyLongWriter_Create()
-^^^^^^^^^^^^^^^^^^^^^
+   The instance must be destroyed by :c:func:`PyLongWriter_Finish`.
 
-API::
 
-    PyLongWriter* PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)
+.. c:function:: PyLongWriter* PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)
 
-Create a ``PyLongWriter``.
+   Create a :c:type:`PyLongWriter`.
 
-On success, set *\*digits* and return a writer.
-On error, set an exception and return ``NULL``.
+   On success, set *\*digits* and return a writer.
+   On error, set an exception and return ``NULL``.
 
-*negative* is ``1`` if the number is negative, or ``0`` otherwise.
+   *negative* is ``1`` if the number is negative, or ``0`` otherwise.
 
-*ndigits* is the number of digits in the *digits* array. It must be
-greater than or equal to 0.
+   *ndigits* is the number of digits in the *digits* array. It must be
+   greater than or equal to 0.
 
-The caller must initialize the digits array *digits* and then call
-``PyLongWriter_Finish()`` to get a Python :class:`int`. Digits must be
-in the range [``0``; ``PyLong_BASE - 1``]. Unused digits must be set to
-``0``.
+   The caller must initialize the array of digits *digits* and then call
+   :c:func:`PyLongWriter_Finish` to get a Python :class:`int`. Digits must be
+   in the range [``0``; ``PyLong_BASE - 1``]. Unused digits must be set to
+   ``0``.
 
+On CPython 3.14, the implementation is a thin wrapper to the private
+:c:func:`!_PyLong_New()` function.
 
-PyLongWriter_Finish()
-^^^^^^^^^^^^^^^^^^^^^
-
-API::
-
-    PyObject* PyLongWriter_Finish(PyLongWriter *writer)
 
-Finish a ``PyLongWriter`` created by ``PyLongWriter_Create()``.
+.. c:function:: PyObject* PyLongWriter_Finish(PyLongWriter *writer)
 
-On success, return a Python :class:`int` object.
-On error, set an exception and return ``NULL``.
+   Finish a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`.
 
+   On success, return a Python :class:`int` object.
+   On error, set an exception and return ``NULL``.
 
-PyLongWriter_Discard()
-^^^^^^^^^^^^^^^^^^^^^^
+:c:func:`PyLongWriter_Finish()` takes care of normalizing the digits and
+converts the object to a compact integer if needed.
 
-API::
 
-    void PyLongWriter_Discard(PyLongWriter *writer)
+.. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
 
-Discard the internal object and destroy the writer instance.
+   Discard the internal object and destroy the writer instance.
 
 
 Optimize import for small integers
@@ -252,8 +238,8 @@ Implementation
 Benchmarks
 ==========
 
-Export: PyLong_Export() with gmpy2
-----------------------------------
+Export: :c:func:`PyLong_Export()` with gmpy2
+--------------------------------------------
 
 Code::
 
@@ -284,14 +270,17 @@ Code::
                 if (long_export.value < 0) {
                     mpz_t tmp;
                     mpz_init(tmp);
-                    mpz_ui_pow_ui(tmp, 2, 8*sizeof(size_t));
+                    mpz_ui_pow_ui(tmp, 2, 64);
                     mpz_sub(z, z, tmp);
                     mpz_clear(tmp);
                 }
             }
         }
     }
 
+Reference code: `mpz_set_PyLong() in the gmpy2 master for commit 9177648
+<https://github.com/aleaxit/gmpy/blob/9177648c23f5c507e46b81c1eb7d527c79c96f00/src/gmpy2_convert_gmp.c#L42-L69>`_.
+
 Benchmark:
 
 .. code-block:: py
@@ -323,8 +312,8 @@ mode:
 +----------------+---------+-----------------------+
 
 
-Import: PyLongWriter_Create() with gmpy2
-----------------------------------------
+Import: :c:func:`PyLongWriter_Create()` with gmpy2
+--------------------------------------------------
 
 Code::
 
@@ -353,6 +342,9 @@ Code::
         return PyLongWriter_Finish(writer);
     }
 
+Reference code: `GMPy_PyLong_From_MPZ() in the gmpy2 master for commit 9177648
+<https://github.com/aleaxit/gmpy/blob/9177648c23f5c507e46b81c1eb7d527c79c96f00/src/gmpy2_convert_gmp.c#L128-L156>`_.
+
 Benchmark:
 
 .. code-block:: py
@@ -393,16 +385,16 @@ Open Questions
 ==============
 
 * 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
+  and remove :c:func:`PyLong_GetNativeLayout()`?  The
+  :c:func:`PyLong_GetNativeLayout()` function returns a C structure
   which is more convenient to use in C than :data:`sys.int_info` which uses
   Python objects.
 * Currenly, all required information for :class:`int` import/export is
   already available via :c:func:`PyLong_GetInfo()` or :data:`sys.int_info`.
   Native endianness of "digits" and current order of digits (least
   significant digit first) --- is a common denominator of all libraries
   for aribitrary precision integer arithmetic.  So, shouldn't we just remove
-  from API both ``PyLongLayout`` and ``PyLong_GetNativeLayout()`` (which
+  from API both :c:struct:`PyLongLayout` and :c:func:`PyLong_GetNativeLayout()` (which
   is actually just a minor convenience)?
 
 
@@ -416,8 +408,8 @@ It would be convenient to support arbitrary layout to import-export
 Python integers.
 
 For example, it was proposed to add a *layout* parameter to
-``PyLongWriter_Create()`` and a *layout* member to the
-``PyLongExport`` structure.
+:c:func:`PyLongWriter_Create()` and a *layout* member to the
+:c:struct:`PyLongExport` structure.
 
 The problem is that it's more complex to implement and not really
 needed. What's strictly needed is only an API to import-export using the