Merge branch 'main' into meta/crypto/c/hashlib/34/openssl-peek-error-159815

Author: picnixz

Doc/c-api/interp-lifecycle.rst

@@ -265,6 +265,48 @@ Initializing and finalizing the interpreter
    first initialized).
 
 
+.. c:function:: int Py_FrozenMain(int argc, char **argv)
+
+   .. index:: single: freeze utility
+
+   The main program for a "frozen" Python program (an executable that embeds
+   the interpreter together with the bytecode of the program's modules, as
+   produced by the :program:`freeze` utility; see :source:`Tools/freeze`).
+
+   This function initializes the interpreter, imports the frozen module named
+   ``__main__``, and finalizes the interpreter.
+   The frozen modules must have been registered in
+   :c:var:`PyImport_FrozenModules` before calling this function;
+   it is a fatal error if ``__main__`` is not among them.
+
+   *argc* and *argv* are byte strings like the arguments of a C program's
+   ``main`` function, and are passed to the interpreter with
+   :c:func:`PyConfig_SetBytesArgv`.
+   Unlike :c:func:`Py_Main`, the arguments are not parsed as Python command
+   line options (:c:member:`PyConfig.parse_argv` is ``0``), so all of them
+   are made available to the program in :data:`sys.argv`.
+   Apart from that, the interpreter uses the
+   :ref:`Python Configuration <init-python-config>`, so environment variables
+   such as :envvar:`PYTHONPATH` are honored.
+   Warnings about the path configuration
+   (:c:member:`PyConfig.pathconfig_warnings`) are suppressed.
+   If :envvar:`PYTHONINSPECT` is set and standard input is a terminal, an
+   interactive prompt is run after ``__main__`` has finished, as with the
+   :option:`-i` option.
+
+   Return ``0`` if ``__main__`` ran without an unhandled exception, ``1``
+   otherwise, and ``120`` if finalizing the interpreter failed (see
+   :c:func:`Py_FinalizeEx`).
+   An unhandled :exc:`SystemExit` terminates the process.
+   If the interpreter cannot be initialized, the process exits via
+   :c:func:`Py_ExitStatusException`.
+
+   On Windows, this function is not exported by the Python DLL.
+   The :program:`freeze` utility compiles :file:`Python/frozenmain.c` into the
+   frozen program instead, together with the Windows-specific hooks that the
+   function requires.
+
+
 .. c:function:: int Py_RunMain(void)
 
    Executes the main module in a fully configured CPython runtime.

Doc/c-api/structures.rst

@@ -760,11 +760,20 @@ The following flags can be used with :c:member:`PyMemberDef.flags`:
 .. versionchanged:: 3.12
 
    The :c:macro:`!READONLY` macro was renamed to :c:macro:`Py_READONLY`.
-   The :c:macro:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix.
+   The :c:macro:`PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix.
    The new names are now always available.
    Previously, these required ``#include "structmember.h"``.
    The header is still available and it provides the old names.
 
+.. c:macro:: PY_AUDIT_READ
+
+   Soft-deprecated alias of :c:macro:`Py_AUDIT_READ` (note capitalization of
+   the ``y``).
+   Only available with  ``#include "structmember.h"``.
+
+   .. soft-deprecated:: 3.12
+      Use :c:macro:`Py_AUDIT_READ` instead.
+
 .. _PyMemberDef-types:
 
 Member types

Doc/library/ctypes.rst

@@ -1107,6 +1107,17 @@ In addition, if a function argument is explicitly declared to be a pointer type
 type (``c_int`` in this case) can be passed to the function.  ctypes will apply
 the required :func:`byref` conversion in this case automatically.
 
+These conversions are also applied to the :attr:`!_as_parameter_` attribute of
+an object passed for a pointer argument (see
+:ref:`ctypes-calling-functions-with-own-custom-data-types`). So, for a
+``POINTER(c_int)`` argument, an object whose :attr:`!_as_parameter_` is a
+``c_int`` instance is passed by reference, and one whose :attr:`!_as_parameter_`
+is a ``c_int`` array is accepted as well.
+
+.. versionchanged:: next
+   Objects with an :attr:`!_as_parameter_` attribute now receive the same
+   implicit conversions for pointer arguments as the object they wrap.
+
 To set a POINTER type field to ``NULL``, you can assign ``None``::
 
    >>> bar.values = None

Doc/library/pathlib-parts.svg

@@ -307,6 +307,21 @@ Methods and properties
 
    from pathlib import PurePath, PurePosixPath, PureWindowsPath
 
+The :attr:`~PurePath.parent`, :attr:`~PurePath.name`,
+:attr:`~PurePath.stem`, and :attr:`~PurePath.suffix` properties describe
+different parts of a path.  For example, given::
+
+   >>> p = PurePosixPath('/srv/holy/grail.tar.gz')
+
+.. image:: pathlib-parts.svg
+   :align: center
+   :class: invert-in-dark-mode
+   :alt: For p = PurePosixPath('/srv/holy/grail.tar.gz'), p.parent is
+         PurePosixPath('/srv/holy'), p.name is 'grail.tar.gz',
+         p.stem is 'grail.tar', and p.suffix is '.gz'.
+
+The stem excludes only the final suffix: in this example, it includes ``.tar``.
+
 Pure paths provide the following methods and properties:
 
 .. attribute:: PurePath.parser

Doc/library/pathlib.rst

@@ -2432,6 +2432,26 @@ always available. Unless explicitly noted otherwise, all variables are read-only
    .. versionadded:: 3.2
 
 
+.. data:: EXIT_SUCCESS
+
+    An int you can use to indicate your program ended gracefully.
+
+    .. code-block:: python
+
+        sys.exit(sys.EXIT_SUCCESS)
+
+    .. versionadded:: 3.16
+
+.. data:: EXIT_FAILURE
+
+    An int you can use to indicate your program encountered an error.
+
+    .. code-block:: python
+
+        sys.exit(sys.EXIT_FAILURE)
+
+    .. versionadded:: 3.16
+
 .. rubric:: Citations
 
 .. [C99] ISO/IEC 9899:1999.  "Programming languages -- C."  A public draft of this standard is available at https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf\ .

Doc/library/sys.rst

@@ -227,8 +227,13 @@ than needed.
    .. versionchanged:: 3.9
       Added support for ``|`` and ``|=`` operators, as specified in :pep:`584`.
 
-:class:`WeakValueDictionary` objects have an additional method that has the
-same issues as the :meth:`WeakKeyDictionary.keyrefs` method.
+:class:`WeakValueDictionary` objects have the following additional methods.
+These have the same issues as the :meth:`WeakKeyDictionary.keyrefs` method.
+
+
+.. method:: WeakValueDictionary.itervaluerefs()
+
+   Return an :term:`iterator` that yields the weak references to the values.
 
 
 .. method:: WeakValueDictionary.valuerefs()