Address Petr's review

python · vstinner · Dec 13, 2024 · Jul 2, 2024 · Jul 23, 2024 · Sep 3, 2024
commit 92007d1c2c0d58b4cefcda6c39a180a6c564c64e
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
@@ -703,8 +703,8 @@ Export API
 
    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.
+   finalized. The layout is the same for all Python sub-interpreters
+   in a process, and so it can be cached.
 
 
 .. c:struct:: PyLongExport
@@ -714,10 +714,8 @@ Export API
    There are two cases:
 
    * 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.
 
    .. c:member:: int64_t value
 
@@ -743,20 +741,28 @@ Export API
 
    Export a Python :class:`int` object.
 
-   *export_long* must not be ``NULL``.
+   *export_long* must point to a :c:struct:`PyLongExport` structure allocated
+   by the caller. It must not be ``NULL``.
 
-   On success, set *\*export_long* and return ``0``.
+   On success, fill in *\*export_long* and return ``0``.
    On error, set an exception and return ``-1``.
 
-   If *export_long->digits* is not ``NULL``, :c:func:`PyLong_FreeExport` must
-   be called when the export is no longer needed. Otherwise, calling
-   :c:func:`PyLong_FreeExport` is optional.
+   :c:func:`PyLong_FreeExport` must be called when the export is no longer
+   needed.
+
+    .. impl-detail::
+        This function always succeeds if *obj* is a Python :class:`int` object
+        or a subclass.
 
-
+
+    .. impl-detail::
+
+        This function always succeeds if *obj* is a Python :class:`int` object
+        or a subclass.
+
-
+
+    .. impl-detail::
+
+        This function always succeeds if *obj* is a Python :class:`int` object
+        or a subclass.
+
 
 .. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
 
    Release the export *export_long* created by :c:func:`PyLong_Export`.
 
+   .. impl-detail::
+      Calling :c:func:`PyLong_FreeExport` is optional if *export_long->digits*
+      is ``NULL``.
+
 
 PyLongWriter API
 ^^^^^^^^^^^^^^^^
@@ -787,12 +793,18 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
 
    *digits* must not be NULL.
 
-   The caller can either initialize the array of digits *digits* and then
-   either call :c:func:`PyLongWriter_Finish` to get a Python :class:`int` or
-   :c:func:`PyLongWriter_Discard` to destroy the writer instance.  Digits must
-   be in the range [``0``; ``(1 << bits_per_digit) - 1``]  (where the
-   :c:struct:`~PyLongLayout.bits_per_digit` is the number of bits per digit).
-   The unused most significant digits must be set to ``0``.
+   After a successful call to this function, the caller should fill in the
+   array of digits *digits* and then call :c:func:`PyLongWriter_Finish` to get
+   a Python :class:`int`.
+   The layout of *digits* is described by :c:func:`PyLong_GetNativeLayout`.
+
+   Digits must be in the range [``0``; ``(1 << bits_per_digit) - 1``]
+   (where the :c:struct:`~PyLongLayout.bits_per_digit` is the number of bits
+   per digit).
+   Any unused most significant digits must be set to ``0``.
+
+   Alternately, call :c:func:`PyLongWriter_Discard` to destroy the writer
+   instance without creating an :class:`~int` object.
 
 
 .. c:function:: PyObject* PyLongWriter_Finish(PyLongWriter *writer)
@@ -805,7 +817,7 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
    The function takes care of normalizing the digits and converts the object
    to a compact integer if needed.
 
-   The writer instance is invalid after the call.
+   The writer instance and the *digits* array are invalid after the call.
 
 
 .. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
@@ -814,4 +826,4 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
 
    *writer* must not be ``NULL``.
 
-   The writer instance is invalid after the call.
+   The writer instance and the *digits* array are invalid after the call.
diff --git a/Doc/conf.py b/Doc/conf.py
@@ -158,7 +158,6 @@
     ('c:type', 'size_t'),
     ('c:type', 'ssize_t'),
     ('c:type', 'time_t'),
-    ('c:type', 'int8_t'),
     ('c:type', 'uint8_t'),
     ('c:type', 'uint16_t'),
  
9E88
   ('c:type', 'uint32_t'),

diff --git a/Modules/_testcapi/long.c b/Modules/_testcapi/long.c
@@ -164,8 +164,9 @@ pylong_export(PyObject *module, PyObject *obj)
         assert(export_long.negative == 0);
         assert(export_long.ndigits == 0);
         assert(export_long.digits == NULL);
-        return PyLong_FromInt64(export_long.value);
-        // PyLong_FreeExport() is not needed in this case
+        PyObject *res = PyLong_FromInt64(export_long.value);
+        PyLong_FreeExport(&export_long);
+        return res;
     }
 
     assert(PyLong_GetNativeLayout()->digit_size == sizeof(digit));

diff --git a/Objects/longobject.c b/Objects/longobject.c
@@ -6797,6 +6797,7 @@ int
 PyLong_Export(PyObject *obj, PyLongExport *export_long)
 {
     if (!PyLong_Check(obj)) {
+        memset(export_long, 0, sizeof(*export_long));
         PyErr_Format(PyExc_TypeError, "expect int, got %T", obj);
         return -1;
     }