Merge branch 'main' into sqlite-begin

Author: Erlend E. Aasland

.gitattributes

@@ -57,6 +57,7 @@ Doc/library/token-list.inc  linguist-generated=true
 Include/token.h             linguist-generated=true
 Lib/token.py                linguist-generated=true
 Parser/token.c              linguist-generated=true
+Programs/test_frozenmain.h  linguist-generated=true
 
 # Language aware diff headers
 # https://tekin.co.uk/2020/10/better-git-diff-output-for-ruby-python-elixir-and-more

.github/SECURITY.md

@@ -10,9 +10,8 @@ https://devguide.python.org/#status-of-python-branches
 ## Reporting a Vulnerability
 
 Please read the guidelines on reporting security issues [on the
-official website](
-https://www.python.org/news/security/#reporting-security-issues-in-python
-) for instructions on how to report a security-related problem to
+official website](https://www.python.org/dev/security/) for
+instructions on how to report a security-related problem to
 the Python team responsibly.
 
 To reach the response team, email `security at python dot org`. 

.github/workflows/build.yml

@@ -6,16 +6,18 @@ name: Tests
 on:
   push:
     branches:
-    - main
-    - 3.9
-    - 3.8
-    - 3.7
+    - 'main'
+    - '3.10'
+    - '3.9'
+    - '3.8'
+    - '3.7'
   pull_request:
     branches:
-    - main
-    - 3.9
-    - 3.8
-    - 3.7
+    - 'main'
+    - '3.10'
+    - '3.9'
+    - '3.8'
+    - '3.7'
 
 jobs:
   check_source:
@@ -148,7 +150,7 @@ jobs:
         echo "LD_LIBRARY_PATH=${GITHUB_WORKSPACE}/multissl/openssl/${OPENSSL_VER}/lib" >> $GITHUB_ENV
     - name: 'Restore OpenSSL build'
       id: cache-openssl
-      uses: actions/[email protected].5
+      uses: actions/[email protected].6
       with:
         path: ./multissl/openssl/${{ env.OPENSSL_VER }}
         key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}
@@ -177,7 +179,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        openssl_ver: [1.1.1k, 3.0.0-alpha16]
+        openssl_ver: [1.1.1k, 3.0.0-alpha17]
     env:
       OPENSSL_VER: ${{ matrix.openssl_ver }}
       MULTISSL_DIR: ${{ github.workspace }}/multissl
@@ -196,7 +198,7 @@ jobs:
         echo "LD_LIBRARY_PATH=${GITHUB_WORKSPACE}/multissl/openssl/${OPENSSL_VER}/lib" >> $GITHUB_ENV
     - name: 'Restore OpenSSL build'
       id: cache-openssl
-      uses: actions/[email protected].5
+      uses: actions/[email protected].6
       with:
         path: ./multissl/openssl/${{ env.OPENSSL_VER }}
         key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}

.github/workflows/build_msi.yml

@@ -3,18 +3,20 @@ name: TestsMSI
 on:
   push:
     branches:
-    - main
-    - 3.9
-    - 3.8
-    - 3.7
+    - 'main'
+    - '3.10'
+    - '3.9'
+    - '3.8'
+    - '3.7'
     paths:
     - 'Tools/msi/**'
   pull_request:
     branches:
-    - main
-    - 3.9
-    - 3.8
-    - 3.7
+    - 'main'
+    - '3.10'
+    - '3.9'
+    - '3.8'
+    - '3.7'
     paths:
     - 'Tools/msi/**'
 

.github/workflows/doc.yml

@@ -3,18 +3,20 @@ name: Docs
 on:
   #push:
   #  branches:
-  #  - main
-  #  - 3.9
-  #  - 3.8
-  #  - 3.7
+  #  - 'main'
+  #  - '3.10'
+  #  - '3.9'
+  #  - '3.8'
+  #  - '3.7'
   #  paths:
   #  - 'Doc/**'
   pull_request:
     branches:
-    - main
-    - 3.9
-    - 3.8
-    - 3.7
+    - 'main'
+    - '3.10'
+    - '3.9'
+    - '3.8'
+    - '3.7'
     paths:
     - 'Doc/**'
     - 'Misc/**'

Doc/about.rst

@@ -23,9 +23,8 @@ Many thanks go to:
   and writer of much of the content;
 * the `Docutils <http://docutils.sourceforge.net/>`_ project for creating
   reStructuredText and the Docutils suite;
-* Fredrik Lundh for his `Alternative Python Reference
-  <http://effbot.org/zone/pyref.htm>`_ project from which Sphinx got many good
-  ideas.
+* Fredrik Lundh for his Alternative Python Reference project from which Sphinx
+  got many good ideas.
 
 
 Contributors to the Python Documentation

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/gcsupport.rst

@@ -33,6 +33,18 @@ Constructors for container types must conform to two rules:
 #. Once all the fields which may contain references to other containers are
    initialized, it must call :c:func:`PyObject_GC_Track`.
 
+   .. warning::
+      If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement at least
+      a :c:member:`~PyTypeObject.tp_traverse` handler or explicitly use one
+      from its subclass or subclasses.
+
+      When calling :c:func:`PyType_Ready` or some of the APIs that indirectly
+      call it like :c:func:`PyType_FromSpecWithBases` or
+      :c:func:`PyType_FromSpec` the interpreter will automatically populate the
+      :c:member:`~PyTypeObject.tp_flags`, :c:member:`~PyTypeObject.tp_traverse`
+      and :c:member:`~PyTypeObject.tp_clear` fields if the type inherits from a
+      class that implements the garbage collector protocol and the child class
+      does *not* include the :const:`Py_TPFLAGS_HAVE_GC` flag.
 
 .. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
 

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)