Merge remote-tracking branch 'upstream/main' into deferred_gc

Author: Fidget-Spinner

Doc/c-api/dict.rst

@@ -156,7 +156,7 @@ Dictionary Objects
 
 .. c:function:: int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)
 
-   Similar than :c:func:`PyDict_GetItemRef`, but *key* is specified as a
+   Similar to :c:func:`PyDict_GetItemRef`, but *key* is specified as a
    :c:expr:`const char*` UTF-8 encoded bytes string, rather than a
    :c:expr:`PyObject*`.
 
@@ -206,7 +206,7 @@ Dictionary Objects
      ``NULL``, and return ``0``.
    - On error, raise an exception and return ``-1``.
 
-   This is similar to :meth:`dict.pop`, but without the default value and
+   Similar to :meth:`dict.pop`, but without the default value and
    not raising :exc:`KeyError` if the key missing.
 
    .. versionadded:: 3.13

Doc/c-api/typeobj.rst

@@ -1592,7 +1592,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    weak references to the type object itself.
 
    It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
-   :c:member:`~PyTypeObject.tp_weaklist`.
+   :c:member:`~PyTypeObject.tp_weaklistoffset`.
 
    **Inheritance:**
 
@@ -1604,7 +1604,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    **Default:**
 
    If the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit is set in the
-   :c:member:`~PyTypeObject.tp_dict` field, then
+   :c:member:`~PyTypeObject.tp_flags` field, then
    :c:member:`~PyTypeObject.tp_weaklistoffset` will be set to a negative value,
    to indicate that it is unsafe to use this field.
 

Doc/howto/logging.rst

@@ -385,6 +385,46 @@ following diagram.
 .. raw:: html
    :file: logging_flow.svg
 
+.. raw:: html
+
+   <script>
+   /*
+    * This snippet is needed to handle the case where a light or dark theme is
+    * chosen via the theme is selected in the page. We call the existing handler
+    * and then add a dark-theme class to the body when the dark theme is selected.
+    * The SVG styling (above) then does the rest.
+    *
+    * If the pydoc theme is updated to set the dark-theme class, this snippet
+    * won't be needed any more.
+    */
+   (function() {
+     var oldActivateTheme = activateTheme;
+
+     function updateBody(theme) {
+        let elem = document.body;
+
+        elem.classList.remove('dark-theme');
+        elem.classList.remove('light-theme');
+        if (theme === 'dark') {
+            elem.classList.add('dark-theme');
+        }
+        else if (theme === 'light') {
+            elem.classList.add('light-theme');
+        }
+     }
+
+     activateTheme = function(theme) {
+        oldActivateTheme(theme);
+        updateBody(theme);
+     };
+     /*
+      * If the page is refreshed, make sure we update the body - the overriding
+      * of activateTheme won't have taken effect yet.
+      */
+      updateBody(localStorage.getItem('currentTheme') || 'auto');
+   })();
+   </script>
+
 Loggers
 ^^^^^^^
 

Doc/howto/logging_flow.svg

@@ -266,6 +266,20 @@ Fundamental data types
 (1)
    The constructor accepts any object with a truth value.
 
+Additionally, if IEC 60559 compatible complex arithmetic (Annex G) is supported, the following
+complex types are available:
+
++----------------------------------+---------------------------------+-----------------+
+| ctypes type                      | C type                          | Python type     |
++==================================+=================================+=================+
+| :class:`c_float_complex`         | :c:expr:`float complex`         | complex         |
++----------------------------------+---------------------------------+-----------------+
+| :class:`c_double_complex`        | :c:expr:`double complex`        | complex         |
++----------------------------------+---------------------------------+-----------------+
+| :class:`c_longdouble_complex`    | :c:expr:`long double complex`   | complex         |
++----------------------------------+---------------------------------+-----------------+
+
+
 All these types can be created by calling them with an optional initializer of
 the correct type and value::
 
@@ -2284,6 +2298,30 @@ These are the fundamental ctypes data types:
    optional float initializer.
 
 
+.. class:: c_double_complex
+
+   Represents the C :c:expr:`double complex` datatype, if available.  The
+   constructor accepts an optional :class:`complex` initializer.
+
+   .. versionadded:: 3.14
+
+
+.. class:: c_float_complex
+
+   Represents the C :c:expr:`float complex` datatype, if available.  The
+   constructor accepts an optional :class:`complex` initializer.
+
+   .. versionadded:: 3.14
+
+
+.. class:: c_longdouble_complex
+
+   Represents the C :c:expr:`long double complex` datatype, if available.  The
+   constructor accepts an optional :class:`complex` initializer.
+
+   .. versionadded:: 3.14
+
+
 .. class:: c_int
 
    Represents the C :c:expr:`signed int` datatype.  The constructor accepts an

Doc/library/ctypes.rst

@@ -1724,10 +1724,27 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
       Added support for pipes on Windows.
 
 
-.. function:: splice(src, dst, count, offset_src=None, offset_dst=None)
+.. function:: splice(src, dst, count, offset_src=None, offset_dst=None, flags=0)
 
    Transfer *count* bytes from file descriptor *src*, starting from offset
    *offset_src*, to file descriptor *dst*, starting from offset *offset_dst*.
+
+   The splicing behaviour can be modified by specifying a *flags* value.
+   Any of the following variables may used, combined using bitwise OR
+   (the ``|`` operator):
+
+   * If :const:`SPLICE_F_MOVE` is specified,
+     the kernel is asked to move pages instead of copying,
+     but pages may still be copied if the kernel cannot move the pages from the pipe.
+
+   * If :const:`SPLICE_F_NONBLOCK` is specified,
+     the kernel is asked to not block on I/O.
+     This makes the splice pipe operations nonblocking,
+     but splice may nevertheless block because the spliced file descriptors may block.
+
+   * If :const:`SPLICE_F_MORE` is specified,
+     it hints to the kernel that more data will be coming in a subsequent splice.
+
    At least one of the file descriptors must refer to a pipe. If *offset_src*
    is ``None``, then *src* is read from the current position; respectively for
    *offset_dst*. The offset associated to the file descriptor that refers to a
@@ -1746,6 +1763,8 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    make sense to block because there are no writers connected to the write end
    of the pipe.
 
+   .. seealso:: The :manpage:`splice(2)` man page.
+
    .. availability:: Linux >= 2.6.17 with glibc >= 2.5
 
    .. versionadded:: 3.10
@@ -4642,6 +4661,10 @@ written in Python, such as a mail server's external command delivery program.
       Use :class:`subprocess.Popen` or :func:`subprocess.run` to
       control options like encodings.
 
+   .. deprecated:: 3.14
+      The function is :term:`soft deprecated` and should no longer be used to
+      write new code. The :mod:`subprocess` module is recommended instead.
+
 
 .. function:: posix_spawn(path, argv, env, *, file_actions=None, \
                           setpgroup=None, resetids=False, setsid=False, setsigmask=(), \
@@ -4868,6 +4891,10 @@ written in Python, such as a mail server's external command delivery program.
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
+   .. deprecated:: 3.14
+      These functions are :term:`soft deprecated` and should no longer be used
+      to write new code. The :mod:`subprocess` module is recommended instead.
+
 
 .. data:: P_NOWAIT
           P_NOWAITO
@@ -4972,7 +4999,7 @@ written in Python, such as a mail server's external command delivery program.
    shell documentation.
 
    The :mod:`subprocess` module provides more powerful facilities for spawning
-   new processes and retrieving their results; using that module is preferable
+   new processes and retrieving their results; using that module is recommended
    to using this function.  See the :ref:`subprocess-replacements` section in
    the :mod:`subprocess` documentation for some helpful recipes.