Merge remote-tracking branch 'upstream/main' into fix-issue-25872

Author: uniocto

.github/workflows/build.yml

@@ -177,7 +177,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        openssl_ver: [1.1.1k, 3.0.0-alpha15]
+        openssl_ver: [1.1.1k, 3.0.0-alpha16]
     env:
       OPENSSL_VER: ${{ matrix.openssl_ver }}
       MULTISSL_DIR: ${{ github.workspace }}/multissl

Doc/c-api/apiabiversion.rst

@@ -6,34 +6,57 @@
 API and ABI Versioning
 ***********************
 
-``PY_VERSION_HEX`` is the Python version number encoded in a single integer.
-
-For example if the ``PY_VERSION_HEX`` is set to ``0x030401a2``, the underlying
-version information can be found by treating it as a 32 bit number in
-the following manner:
-
-   +-------+-------------------------+------------------------------------------------+
-   | Bytes | Bits (big endian order) | Meaning                                        |
-   +=======+=========================+================================================+
-   | ``1`` |       ``1-8``           |  ``PY_MAJOR_VERSION`` (the ``3`` in            |
-   |       |                         |  ``3.4.1a2``)                                  |
-   +-------+-------------------------+------------------------------------------------+
-   | ``2`` |       ``9-16``          |  ``PY_MINOR_VERSION`` (the ``4`` in            |
-   |       |                         |  ``3.4.1a2``)                                  |
-   +-------+-------------------------+------------------------------------------------+
-   | ``3`` |       ``17-24``         |  ``PY_MICRO_VERSION`` (the ``1`` in            |
-   |       |                         |  ``3.4.1a2``)                                  |
-   +-------+-------------------------+------------------------------------------------+
-   | ``4`` |       ``25-28``         |  ``PY_RELEASE_LEVEL`` (``0xA`` for alpha,      |
-   |       |                         |  ``0xB`` for beta, ``0xC`` for release         |
-   |       |                         |  candidate and ``0xF`` for final), in this     |
-   |       |                         |  case it is alpha.                             |
-   +-------+-------------------------+------------------------------------------------+
-   |       |       ``29-32``         |  ``PY_RELEASE_SERIAL`` (the ``2`` in           |
-   |       |                         |  ``3.4.1a2``, zero for final releases)         |
-   +-------+-------------------------+------------------------------------------------+
-
-Thus ``3.4.1a2`` is hexversion ``0x030401a2``.
+CPython exposes its version number in the following macros.
+Note that these correspond to the version code is **built** with,
+not necessarily the version used at **run time**.
 
-All the given macros are defined in :source:`Include/patchlevel.h`.
+See :ref:`stable` for a discussion of API and ABI stability across versions.
+
+.. c:macro:: PY_MAJOR_VERSION
+
+   The ``3`` in ``3.4.1a2``.
+
+.. c:macro:: PY_MINOR_VERSION
+
+   The ``4`` in ``3.4.1a2``.
+
+.. c:macro:: PY_MICRO_VERSION
+
+   The ``1`` in ``3.4.1a2``.
+
+.. c:macro:: PY_RELEASE_LEVEL
+
+   The ``a`` in ``3.4.1a2``.
+   This can be ``0xA`` for alpha, ``0xB`` for beta, ``0xC`` for release
+   candidate or ``0xF`` for final.
 
+.. c:macro:: PY_RELEASE_SERIAL
+
+   The ``2`` in ``3.4.1a2``. Zero for final releases.
+
+.. c:macro:: PY_VERSION_HEX
+
+   The Python version number encoded in a single integer.
+
+   The underlying version information can be found by treating it as a 32 bit
+   number in the following manner:
+
+   +-------+-------------------------+-------------------------+--------------------------+
+   | Bytes | Bits (big endian order) | Meaning                 | Value for ``3.4.1a2``    |
+   +=======+=========================+=========================+==========================+
+   |   1   |         1-8             |  ``PY_MAJOR_VERSION``   | ``0x03``                 |
+   +-------+-------------------------+-------------------------+--------------------------+
+   |   2   |         9-16            |  ``PY_MINOR_VERSION``   | ``0x04``                 |
+   +-------+-------------------------+-------------------------+--------------------------+
+   |   3   |         17-24           |  ``PY_MICRO_VERSION``   | ``0x01``                 |
+   +-------+-------------------------+-------------------------+--------------------------+
+   |   4   |         25-28           |  ``PY_RELEASE_LEVEL``   | ``0xA``                  |
+   +       +-------------------------+-------------------------+--------------------------+
+   |       |         29-32           |  ``PY_RELEASE_SERIAL``  | ``0x2``                  |
+   +-------+-------------------------+-------------------------+--------------------------+
+
+   Thus ``3.4.1a2`` is hexversion ``0x030401a2`` and ``3.10.0`` is
+   hexversion ``0x030a00f0``.
+
+
+All the given macros are defined in :source:`Include/patchlevel.h`.

Doc/c-api/exceptions.rst

@@ -675,27 +675,6 @@ The following functions are used to create and modify Unicode exceptions from C.
    *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
    UTF-8 encoded strings.
 
-.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
-
-   Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
-   *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
-   UTF-8 encoded strings.
-
-   .. deprecated:: 3.3 3.11
-
-      ``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
-      ``PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...)``.
-
-.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
-
-   Create a :class:`UnicodeTranslateError` object with the attributes *object*,
-   *length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string.
-
-   .. deprecated:: 3.3 3.11
-
-      ``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
-      ``PyObject_CallFunction(PyExc_UnicodeTranslateError, "Onns", ...)``.
-
 .. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
                 PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
 

Doc/c-api/init.rst

@@ -323,6 +323,11 @@ Process-wide parameters
       single: main()
       triple: stdin; stdout; sdterr
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.stdio_encoding` and :c:member:`PyConfig.stdio_errors`
+   should be used instead, see :ref:`Python Initialization Configuration
+   <init-config>`.
+
    This function should be called before :c:func:`Py_Initialize`, if it is
    called at all. It specifies which encoding and error handling to use
    with standard IO, with the same meanings as in :func:`str.encode`.
@@ -345,6 +350,8 @@ Process-wide parameters
 
    .. versionadded:: 3.4
 
+   .. deprecated:: 3.11
+
 
 .. c:function:: void Py_SetProgramName(const wchar_t *name)
 
@@ -353,6 +360,10 @@ Process-wide parameters
       single: main()
       single: Py_GetPath()
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.program_name` should be used instead, see :ref:`Python
+   Initialization Configuration <init-config>`.
+
    This function should be called before :c:func:`Py_Initialize` is called for
    the first time, if it is called at all.  It tells the interpreter the value
    of the ``argv[0]`` argument to the :c:func:`main` function of the program
@@ -367,6 +378,8 @@ Process-wide parameters
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:type:`wchar_*` string.
 
+   .. deprecated:: 3.11
+
 
 .. c:function:: wchar* Py_GetProgramName()
 
@@ -495,6 +508,11 @@ Process-wide parameters
       single: path (in module sys)
       single: Py_GetPath()
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.module_search_paths` and
+   :c:member:`PyConfig.module_search_paths_set` should be used instead, see
+   :ref:`Python Initialization Configuration <init-config>`.
+
    Set the default module search path.  If this function is called before
    :c:func:`Py_Initialize`, then :c:func:`Py_GetPath` won't attempt to compute a
    default search path but uses the one provided instead.  This is useful if
@@ -518,6 +536,8 @@ Process-wide parameters
       The program full path is now used for :data:`sys.executable`, instead
       of the program name.
 
+   .. deprecated:: 3.11
+
 
 .. c:function:: const char* Py_GetVersion()
 
@@ -617,6 +637,9 @@ Process-wide parameters
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:type:`wchar_*` string.
 
+   See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
+   members of the :ref:`Python Initialization Configuration <init-config>`.
+
    .. note::
       It is recommended that applications embedding the Python interpreter
       for purposes other than executing a single script pass ``0`` as *updatepath*,
@@ -644,11 +667,18 @@ Process-wide parameters
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:type:`wchar_*` string.
 
+   See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
+   members of the :ref:`Python Initialization Configuration <init-config>`.
+
    .. versionchanged:: 3.4 The *updatepath* value depends on :option:`-I`.
 
 
 .. c:function:: void Py_SetPythonHome(const wchar_t *home)
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.home` should be used instead, see :ref:`Python
+   Initialization Configuration <init-config>`.
+
    Set the default "home" directory, that is, the location of the standard
    Python libraries.  See :envvar:`PYTHONHOME` for the meaning of the
    argument string.
@@ -661,6 +691,8 @@ Process-wide parameters
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:type:`wchar_*` string.
 
+   .. deprecated:: 3.11
+
 
 .. c:function:: w_char* Py_GetPythonHome()
 

Doc/c-api/memory.rst

@@ -476,6 +476,8 @@ Customize Memory Allocators
    the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the
    debug hooks on top on the new allocator.
 
+   See also :c:member:`PyPreConfig.allocator` and :ref:`Preinitialize Python
+   with PyPreConfig <c-preinit>`.
 
 .. c:function:: void PyMem_SetupDebugHooks(void)