Merge branch 'main' into pythongh-104090-fix-leaked-semaphors-on-test_concurrent_futures-v2

Author: bityob

Diff for: .github/CODEOWNERS

@@ -177,3 +177,4 @@ Doc/c-api/stable.rst          @encukou
 # Argument Clinic
 /Tools/clinic/**              @erlend-aasland @AlexWaygood
 /Lib/test/test_clinic.py      @erlend-aasland @AlexWaygood
+Doc/howto/clinic.rst          @erlend-aasland

Diff for: Doc/c-api/module.rst

@@ -486,12 +486,29 @@ state:
    .. versionadded:: 3.10
 
 
+.. c:function:: int PyModule_Add(PyObject *module, const char *name, PyObject *value)
+
+   Similar to :c:func:`PyModule_AddObjectRef`, but "steals" a reference
+   to *value*.
+   It can be called with a result of function that returns a new reference
+   without bothering to check its result or even saving it to a variable.
+
+   Example usage::
+
+        if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
+            goto error;
+        }
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
 
    Similar to :c:func:`PyModule_AddObjectRef`, but steals a reference to
    *value* on success (if it returns ``0``).
 
-   The new :c:func:`PyModule_AddObjectRef` function is recommended, since it is
+   The new :c:func:`PyModule_Add` or :c:func:`PyModule_AddObjectRef`
+   functions are recommended, since it is
    easy to introduce reference leaks by misusing the
    :c:func:`PyModule_AddObject` function.
 
@@ -501,44 +518,24 @@ state:
       only decrements the reference count of *value* **on success**.
 
       This means that its return value must be checked, and calling code must
-      :c:func:`Py_DECREF` *value* manually on error.
+      :c:func:`Py_XDECREF` *value* manually on error.
 
    Example usage::
 
-      static int
-      add_spam(PyObject *module, int value)
-      {
-          PyObject *obj = PyLong_FromLong(value);
-          if (obj == NULL) {
-              return -1;
-          }
-          if (PyModule_AddObject(module, "spam", obj) < 0) {
-              Py_DECREF(obj);
-              return -1;
-          }
-          // PyModule_AddObject() stole a reference to obj:
-          // Py_DECREF(obj) is not needed here
-          return 0;
-      }
-
-   The example can also be written without checking explicitly if *obj* is
-   ``NULL``::
+        PyObject *obj = PyBytes_FromString(value);
+        if (PyModule_AddObject(module, "spam", obj) < 0) {
+            // If 'obj' is not NULL and PyModule_AddObject() failed,
+            // 'obj' strong reference must be deleted with Py_XDECREF().
+            // If 'obj' is NULL, Py_XDECREF() does nothing.
+            Py_XDECREF(obj);
+            goto error;
+        }
+        // PyModule_AddObject() stole a reference to obj:
+        // Py_XDECREF(obj) is not needed here.
 
-      static int
-      add_spam(PyObject *module, int value)
-      {
-          PyObject *obj = PyLong_FromLong(value);
-          if (PyModule_AddObject(module, "spam", obj) < 0) {
-              Py_XDECREF(obj);
-              return -1;
-          }
-          // PyModule_AddObject() stole a reference to obj:
-          // Py_DECREF(obj) is not needed here
-          return 0;
-      }
+   .. deprecated:: 3.13
 
-   Note that ``Py_XDECREF()`` should be used instead of ``Py_DECREF()`` in
-   this case, since *obj* can be ``NULL``.
+      :c:func:`PyModule_AddObject` is :term:`soft deprecated`.
 
 
 .. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

Diff for: Doc/data/stable_abi.dat

@@ -560,15 +560,12 @@ Let's dive in!
     Congratulations, you've ported your first function to work with Argument Clinic!
 
 
-Advanced topics
-===============
+How-to guides
+=============
 
-Now that you've had some experience working with Argument Clinic, it's time
-for some advanced topics.
 
-
-Symbolic default values
------------------------
+How to use symbolic default values
+----------------------------------
 
 The default value you provide for a parameter can't be any arbitrary
 expression.  Currently the following are explicitly supported:
@@ -583,8 +580,8 @@ expression.  Currently the following are explicitly supported:
 to allow full expressions like ``CONSTANT - 1``.)
 
 
-Renaming the C functions and variables generated by Argument Clinic
--------------------------------------------------------------------
+How to to rename C functions and variables generated by Argument Clinic
+-----------------------------------------------------------------------
 
 Argument Clinic automatically names the functions it generates for you.
 Occasionally this may cause a problem, if the generated name collides with
@@ -626,8 +623,8 @@ array) would be ``file``, but the C variable would be named ``file_obj``.
 You can use this to rename the ``self`` parameter too!
 
 
-Converting functions using PyArg_UnpackTuple
---------------------------------------------
+How to convert functions using ``PyArg_UnpackTuple``
+----------------------------------------------------
 
 To convert a function parsing its arguments with :c:func:`PyArg_UnpackTuple`,
 simply write out all the arguments, specifying each as an ``object``.  You
@@ -639,8 +636,8 @@ Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this
 will change soon.
 
 
-Optional groups
----------------
+How to use optional groups
+--------------------------
 
 Some legacy functions have a tricky approach to parsing their arguments:
 they count the number of positional arguments, then use a ``switch`` statement
@@ -732,8 +729,8 @@ Notes:
   use optional groups for new code.
 
 
-Using real Argument Clinic converters, instead of "legacy converters"
----------------------------------------------------------------------
+How to use real Argument Clinic converters, instead of "legacy converters"
+--------------------------------------------------------------------------
 
 To save time, and to minimize how much you need to learn
 to achieve your first port to Argument Clinic, the walkthrough above tells
@@ -903,17 +900,17 @@ it accepts, along with the default value for each parameter.
 Just run ``Tools/clinic/clinic.py --converters`` to see the full list.
 
 
-Py_buffer
----------
+How to use the ``Py_buffer`` converter
+--------------------------------------
 
 When using the ``Py_buffer`` converter
 (or the ``'s*'``, ``'w*'``, ``'*y'``, or ``'z*'`` legacy converters),
 you *must* not call :c:func:`PyBuffer_Release` on the provided buffer.
 Argument Clinic generates code that does it for you (in the parsing function).
 
 
-Advanced converters
--------------------
+How to use advanced converters
+------------------------------
 
 Remember those format units you skipped for your first
 time because they were advanced?  Here's how to handle those too.
@@ -944,8 +941,8 @@ hard-coded encoding strings for parameters whose format units start with ``e``.
 
 .. _default_values:
 
-Parameter default values
-------------------------
+How to assign default values to parameter
+-----------------------------------------
 
 Default values for parameters can be any of a number of values.
 At their simplest, they can be string, int, or float literals:
@@ -968,8 +965,8 @@ There's also special support for a default value of ``NULL``, and
 for simple expressions, documented in the following sections.
 
 
-The ``NULL`` default value
---------------------------
+How to use the ``NULL`` default value
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For string and object parameters, you can set them to ``None`` to indicate
 that there's no default.  However, that means the C variable will be
@@ -979,8 +976,8 @@ behaves like a default value of ``None``, but the C variable is initialized
 with ``NULL``.
 
 
-Expressions specified as default values
----------------------------------------
+How to use expressions as default values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The default value for a parameter can be more than just a literal value.
 It can be an entire expression, using math operators and looking up attributes
@@ -1036,8 +1033,8 @@ you're not permitted to use:
 * Tuple/list/set/dict literals.
 
 
-Using a return converter
-------------------------
+How to use return converters
+----------------------------
 
 By default, the impl function Argument Clinic generates for you returns
 :c:type:`PyObject * <PyObject>`.
@@ -1106,8 +1103,8 @@ their parameters (if any),
 just run ``Tools/clinic/clinic.py --converters`` for the full list.
 
 
-Cloning existing functions
---------------------------
+How to clone existing functions
+-------------------------------
 
 If you have a number of functions that look similar, you may be able to
 use Clinic's "clone" feature.  When you clone an existing function,
@@ -1150,8 +1147,8 @@ Also, the function you are cloning from must have been previously defined
 in the current file.
 
 
-Calling Python code
--------------------
+How to call Python code
+-----------------------
 
 The rest of the advanced topics require you to write Python code
 which lives inside your C file and modifies Argument Clinic's
@@ -1178,8 +1175,8 @@ variable to the C code::
     /*[python checksum:...]*/
 
 
-Using a "self converter"
-------------------------
+How to use the "self converter"
+-------------------------------
 
 Argument Clinic automatically adds a "self" parameter for you
 using a default converter.  It automatically sets the ``type``
@@ -1230,8 +1227,8 @@ type for ``self``, it's best to create your own converter, subclassing
     [clinic start generated code]*/
 
 
-Using a "defining class" converter
-----------------------------------
+How to use the "defining class" converter
+-----------------------------------------
 
 Argument Clinic facilitates gaining access to the defining class of a method.
 This is useful for :ref:`heap type <heap-types>` methods that need to fetch
@@ -1293,8 +1290,8 @@ state.  Example from the ``setattro`` slot method in
 See also :pep:`573`.
 
 
-Writing a custom converter
---------------------------
+How to write a custom converter
+-------------------------------
 
 As we hinted at in the previous section... you can write your own converters!
 A converter is simply a Python class that inherits from ``CConverter``.
@@ -1385,8 +1382,8 @@ You can see more examples of custom converters in the CPython
 source tree; grep the C files for the string ``CConverter``.
 
 
-Writing a custom return converter
----------------------------------
+How to write a custom return converter
+--------------------------------------
 
 Writing a custom return converter is much like writing
 a custom converter.  Except it's somewhat simpler, because return
@@ -1400,8 +1397,8 @@ specifically the implementation of ``CReturnConverter`` and
 all its subclasses.
 
 
-METH_O and METH_NOARGS
-----------------------
+How to convert ``METH_O`` and ``METH_NOARGS`` functions
+-------------------------------------------------------
 
 To convert a function using ``METH_O``, make sure the function's
 single argument is using the ``object`` converter, and mark the
@@ -1422,8 +1419,8 @@ You can still use a self converter, a return converter, and specify
 a ``type`` argument to the object converter for ``METH_O``.
 
 
-tp_new and tp_init functions
-----------------------------
+How to convert ``tp_new`` and ``tp_init`` functions
+---------------------------------------------------
 
 You can convert ``tp_new`` and ``tp_init`` functions.  Just name
 them ``__new__`` or ``__init__`` as appropriate.  Notes:
@@ -1445,8 +1442,8 @@ them ``__new__`` or ``__init__`` as appropriate.  Notes:
   generated will throw an exception if it receives any.)
 
 
-Changing and redirecting Clinic's output
-----------------------------------------
+How to change and redirect Clinic's output
+------------------------------------------
 
 It can be inconvenient to have Clinic's output interspersed with
 your conventional hand-edited C code.  Luckily, Clinic is configurable:
@@ -1728,8 +1725,8 @@ it in a Clinic block lets Clinic use its existing checksum functionality to ensu
 the file was not modified by hand before it gets overwritten.
 
 
-The #ifdef trick
-----------------
+How to use the ``#ifdef`` trick
+-------------------------------
 
 If you're converting a function that isn't available on all platforms,
 there's a trick you can use to make life a little easier.  The existing
@@ -1809,8 +1806,8 @@ Argument Clinic added to your file (it'll be at the very bottom), then
 move it above the ``PyMethodDef`` structure where that macro is used.
 
 
-Using Argument Clinic in Python files
--------------------------------------
+How to use Argument Clinic in Python files
+------------------------------------------
 
 It's actually possible to use Argument Clinic to preprocess Python files.
 There's no point to using Argument Clinic blocks, of course, as the output

Diff for: Doc/howto/clinic.rst

@@ -774,6 +774,11 @@ New Features
   If the assertion fails, make sure that the size is set before.
   (Contributed by Victor Stinner in :gh:`106168`.)
 
+* Add :c:func:`PyModule_Add` function: similar to
+  :c:func:`PyModule_AddObjectRef` and :c:func:`PyModule_AddObject` but
+  always steals a reference to the value.
+  (Contributed by Serhiy Storchaka in :gh:`86493`.)
+
 Porting to Python 3.13
 ----------------------