Merge branch 'master' into revert-23107-revert-13893-fix-issue-37193

Call _PyType_Fini() in subinterpreters.

Fix reference leaks in subinterpreters.

.azure-pipelines/ci.yml

@@ -104,7 +104,7 @@ jobs:
     matrix:
       win32:
         arch: win32
-        buildOpt:
+        buildOpt: '-p Win32'
         testRunTitle: '$(Build.SourceBranchName)-win32'
         testRunPlatform: win32
       win64:

.azure-pipelines/docs-steps.yml

@@ -12,11 +12,11 @@ steps:
   inputs:
     versionSpec: '>=3.6'
 
-- script: python -m pip install sphinx==2.2.0 blurb python-docs-theme
+- script: python -m pip install sphinx==3.2.1 blurb python-docs-theme
   displayName: 'Install build dependencies'
 
 - ${{ if ne(parameters.latex, 'true') }}:
-  - script: make check suspicious html PYTHON=python
+  - script: make check html PYTHON=python
     workingDirectory: '$(build.sourcesDirectory)/Doc'
     displayName: 'Build documentation'
 
@@ -31,7 +31,7 @@ steps:
 - ${{ if eq(parameters.upload, 'true') }}:
   - task: PublishBuildArtifacts@1
     displayName: 'Publish docs'
-  
+
     inputs:
       PathToPublish: '$(build.sourcesDirectory)/Doc/build'
       ArtifactName: docs

.azure-pipelines/pr.yml

@@ -104,7 +104,7 @@ jobs:
     matrix:
       win32:
         arch: win32
-        buildOpt:
+        buildOpt: '-p Win32'
         testRunTitle: '$(System.PullRequest.TargetBranch)-win32'
         testRunPlatform: win32
       win64:

.azure-pipelines/windows-release/stage-pack-msix.yml

@@ -120,10 +120,11 @@ jobs:
       artifactName: unsigned_msix
       downloadPath: $(Build.BinariesDirectory)
 
+  # MSIX must be signed and timestamped simultaneously
   - powershell: |
       $failed = $true
       foreach ($retry in 1..3) {
-          signtool sign /a /n "$(SigningCertificate)" /fd sha256 /t http://timestamp.verisign.com/scripts/timestamp.dll /d "$(SigningDescription)" (gi *.msix)
+          signtool sign /a /n "$(SigningCertificate)" /fd sha256 /tr http://timestamp.digicert.com/ /td sha256 /d "$(SigningDescription)" (gi *.msix)
           if ($?) {
               $failed = $false
               break

.azure-pipelines/windows-release/stage-pack-nuget.yml

@@ -4,7 +4,7 @@ jobs:
   condition: and(succeeded(), eq(variables['DoNuget'], 'true'))
 
   pool:
-    vmImage: windows-2019
+    name: 'Windows Release'
 
   workspace:
     clean: all
@@ -36,6 +36,14 @@ jobs:
       nuget pack "$(Build.BinariesDirectory)\layout\python.nuspec" -OutputDirectory $(Build.ArtifactStagingDirectory) -NoPackageAnalysis -NonInteractive
     displayName: 'Create nuget package'
 
+  - powershell: |
+      gci *.nupkg | %{
+        nuget sign "$_" -CertificateSubjectName "$(SigningCertificate)" -Timestamper http://timestamp.digicert.com/ -Overwrite
+      }
+    displayName: 'Sign nuget package'
+    workingDirectory: $(Build.ArtifactStagingDirectory)
+    condition: and(succeeded(), variables['SigningCertificate'])
+
   - task: PublishBuildArtifacts@1
     displayName: 'Publish Artifact: nuget'
     inputs:

.azure-pipelines/windows-release/stage-sign.yml

@@ -57,7 +57,7 @@ jobs:
       $files = (gi ${{ parameters.Include }} -Exclude ${{ parameters.Exclude }})
       $failed = $true
       foreach ($retry in 1..10) {
-          signtool timestamp /t http://timestamp.verisign.com/scripts/timestamp.dll $files
+          signtool timestamp /tr http://timestamp.digicert.com/ /td sha256 $files
           if ($?) {
               $failed = $false
               break

.github/CODEOWNERS

@@ -19,6 +19,7 @@ Objects/frameobject.c         @markshannon
 Objects/call.c                @markshannon
 Python/ceval.c                @markshannon
 Python/compile.c              @markshannon
+Python/ast_opt.c              @isidentical
 
 # Hashing
 **/*hashlib*                  @python/crypto-team @tiran
@@ -84,6 +85,12 @@ Include/pytime.h              @pganssle @abalkin
 /Lib/test/test_peg_generator/ @pablogsal @lysnikolaou
 /Grammar/python.gram          @pablogsal @lysnikolaou
 
+# AST
+Python/ast.c                  @isidentical
+Parser/asdl.py                @isidentical
+Parser/asdl_c.py              @isidentical
+Lib/ast.py                    @isidentical
+
 # SQLite 3
 **/*sqlite*                   @berkerpeksag
 

.github/dependabot.yml

@@ -7,3 +7,7 @@ updates:
     labels:
       - "skip issue"
       - "skip news"
+    target_branch:
+      - "master"
+      - "3.9"
+      - "3.8"

.github/workflows/build.yml

@@ -47,6 +47,37 @@ jobs:
             # https://github.com/python/core-workflow/issues/373
             git diff --name-only origin/$GITHUB_BASE_REF.. | grep -qvE '(\.rst$|^Doc|^Misc)' && echo '::set-output name=run_tests::true' || true
           fi
+
+  check_generated_files:
+    name: 'Check if generated files are up to date'
+    runs-on: ubuntu-latest
+    needs: check_source
+    if: needs.check_source.outputs.run_tests == 'true'
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+      - name: Install Dependencies
+        run: sudo ./.github/workflows/posix-deps-apt.sh
+      - name: Build CPython
+        run: |
+          # Build Python with the libpython dynamic library
+          ./configure --with-pydebug --enable-shared
+          make -j4 regen-all
+      - name: Check for changes
+        run: |
+          changes=$(git status --porcelain)
+          # Check for changes in regenerated files
+          if ! test -z "$changes"
+          then
+            echo "Generated files not up to date. Perhaps you forgot to run make regen-all ;)"
+            echo "$changes"
+            exit 1
+          fi
+      - name: Check exported libpython symbols
+        run: make smelly
+      - name: Check limited ABI symbols
+        run: make check-limited-abi
+
   build_win32:
     name: 'Windows (x86)'
     runs-on: windows-latest
@@ -59,7 +90,7 @@ jobs:
     - name: Display build info
       run: .\python.bat -m test.pythoninfo
     - name: Tests
-      run: .\PCbuild\rt.bat -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
+      run: .\PCbuild\rt.bat -p Win32 -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
 
   build_win_amd64:
     name: 'Windows (x64)'
@@ -73,7 +104,7 @@ jobs:
     - name: Display build info
       run: .\python.bat -m test.pythoninfo
     - name: Tests
-      run: .\PCbuild\rt.bat -x64 -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
+      run: .\PCbuild\rt.bat -p x64 -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
 
   build_macos:
     name: 'macOS'
@@ -106,7 +137,7 @@ jobs:
       run: sudo ./.github/workflows/posix-deps-apt.sh
     - name: 'Restore OpenSSL build'
       id: cache-openssl
-      uses: actions/cache@v2.1.2
+      uses: actions/cache@v2.1.3
       with:
         path: ./multissl/openssl/${{ env.OPENSSL_VER }}
         key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}

.github/workflows/coverage.yml

@@ -32,7 +32,7 @@ jobs:
       run: sudo ./.github/workflows/posix-deps-apt.sh
     - name: 'Restore OpenSSL build'
       id: cache-openssl
-      uses: actions/cache@v2.1.2
+      uses: actions/cache@v2.1.3
       with:
         path: ./multissl/openssl/${{ env.OPENSSL_VER }}
         key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}

.github/workflows/doc.yml

@@ -36,9 +36,9 @@ jobs:
     - name: 'Install build dependencies'
       run: make -C Doc/ PYTHON=../python venv
     - name: 'Build documentation'
-      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going -j4" doctest suspicious html
+      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going -j4" doctest html
     - name: 'Upload'
-      uses: actions/upload-artifact@v2.2.0
+      uses: actions/upload-artifact@v2.2.1
       with:
         name: doc-html
         path: Doc/build/html

.github/workflows/stale.yml

@@ -0,0 +1,19 @@
+name: Mark stale pull requests
+
+on:
+  schedule:
+  - cron: "0 0 * * *"
+
+jobs:
+  stale:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/stale@v3
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        stale-pr-message: 'This PR is stale because it has been open for 30 days with no activity.'
+        stale-pr-label: 'stale'
+        days-before-stale: 30
+        days-before-close: -1

.travis.yml

@@ -53,7 +53,7 @@ matrix:
         - cd Doc
         - make venv PYTHON=python
       script:
-        - make check suspicious html SPHINXOPTS="-q -W -j4"
+        - make check html SPHINXOPTS="-q -W -j4"
     - name: "Documentation tests"
       os: linux
       language: c
@@ -192,6 +192,8 @@ script:
   - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then ./python Tools/scripts/patchcheck.py --travis $TRAVIS_PULL_REQUEST; fi
   # Check that all symbols exported by libpython start with "Py" or "_Py"
   - make smelly
+  # Check that all symbols in the limited abi are present
+  - make check-limited-abi
   # `-r -w` implicitly provided through `make buildbottest`.
   - |
     if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then

Doc/Makefile

@@ -202,6 +202,7 @@ dist:
 
 check:
 	$(PYTHON) tools/rstlint.py -i tools -i $(VENVDIR) -i README.rst
+	$(PYTHON) tools/rstlint.py ../Misc/NEWS.d/next/
 
 serve:
 	$(PYTHON) ../Tools/scripts/serve.py build/html
@@ -215,12 +216,11 @@ serve:
 
 # for development releases: always build
 autobuild-dev:
-	make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switchers=1'
-	-make suspicious
+	make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
 
 # for quick rebuilds (HTML only)
 autobuild-dev-html:
-	make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switchers=1'
+	make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
 
 # for stable releases: only build if not in pre-release stage (alpha, beta)
 # release candidate downloads are okay, since the stable tree can be in that stage

Doc/c-api/arg.rst

@@ -482,7 +482,8 @@ API Functions
    *min* and no more than *max*; *min* and *max* may be equal.  Additional
    arguments must be passed to the function, each of which should be a pointer to a
    :c:type:`PyObject*` variable; these will be filled in with the values from
-   *args*; they will contain borrowed references.  The variables which correspond
+   *args*; they will contain :term:`borrowed references <borrowed reference>`.
+   The variables which correspond
    to optional parameters not given by *args* will not be filled in; these should
    be initialized by the caller. This function returns true on success and false if
    *args* is not a tuple or contains the wrong number of elements; an exception

Doc/c-api/init.rst

@@ -376,6 +376,12 @@ Process-wide parameters
    The returned string points into static storage; the caller should not modify its
    value.
 
+   This function should not be called before :c:func:`Py_Initialize`, otherwise
+   it returns ``NULL``.
+
+   .. versionchanged:: 3.10
+      It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
 
 .. c:function:: wchar_t* Py_GetPrefix()
 
@@ -389,6 +395,12 @@ Process-wide parameters
    script at build time.  The value is available to Python code as ``sys.prefix``.
    It is only useful on Unix.  See also the next function.
 
+   This function should not be called before :c:func:`Py_Initialize`, otherwise
+   it returns ``NULL``.
+
+   .. versionchanged:: 3.10
+      It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
 
 .. c:function:: wchar_t* Py_GetExecPrefix()
 
@@ -424,6 +436,12 @@ Process-wide parameters
    while having :file:`/usr/local/plat` be a different filesystem for each
    platform.
 
+   This function should not be called before :c:func:`Py_Initialize`, otherwise
+   it returns ``NULL``.
+
+   .. versionchanged:: 3.10
+      It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
 
 .. c:function:: wchar_t* Py_GetProgramFullPath()
 
@@ -437,6 +455,12 @@ Process-wide parameters
    static storage; the caller should not modify its value.  The value is available
    to Python code as ``sys.executable``.
 
+   This function should not be called before :c:func:`Py_Initialize`, otherwise
+   it returns ``NULL``.
+
+   .. versionchanged:: 3.10
+      It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
 
 .. c:function:: wchar_t* Py_GetPath()
 
@@ -455,8 +479,14 @@ Process-wide parameters
    can be (and usually is) modified later to change the search path for loading
    modules.
 
+   This function should not be called before :c:func:`Py_Initialize`, otherwise
+   it returns ``NULL``.
+
    .. XXX should give the exact rules
 
+   .. versionchanged:: 3.10
+      It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
 
 .. c:function::  void Py_SetPath(const wchar_t *)
 
@@ -638,6 +668,12 @@ Process-wide parameters
    :c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`
    environment variable if it is set.
 
+   This function should not be called before :c:func:`Py_Initialize`, otherwise
+   it returns ``NULL``.
+
+   .. versionchanged:: 3.10
+      It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
 
 .. _threads:
 
@@ -1077,7 +1113,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
 
    Get the current frame of the Python thread state *tstate*.
 
-   Return a strong reference. Return ``NULL`` if no frame is currently
+   Return a :term:`strong reference`. Return ``NULL`` if no frame is currently
    executing.
 
    See also :c:func:`PyEval_GetFrame`.

Doc/c-api/init_config.rst

@@ -8,46 +8,24 @@ Python Initialization Configuration
 
 .. versionadded:: 3.8
 
-Structures:
+Python can be initialized with :c:func:`Py_InitializeFromConfig` and the
+:c:type:`PyConfig` structure. It can be preinitialized with
+:c:func:`Py_PreInitialize` and the :c:type:`PyPreConfig` structure.
 
-* :c:type:`PyConfig`
-* :c:type:`PyPreConfig`
-* :c:type:`PyStatus`
-* :c:type:`PyWideStringList`
+There are two kinds of configuration:
 
-Functions:
+* The :ref:`Python Configuration <init-python-config>` can be used to build a
+  customized Python which behaves as the regular Python. For example,
+  environments variables and command line arguments are used to configure
+  Python.
 
-* :c:func:`PyConfig_Clear`
-* :c:func:`PyConfig_InitIsolatedConfig`
-* :c:func:`PyConfig_InitPythonConfig`
-* :c:func:`PyConfig_Read`
-* :c:func:`PyConfig_SetArgv`
-* :c:func:`PyConfig_SetBytesArgv`
-* :c:func:`PyConfig_SetBytesString`
-* :c:func:`PyConfig_SetString`
-* :c:func:`PyConfig_SetWideStringList`
-* :c:func:`PyPreConfig_InitIsolatedConfig`
-* :c:func:`PyPreConfig_InitPythonConfig`
-* :c:func:`PyStatus_Error`
-* :c:func:`PyStatus_Exception`
-* :c:func:`PyStatus_Exit`
-* :c:func:`PyStatus_IsError`
-* :c:func:`PyStatus_IsExit`
-* :c:func:`PyStatus_NoMemory`
-* :c:func:`PyStatus_Ok`
-* :c:func:`PyWideStringList_Append`
-* :c:func:`PyWideStringList_Insert`
-* :c:func:`Py_ExitStatusException`
-* :c:func:`Py_InitializeFromConfig`
-* :c:func:`Py_PreInitialize`
-* :c:func:`Py_PreInitializeFromArgs`
-* :c:func:`Py_PreInitializeFromBytesArgs`
-* :c:func:`Py_RunMain`
-* :c:func:`Py_GetArgcArgv`
+* The :ref:`Isolated Configuration <init-isolated-conf>` can be used to embed
+  Python into an application. It isolates Python from the system. For example,
+  environments variables are ignored, the LC_CTYPE locale is left unchanged and
+  no signal handler is registred.
 
-The preconfiguration (``PyPreConfig`` type) is stored in
-``_PyRuntime.preconfig`` and the configuration (``PyConfig`` type) is stored in
-``PyInterpreterState.config``.
+The :c:func:`Py_RunMain` function can be used to write a customized Python
+program.
 
 See also :ref:`Initialization, Finalization, and Threads <initialization>`.
 
@@ -55,8 +33,47 @@ See also :ref:`Initialization, Finalization, and Threads <initialization>`.
    :pep:`587` "Python Initialization Configuration".
 
 
+Example
+=======
+
+Example of customized Python always running in isolated mode::
+
+    int main(int argc, char **argv)
+    {
+        PyStatus status;
+
+        PyConfig config;
+        PyConfig_InitPythonConfig(&config);
+        config.isolated = 1;
+
+        /* Decode command line arguments.
+           Implicitly preinitialize Python (in isolated mode). */
+        status = PyConfig_SetBytesArgv(&config, argc, argv);
+        if (PyStatus_Exception(status)) {
+            goto exception;
+        }
+
+        status = Py_InitializeFromConfig(&config);
+        if (PyStatus_Exception(status)) {
+            goto exception;
+        }
+        PyConfig_Clear(&config);
+
+        return Py_RunMain();
+
+    exception:
+        PyConfig_Clear(&config);
+        if (PyStatus_IsExit(status)) {
+            return status.exitcode;
+        }
+        /* Display the error message and exit the process with
+           non-zero exit code */
+        Py_ExitStatusException(status);
+    }
+
+
 PyWideStringList
-----------------
+================
 
 .. c:type:: PyWideStringList
 
@@ -95,7 +112,7 @@ PyWideStringList
       List items.
 
 PyStatus
---------
+========
 
 .. c:type:: PyStatus
 
@@ -128,6 +145,8 @@ PyStatus
 
       Initialization error with a message.
 
+      *err_msg* must not be ``NULL``.
+
    .. c:function:: PyStatus PyStatus_NoMemory(void)
 
       Memory allocation failure (out of memory).
@@ -185,7 +204,7 @@ Example::
 
 
 PyPreConfig
------------
+===========
 
 .. c:type:: PyPreConfig
 
@@ -315,7 +334,7 @@ PyPreConfig
 .. _c-preinit:
 
 Preinitialize Python with PyPreConfig
--------------------------------------
+=====================================
 
 The preinitialization of Python:
 
@@ -324,12 +343,17 @@ The preinitialization of Python:
 * Set the :ref:`Python UTF-8 Mode <utf8-mode>`
   (:c:member:`PyPreConfig.utf8_mode`)
 
+The current preconfiguration (``PyPreConfig`` type) is stored in
+``_PyRuntime.preconfig``.
+
 Functions to preinitialize Python:
 
 .. c:function:: PyStatus Py_PreInitialize(const PyPreConfig *preconfig)
 
    Preinitialize Python from *preconfig* preconfiguration.
 
+   *preconfig* must not be ``NULL``.
+
 .. c:function:: PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv)
 
    Preinitialize Python from *preconfig* preconfiguration.
@@ -337,6 +361,8 @@ Functions to preinitialize Python:
    Parse *argv* command line arguments (bytes strings) if
    :c:member:`~PyPreConfig.parse_argv` of *preconfig* is non-zero.
 
+   *preconfig* must not be ``NULL``.
+
 .. c:function:: PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t * const * argv)
 
    Preinitialize Python from *preconfig* preconfiguration.
@@ -344,6 +370,8 @@ Functions to preinitialize Python:
    Parse *argv* command line arguments (wide strings) if
    :c:member:`~PyPreConfig.parse_argv` of *preconfig* is non-zero.
 
+   *preconfig* must not be ``NULL``.
+
 The caller is responsible to handle exceptions (error or exit) using
 :c:func:`PyStatus_Exception` and :c:func:`Py_ExitStatusException`.
 
@@ -386,7 +414,7 @@ the :ref:`Python UTF-8 Mode <utf8-mode>`::
 
 
 PyConfig
---------
+========
 
 .. c:type:: PyConfig
 
@@ -447,8 +475,20 @@ PyConfig
 
       Fields which are already initialized are left unchanged.
 
+      The :c:func:`PyConfig_Read` function only parses
+      :c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
+      is set to ``2`` after arguments are parsed. Since Python arguments are
+      strippped from :c:member:`PyConfig.argv`, parsing arguments twice would
+      parse the application options as Python options.
+
       :ref:`Preinitialize Python <c-preinit>` if needed.
 
+      .. versionchanged:: 3.10
+         The :c:member:`PyConfig.argv` arguments are now only parsed once,
+         :c:member:`PyConfig.parse_argv` is set to ``2`` after arguments are
+         parsed, and arguments are only parsed if
+         :c:member:`PyConfig.parse_argv` equals ``1``.
+
    .. c:function:: void PyConfig_Clear(PyConfig *config)
 
       Release configuration memory.
@@ -496,7 +536,7 @@ PyConfig
 
       Default: ``NULL``.
 
-      Part of the :ref:`Path Configuration <init-path-config>` output.
+      Part of the :ref:`Python Path Configuration <init-path-config>` output.
 
    .. c:member:: wchar_t* base_executable
 
@@ -508,7 +548,7 @@ PyConfig
 
       Default: ``NULL``.
 
-      Part of the :ref:`Path Configuration <init-path-config>` output.
+      Part of the :ref:`Python Path Configuration <init-path-config>` output.
 
    .. c:member:: wchar_t* base_prefix
 
@@ -516,7 +556,7 @@ PyConfig
 
       Default: ``NULL``.
 
-      Part of the :ref:`Path Configuration <init-path-config>` output.
+      Part of the :ref:`Python Path Configuration <init-path-config>` output.
 
    .. c:member:: int buffered_stdio
 
@@ -598,7 +638,7 @@ PyConfig
 
       Default: ``NULL``.
 
-      Part of the :ref:`Path Configuration <init-path-config>` output.
+      Part of the :ref:`Python Path Configuration <init-path-config>` output.
 
    .. c:member:: wchar_t* executable
 
@@ -607,7 +647,7 @@ PyConfig
 
       Default: ``NULL``.
 
-      Part of the :ref:`Path Configuration <init-path-config>` output.
+      Part of the :ref:`Python Path Configuration <init-path-config>` output.
 
    .. c:member:: int faulthandler
 
@@ -690,7 +730,7 @@ PyConfig
 
       Default: ``NULL``.
 
-      Part of the :ref:`Path Configuration <init-path-config>` input.
+      Part of the :ref:`Python Path Configuration <init-path-config>` input.
 
    .. c:member:: int import_time
 
@@ -781,7 +821,7 @@ PyConfig
       Default: value of the ``PLATLIBDIR`` macro which is set at configure time
       by ``--with-platlibdir`` (default: ``"lib"``).
 
-      Part of the :ref:`Path Configuration <init-path-config>` input.
+      Part of the :ref:`Python Path Configuration <init-path-config>` input.
 
       .. versionadded:: 3.9
 
@@ -794,7 +834,7 @@ PyConfig
 
       Default: ``NULL``.
 
-      Part of the :ref:`Path Configuration <init-path-config>` input.
+      Part of the :ref:`Python Path Configuration <init-path-config>` input.
 
    .. c:member:: PyWideStringList module_search_paths
    .. c:member:: int module_search_paths_set
@@ -802,14 +842,14 @@ PyConfig
       Module search paths: :data:`sys.path`.
 
       If :c:member:`~PyConfig.module_search_paths_set` is equal to 0, the
-      function calculating the :ref:`Path Configuration <init-path-config>`
+      function calculating the :ref:`Python Path Configuration <init-path-config>`
       overrides the :c:member:`~PyConfig.module_search_paths` and sets
       :c:member:`~PyConfig.module_search_paths_set` to ``1``.
 
       Default: empty list (``module_search_paths``) and ``0``
       (``module_search_paths_set``).
 
-      Part of the :ref:`Path Configuration <init-path-config>` output.
+      Part of the :ref:`Python Path Configuration <init-path-config>` output.
 
    .. c:member:: int optimization_level
 
@@ -831,7 +871,7 @@ PyConfig
 
       If :c:member:`~PyConfig.orig_argv` list is empty and
       :c:member:`~PyConfig.argv` is not a list only containing an empty
-      string, :c:func:`PyConfig_Read()` copies :c:member:`~PyConfig.argv` into
+      string, :c:func:`PyConfig_Read` copies :c:member:`~PyConfig.argv` into
       :c:member:`~PyConfig.orig_argv` before modifying
       :c:member:`~PyConfig.argv` (if :c:member:`~PyConfig.parse_argv` is
       non-zero).
@@ -847,12 +887,22 @@ PyConfig
 
       Parse command line arguments?
 
-      If non-zero, parse :c:member:`~PyConfig.argv` the same way the regular
+      If equals to ``1``, parse :c:member:`~PyConfig.argv` the same way the regular
       Python parses :ref:`command line arguments <using-on-cmdline>`, and strip
       Python arguments from :c:member:`~PyConfig.argv`.
 
+      The :c:func:`PyConfig_Read` function only parses
+      :c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
+      is set to ``2`` after arguments are parsed. Since Python arguments are
+      strippped from :c:member:`PyConfig.argv`, parsing arguments twice would
+      parse the application options as Python options.
+
       Default: ``1`` in Python mode, ``0`` in isolated mode.
 
+      .. versionchanged:: 3.10
+         The :c:member:`PyConfig.argv` arguments are now only parsed if
+         :c:member:`PyConfig.parse_argv` equals to ``1``.
+
    .. c:member:: int parser_debug
 
       Parser debug mode. If greater than 0, turn on parser debugging output (for expert only, depending
@@ -865,7 +915,7 @@ PyConfig
 
    .. c:member:: int pathconfig_warnings
 
-      On Unix, if non-zero, calculating the :ref:`Path Configuration
+      On Unix, if non-zero, calculating the :ref:`Python Path Configuration
       <init-path-config>` can log warnings into ``stderr``. If equals to 0,
       suppress these warnings.
 
@@ -873,7 +923,7 @@ PyConfig
 
       Default: ``1`` in Python mode, ``0`` in isolated mode.
 
-      Part of the :ref:`Path Configuration <init-path-config>` input.
+      Part of the :ref:`Python Path Configuration <init-path-config>` input.
 
    .. c:member:: wchar_t* prefix
 
@@ -882,7 +932,7 @@ PyConfig
 
       Default: ``NULL``.
 
-      Part of the :ref:`Path Configuration <init-path-config>` output.
+      Part of the :ref:`Python Path Configuration <init-path-config>` output.
 
    .. c:member:: wchar_t* program_name
 
@@ -900,7 +950,7 @@ PyConfig
 
       Default: ``NULL``.
 
-      Part of the :ref:`Path Configuration <init-path-config>` input.
+      Part of the :ref:`Python Path Configuration <init-path-config>` input.
 
    .. c:member:: wchar_t* pycache_prefix
 
@@ -1106,7 +1156,7 @@ the :option:`-X` command line option.
 
 
 Initialization with PyConfig
-----------------------------
+============================
 
 Function to initialize Python:
 
@@ -1121,6 +1171,9 @@ If :c:func:`PyImport_FrozenModules`, :c:func:`PyImport_AppendInittab` or
 :c:func:`PyImport_ExtendInittab` are used, they must be set or called after
 Python preinitialization and before the Python initialization.
 
+The current configuration (``PyConfig`` type) is stored in
+``PyInterpreterState.config``.
+
 Example setting the program name::
 
     void init_python(void)
@@ -1134,17 +1187,17 @@ Example setting the program name::
         status = PyConfig_SetString(&config, &config.program_name,
                                     L"/path/to/my_program");
         if (PyStatus_Exception(status)) {
-            goto fail;
+            goto exception;
         }
 
         status = Py_InitializeFromConfig(&config);
         if (PyStatus_Exception(status)) {
-            goto fail;
+            goto exception;
         }
         PyConfig_Clear(&config);
         return;
 
-    fail:
+    exception:
         PyConfig_Clear(&config);
         Py_ExitStatusException(status);
     }
@@ -1200,7 +1253,7 @@ configuration, and then override some parameters::
 .. _init-isolated-conf:
 
 Isolated Configuration
-----------------------
+======================
 
 :c:func:`PyPreConfig_InitIsolatedConfig` and
 :c:func:`PyConfig_InitIsolatedConfig` functions create a configuration to
@@ -1213,7 +1266,7 @@ and user site directory. The C standard streams (ex: ``stdout``) and the
 LC_CTYPE locale are left unchanged. Signal handlers are not installed.
 
 Configuration files are still used with this configuration. Set the
-:ref:`Path Configuration <init-path-config>` ("output fields") to ignore these
+:ref:`Python Path Configuration <init-path-config>` ("output fields") to ignore these
 configuration files and avoid the function computing the default path
 configuration.
 
@@ -1221,7 +1274,7 @@ configuration.
 .. _init-python-config:
 
 Python Configuration
---------------------
+====================
 
 :c:func:`PyPreConfig_InitPythonConfig` and :c:func:`PyConfig_InitPythonConfig`
 functions create a configuration to build a customized Python which behaves as
@@ -1235,46 +1288,11 @@ and :ref:`Python UTF-8 Mode <utf8-mode>`
 (:pep:`540`) depending on the LC_CTYPE locale, :envvar:`PYTHONUTF8` and
 :envvar:`PYTHONCOERCECLOCALE` environment variables.
 
-Example of customized Python always running in isolated mode::
-
-    int main(int argc, char **argv)
-    {
-        PyStatus status;
-
-        PyConfig config;
-        PyConfig_InitPythonConfig(&config);
-        config.isolated = 1;
-
-        /* Decode command line arguments.
-           Implicitly preinitialize Python (in isolated mode). */
-        status = PyConfig_SetBytesArgv(&config, argc, argv);
-        if (PyStatus_Exception(status)) {
-            goto fail;
-        }
-
-        status = Py_InitializeFromConfig(&config);
-        if (PyStatus_Exception(status)) {
-            goto fail;
-        }
-        PyConfig_Clear(&config);
-
-        return Py_RunMain();
-
-    fail:
-        PyConfig_Clear(&config);
-        if (PyStatus_IsExit(status)) {
-            return status.exitcode;
-        }
-        /* Display the error message and exit the process with
-           non-zero exit code */
-        Py_ExitStatusException(status);
-    }
-
 
 .. _init-path-config:
 
-Path Configuration
-------------------
+Python Path Configuration
+=========================
 
 :c:type:`PyConfig` contains multiple fields for the path configuration:
 
@@ -1354,7 +1372,7 @@ The ``__PYVENV_LAUNCHER__`` environment variable is used to set
 
 
 Py_RunMain()
-------------
+============
 
 .. c:function:: int Py_RunMain(void)
 
@@ -1374,7 +1392,7 @@ customized Python always running in isolated mode using
 
 
 Py_GetArgcArgv()
-----------------
+================
 
 .. c:function:: void Py_GetArgcArgv(int *argc, wchar_t ***argv)
 
@@ -1384,7 +1402,7 @@ Py_GetArgcArgv()
 
 
 Multi-Phase Initialization Private Provisional API
---------------------------------------------------
+==================================================
 
 This section is a private provisional API introducing multi-phase
 initialization, the core feature of the :pep:`432`:

Doc/c-api/intro.rst

@@ -326,7 +326,7 @@ when it's no longer needed---or passing on this responsibility (usually to its
 caller). When a function passes ownership of a reference on to its caller, the
 caller is said to receive a *new* reference.  When no ownership is transferred,
 the caller is said to *borrow* the reference. Nothing needs to be done for a
-borrowed reference.
+:term:`borrowed reference`.
 
 Conversely, when a calling function passes in a reference to an  object, there
 are two possibilities: the function *steals* a  reference to the object, or it

Doc/c-api/module.rst

@@ -264,7 +264,7 @@ of the following two module creation functions:
       instead; only use this if you are sure you need it.
 
 Before it is returned from in the initialization function, the resulting module
-object is typically populated using functions like :c:func:`PyModule_AddObject`.
+object is typically populated using functions like :c:func:`PyModule_AddObjectRef`.
 
 .. _multi-phase-initialization:
 
@@ -437,26 +437,102 @@ a function called from a module execution slot (if using multi-phase
 initialization), can use the following functions to help initialize the module
 state:
 
+.. c:function:: int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)
+
+   Add an object to *module* as *name*.  This is a convenience function which
+   can be used from the module's initialization function.
+
+   On success, return ``0``. On error, raise an exception and return ``-1``.
+
+   Return ``NULL`` if *value* is ``NULL``. It must be called with an exception
+   raised in this case.
+
+   Example usage::
+
+       static int
+       add_spam(PyObject *module, int value)
+       {
+           PyObject *obj = PyLong_FromLong(value);
+           if (obj == NULL) {
+               return -1;
+           }
+           int res = PyModule_AddObjectRef(module, "spam", obj);
+           Py_DECREF(obj);
+           return res;
+        }
+
+   The example can also be written without checking explicitly if *obj* is
+   ``NULL``::
+
+       static int
+       add_spam(PyObject *module, int value)
+       {
+           PyObject *obj = PyLong_FromLong(value);
+           int res = PyModule_AddObjectRef(module, "spam", obj);
+           Py_XDECREF(obj);
+           return res;
+        }
+
+   Note that ``Py_XDECREF()`` should be used instead of ``Py_DECREF()`` in
+   this case, since *obj* can be ``NULL``.
+
+   .. versionadded:: 3.10
+
+
 .. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
 
-   Add an object to *module* as *name*.  This is a convenience function which can
-   be used from the module's initialization function.  This steals a reference to
-   *value* on success. Return ``-1`` on error, ``0`` on success.
+   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
+   easy to introduce reference leaks by misusing the
+   :c:func:`PyModule_AddObject` function.
 
    .. note::
 
-      Unlike other functions that steal references, ``PyModule_AddObject()`` only
-      decrements the reference count of *value* **on success**.
+      Unlike other functions that steal references, ``PyModule_AddObject()``
+      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. Example usage::
+      :c:func:`Py_DECREF` *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``::
+
+      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;
+      }
+
+   Note that ``Py_XDECREF()`` should be used instead of ``Py_DECREF()`` in
+   this case, since *obj* can be ``NULL``.
 
-         Py_INCREF(spam);
-         if (PyModule_AddObject(module, "spam", spam) < 0) {
-             Py_DECREF(module);
-             Py_DECREF(spam);
-             return NULL;
-         }
 
 .. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
 

Doc/c-api/refcounting.rst

@@ -13,8 +13,14 @@ objects.
 
 .. c:function:: void Py_INCREF(PyObject *o)
 
-   Increment the reference count for object *o*.  The object must not be ``NULL``; if
-   you aren't sure that it isn't ``NULL``, use :c:func:`Py_XINCREF`.
+   Increment the reference count for object *o*.
+
+   This function is usually used to convert a :term:`borrowed reference` to a
+   :term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be
+   used to create a new :term:`strong reference`.
+
+   The object must not be ``NULL``; if you aren't sure that it isn't
+   ``NULL``, use :c:func:`Py_XINCREF`.
 
 
 .. c:function:: void Py_XINCREF(PyObject *o)
@@ -22,13 +28,55 @@ objects.
    Increment the reference count for object *o*.  The object may be ``NULL``, in
    which case the macro has no effect.
 
+   See also :c:func:`Py_XNewRef`.
+
+
+.. c:function:: PyObject* Py_NewRef(PyObject *o)
+
+   Create a new :term:`strong reference` to an object: increment the reference
+   count of the object *o* and return the object *o*.
+
+   When the :term:`strong reference` is no longer needed, :c:func:`Py_DECREF`
+   should be called on it to decrement the object reference count.
+
+   The object *o* must not be ``NULL``; use :c:func:`Py_XNewRef` if *o* can be
+   ``NULL``.
+
+   For example::
+
+       Py_INCREF(obj);
+       self->attr = obj;
+
+   can be written as::
+
+       self->attr = Py_NewRef(obj);
+
+   See also :c:func:`Py_INCREF`.
+
+   .. versionadded:: 3.10
+
+
+.. c:function:: PyObject* Py_XNewRef(PyObject *o)
+
+   Similar to :c:func:`Py_NewRef`, but the object *o* can be NULL.
+
+   If the object *o* is ``NULL``, the function just returns ``NULL``.
+
+   .. versionadded:: 3.10
+
 
 .. c:function:: void Py_DECREF(PyObject *o)
 
-   Decrement the reference count for object *o*.  The object must not be ``NULL``; if
-   you aren't sure that it isn't ``NULL``, use :c:func:`Py_XDECREF`.  If the reference
-   count reaches zero, the object's type's deallocation function (which must not be
-   ``NULL``) is invoked.
+   Decrement the reference count for object *o*.
+
+   If the reference count reaches zero, the object's type's deallocation
+   function (which must not be ``NULL``) is invoked.
+
+   This function is usually used to delete a :term:`strong reference` before
+   exiting its scope.
+
+   The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``,
+   use :c:func:`Py_XDECREF`.
 
    .. warning::
 

Doc/c-api/reflection.rst

@@ -35,7 +35,7 @@ Reflection
 
    Get the *frame* next outer frame.
 
-   Return a strong reference, or ``NULL`` if *frame* has no outer frame.
+   Return a :term:`strong reference`, or ``NULL`` if *frame* has no outer frame.
 
    *frame* must not be ``NULL``.
 
@@ -46,7 +46,7 @@ Reflection
 
    Get the *frame* code.
 
-   Return a strong reference.
+   Return a :term:`strong reference`.
 
    *frame* must not be ``NULL``. The result (frame code) cannot be ``NULL``.
 

Doc/c-api/structures.rst

@@ -66,11 +66,9 @@ the definition of all other Python objects.
 
    Get the type of the Python object *o*.
 
-   Return a borrowed reference.
+   Return a :term:`borrowed reference`.
 
-   .. versionchanged:: 3.10
-      :c:func:`Py_TYPE()` is changed to the inline static function.
-      Use :c:func:`Py_SET_TYPE()` to set an object type.
+   The :c:func:`Py_SET_TYPE` function must be used to set an object type.
 
 
 .. c:function:: int Py_IS_TYPE(PyObject *o, PyTypeObject *type)
@@ -108,9 +106,7 @@ the definition of all other Python objects.
 
    Get the size of the Python object *o*.
 
-   .. versionchanged:: 3.10
-      :c:func:`Py_SIZE()` is changed to the inline static function.
-      Use :c:func:`Py_SET_SIZE()` to set an object size.
+   The :c:func:`Py_SET_SIZE` function must be used to set an object size.
 
 
 .. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
@@ -263,10 +259,12 @@ There are these calling conventions:
    of :c:type:`PyObject*` values indicating the arguments and the third
    parameter is the number of arguments (the length of the array).
 
-   This is not part of the :ref:`limited API <stable>`.
-
    .. versionadded:: 3.7
 
+   .. versionchanged:: 3.10
+
+      ``METH_FASTCALL`` is now part of the stable ABI.
+
 
 .. data:: METH_FASTCALL | METH_KEYWORDS
 

Doc/c-api/tuple.rst

@@ -57,7 +57,7 @@ Tuple Objects
 .. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
 
    Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
-   out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
+   negative or out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
 
 
 .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

Doc/c-api/type.rst

@@ -105,10 +105,12 @@ Type Objects
 
    See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument.
 
-   An exception is raised if *type* is not a heap type.
-
    .. versionadded:: 3.4
 
+   .. versionchanged:: 3.10
+      :c:func:`PyType_GetSlot` can now accept all types.
+      Previously, it was limited to heap types.
+
 .. c:function:: PyObject* PyType_GetModule(PyTypeObject *type)
 
    Return the module object associated with the given type when the type was
@@ -152,10 +154,10 @@ The following functions and structs are used to create
    Creates and returns a heap type object from the *spec*
    (:const:`Py_TPFLAGS_HEAPTYPE`).
 
-   If *bases* is a tuple, the created heap type contains all types contained
-   in it as base types.
-
-   If *bases* is ``NULL``, the *Py_tp_base* slot is used instead.
+   The *bases* argument can be used to specify base classes; it can either
+   be only one class or a tuple of classes.
+   If *bases* is ``NULL``, the *Py_tp_bases* slot is used instead.
+   If that also is ``NULL``, the *Py_tp_base* slot is used instead.
    If that also is ``NULL``, the new type derives from :class:`object`.
 
    The *module* argument can be used to record the module in which the new
@@ -169,6 +171,11 @@ The following functions and structs are used to create
 
    .. versionadded:: 3.9
 
+   .. versionchanged:: 3.10
+
+      The function now accepts a single class as the *bases* argument and
+      ``NULL`` as the ``tp_doc`` slot.
+
 .. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
 
    Equivalent to ``PyType_FromModuleAndSpec(NULL, spec, bases)``.
@@ -247,7 +254,8 @@ The following functions and structs are used to create
       * :c:member:`~PyBufferProcs.bf_getbuffer`
       * :c:member:`~PyBufferProcs.bf_releasebuffer`
 
-      Setting :c:data:`Py_tp_bases` may be problematic on some platforms.
+      Setting :c:data:`Py_tp_bases` or :c:data:`Py_tp_base` may be
+      problematic on some platforms.
       To avoid issues, use the *bases* argument of
       :py:func:`PyType_FromSpecWithBases` instead.
 
@@ -260,4 +268,4 @@ The following functions and structs are used to create
       The desired value of the slot. In most cases, this is a pointer
       to a function.
 
-      May not be ``NULL``.
+      Slots other than ``Py_tp_doc`` may not be ``NULL``.

Doc/c-api/typeobj.rst

@@ -199,6 +199,8 @@ sub-slots
    +---------------------------------------------------------+-----------------------------------+--------------+
    | :c:member:`~PyAsyncMethods.am_anext`                    | :c:type:`unaryfunc`               | __anext__    |
    +---------------------------------------------------------+-----------------------------------+--------------+
+   | :c:member:`~PyAsyncMethods.am_send`                     | :c:type:`sendfunc`                |              |
+   +---------------------------------------------------------+-----------------------------------+--------------+
    |                                                                                                            |
    +---------------------------------------------------------+-----------------------------------+--------------+
    | :c:member:`~PyNumberMethods.nb_add`                     | :c:type:`binaryfunc`              | __add__      |
@@ -1168,6 +1170,14 @@ and :c:type:`PyType_Type` effectively act as defaults.)
       .. versionadded:: 3.9
 
 
+   .. data:: Py_TPFLAGS_HAVE_AM_SEND
+
+      This bit is set when the :c:member:`~PyAsyncMethods.am_send` entry is present in the
+      :c:member:`~PyTypeObject.tp_as_async` slot of type structure.
+
+      .. versionadded:: 3.10
+
+
 .. c:member:: const char* PyTypeObject.tp_doc
 
    An optional pointer to a NUL-terminated C string giving the docstring for this
@@ -1213,8 +1223,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
    :func:`~gc.get_referents` function will include it.
 
    .. warning::
-       When implementing :c:member:`~PyTypeObject.tp_traverse`, only the members
-       that the instance *owns* (by having strong references to them) must be
+       When implementing :c:member:`~PyTypeObject.tp_traverse`, only the
+       members that the instance *owns* (by having :term:`strong references
+       <strong reference>` to them) must be
        visited. For instance, if an object supports weak references via the
        :c:member:`~PyTypeObject.tp_weaklist` slot, the pointer supporting
        the linked list (what *tp_weaklist* points to) must **not** be
@@ -2303,6 +2314,7 @@ Async Object Structures
             unaryfunc am_await;
             unaryfunc am_aiter;
             unaryfunc am_anext;
+            sendfunc am_send;
         } PyAsyncMethods;
 
 .. c:member:: unaryfunc PyAsyncMethods.am_await
@@ -2336,6 +2348,15 @@ Async Object Structures
    Must return an :term:`awaitable` object.  See :meth:`__anext__` for details.
    This slot may be set to ``NULL``.
 
+.. c:member:: sendfunc PyAsyncMethods.am_send
+
+   The signature of this function is::
+
+      PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);
+
+   See :c:func:`PyIter_Send` for details.
+   This slot may be set to ``NULL``.
+
 
 .. _slot-typedefs:
 
@@ -2431,6 +2452,10 @@ Slot Type typedefs
 
 .. c:type:: PyObject *(*binaryfunc)(PyObject *, PyObject *)
 
+.. c:type:: PySendResult (*sendfunc)(PyObject *, PyObject *, PyObject **)
+
+   See :c:member:`~PyAsyncMethods.am_send`.
+
 .. c:type:: PyObject *(*ternaryfunc)(PyObject *, PyObject *, PyObject *)
 
 .. c:type:: PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t)

Doc/c-api/weakref.rst

@@ -57,10 +57,10 @@ as much as it can.
 
    .. note::
 
-      This function returns a **borrowed reference** to the referenced object.
+      This function returns a :term:`borrowed reference` to the referenced object.
       This means that you should always call :c:func:`Py_INCREF` on the object
-      except if you know that it cannot be destroyed while you are still
-      using it.
+      except when it cannot be destroyed before the last usage of the borrowed
+      reference.
 
 
 .. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)

Doc/conf.py

@@ -15,8 +15,7 @@ sys.path.append(os.path.abspath('includes'))
 
 extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',
               'pyspecific', 'c_annotations', 'escape4chm',
-              'asdl_highlight', 'peg_highlight']
-
+              'asdl_highlight', 'peg_highlight', 'glossary_search']
 
 doctest_global_setup = '''
 try:

Doc/data/refcounts.dat

@@ -3007,6 +3007,9 @@ Py_GetVersion:const char*:::
 Py_INCREF:void:::
 Py_INCREF:PyObject*:o:+1:
 
+Py_NewRef:void:::
+Py_NewRef:PyObject*:o:+1:
+
 Py_Initialize:void:::
 
 Py_IsInitialized:int:::
@@ -3028,6 +3031,9 @@ Py_XDECREF:PyObject*:o:-1:if o is not NULL
 Py_XINCREF:void:::
 Py_XINCREF:PyObject*:o:+1:if o is not NULL
 
+Py_XNewRef:void:::
+Py_XNewRef:PyObject*:o:+1:if o is not NULL
+
 _PyImport_Fini:void:::
 
 _PyObject_New:PyObject*::+1:

Doc/data/stable_abi.dat

@@ -0,0 +1,780 @@
+# File generated by 'make regen-limited-abi'
+# This is NOT an authoritative list of stable ABI symbols
+PyArg_Parse
+PyArg_ParseTuple
+PyArg_ParseTupleAndKeywords
+PyArg_UnpackTuple
+PyArg_VaParse
+PyArg_VaParseTupleAndKeywords
+PyArg_ValidateKeywordArguments
+PyBaseObject_Type
+PyBool_FromLong
+PyBool_Type
+PyByteArrayIter_Type
+PyByteArray_AsString
+PyByteArray_Concat
+PyByteArray_FromObject
+PyByteArray_FromStringAndSize
+PyByteArray_Resize
+PyByteArray_Size
+PyByteArray_Type
+PyBytesIter_Type
+PyBytes_AsString
+PyBytes_AsStringAndSize
+PyBytes_Concat
+PyBytes_ConcatAndDel
+PyBytes_DecodeEscape
+PyBytes_FromFormat
+PyBytes_FromFormatV
+PyBytes_FromObject
+PyBytes_FromString
+PyBytes_FromStringAndSize
+PyBytes_Repr
+PyBytes_Size
+PyBytes_Type
+PyCFunction_Call
+PyCFunction_GetFlags
+PyCFunction_GetFunction
+PyCFunction_GetSelf
+PyCFunction_NewEx
+PyCFunction_Type
+PyCMethod_New
+PyCallIter_New
+PyCallIter_Type
+PyCallable_Check
+PyCapsule_GetContext
+PyCapsule_GetDestructor
+PyCapsule_GetName
+PyCapsule_GetPointer
+PyCapsule_Import
+PyCapsule_IsValid
+PyCapsule_New
+PyCapsule_SetContext
+PyCapsule_SetDestructor
+PyCapsule_SetName
+PyCapsule_SetPointer
+PyCapsule_Type
+PyClassMethodDescr_Type
+PyCodec_BackslashReplaceErrors
+PyCodec_Decode
+PyCodec_Decoder
+PyCodec_Encode
+PyCodec_Encoder
+PyCodec_IgnoreErrors
+PyCodec_IncrementalDecoder
+PyCodec_IncrementalEncoder
+PyCodec_KnownEncoding
+PyCodec_LookupError
+PyCodec_NameReplaceErrors
+PyCodec_Register
+PyCodec_RegisterError
+PyCodec_ReplaceErrors
+PyCodec_StreamReader
+PyCodec_StreamWriter
+PyCodec_StrictErrors
+PyCodec_Unregister
+PyCodec_XMLCharRefReplaceErrors
+PyComplex_FromDoubles
+PyComplex_ImagAsDouble
+PyComplex_RealAsDouble
+PyComplex_Type
+PyDescr_NewClassMethod
+PyDescr_NewGetSet
+PyDescr_NewMember
+PyDescr_NewMethod
+PyDictItems_Type
+PyDictIterItem_Type
+PyDictIterKey_Type
+PyDictIterValue_Type
+PyDictKeys_Type
+PyDictProxy_New
+PyDictProxy_Type
+PyDictRevIterItem_Type
+PyDictRevIterKey_Type
+PyDictRevIterValue_Type
+PyDictValues_Type
+PyDict_Clear
+PyDict_Contains
+PyDict_Copy
+PyDict_DelItem
+PyDict_DelItemString
+PyDict_GetItem
+PyDict_GetItemString
+PyDict_GetItemWithError
+PyDict_Items
+PyDict_Keys
+PyDict_Merge
+PyDict_MergeFromSeq2
+PyDict_New
+PyDict_Next
+PyDict_SetItem
+PyDict_SetItemString
+PyDict_Size
+PyDict_Type
+PyDict_Update
+PyDict_Values
+PyEllipsis_Type
+PyEnum_Type
+PyErr_BadArgument
+PyErr_BadInternalCall
+PyErr_CheckSignals
+PyErr_Clear
+PyErr_Display
+PyErr_ExceptionMatches
+PyErr_Fetch
+PyErr_Format
+PyErr_FormatV
+PyErr_GetExcInfo
+PyErr_GivenExceptionMatches
+PyErr_NewException
+PyErr_NewExceptionWithDoc
+PyErr_NoMemory
+PyErr_NormalizeException
+PyErr_Occurred
+PyErr_Print
+PyErr_PrintEx
+PyErr_ProgramText
+PyErr_ResourceWarning
+PyErr_Restore
+PyErr_SetExcInfo
+PyErr_SetFromErrno
+PyErr_SetFromErrnoWithFilename
+PyErr_SetFromErrnoWithFilenameObject
+PyErr_SetFromErrnoWithFilenameObjects
+PyErr_SetImportError
+PyErr_SetImportErrorSubclass
+PyErr_SetInterrupt
+PyErr_SetNone
+PyErr_SetObject
+PyErr_SetString
+PyErr_SyntaxLocation
+PyErr_SyntaxLocationEx
+PyErr_WarnEx
+PyErr_WarnExplicit
+PyErr_WarnFormat
+PyErr_WriteUnraisable
+PyEval_AcquireLock
+PyEval_AcquireThread
+PyEval_CallFunction
+PyEval_CallMethod
+PyEval_CallObjectWithKeywords
+PyEval_EvalCode
+PyEval_EvalCodeEx
+PyEval_EvalFrame
+PyEval_EvalFrameEx
+PyEval_GetBuiltins
+PyEval_GetFrame
+PyEval_GetFuncDesc
+PyEval_GetFuncName
+PyEval_GetGlobals
+PyEval_GetLocals
+PyEval_InitThreads
+PyEval_ReleaseLock
+PyEval_ReleaseThread
+PyEval_RestoreThread
+PyEval_SaveThread
+PyEval_ThreadsInitialized
+PyExc_ArithmeticError
+PyExc_AssertionError
+PyExc_AttributeError
+PyExc_BaseException
+PyExc_BlockingIOError
+PyExc_BrokenPipeError
+PyExc_BufferError
+PyExc_BytesWarning
+PyExc_ChildProcessError
+PyExc_ConnectionAbortedError
+PyExc_ConnectionError
+PyExc_ConnectionRefusedError
+PyExc_ConnectionResetError
+PyExc_DeprecationWarning
+PyExc_EOFError
+PyExc_EnvironmentError
+PyExc_Exception
+PyExc_FileExistsError
+PyExc_FileNotFoundError
+PyExc_FloatingPointError
+PyExc_FutureWarning
+PyExc_GeneratorExit
+PyExc_IOError
+PyExc_ImportError
+PyExc_ImportWarning
+PyExc_IndentationError
+PyExc_IndexError
+PyExc_InterruptedError
+PyExc_IsADirectoryError
+PyExc_KeyError
+PyExc_KeyboardInterrupt
+PyExc_LookupError
+PyExc_MemoryError
+PyExc_ModuleNotFoundError
+PyExc_NameError
+PyExc_NotADirectoryError
+PyExc_NotImplementedError
+PyExc_OSError
+PyExc_OverflowError
+PyExc_PendingDeprecationWarning
+PyExc_PermissionError
+PyExc_ProcessLookupError
+PyExc_RecursionError
+PyExc_ReferenceError
+PyExc_ResourceWarning
+PyExc_RuntimeError
+PyExc_RuntimeWarning
+PyExc_StopAsyncIteration
+PyExc_StopIteration
+PyExc_SyntaxError
+PyExc_SyntaxWarning
+PyExc_SystemError
+PyExc_SystemExit
+PyExc_TabError
+PyExc_TimeoutError
+PyExc_TypeError
+PyExc_UnboundLocalError
+PyExc_UnicodeDecodeError
+PyExc_UnicodeEncodeError
+PyExc_UnicodeError
+PyExc_UnicodeTranslateError
+PyExc_UnicodeWarning
+PyExc_UserWarning
+PyExc_ValueError
+PyExc_Warning
+PyExc_ZeroDivisionError
+PyExceptionClass_Name
+PyException_GetCause
+PyException_GetContext
+PyException_GetTraceback
+PyException_SetCause
+PyException_SetContext
+PyException_SetTraceback
+PyFile_FromFd
+PyFile_GetLine
+PyFile_WriteObject
+PyFile_WriteString
+PyFilter_Type
+PyFloat_AsDouble
+PyFloat_FromDouble
+PyFloat_FromString
+PyFloat_GetInfo
+PyFloat_GetMax
+PyFloat_GetMin
+PyFloat_Type
+PyFrame_GetCode
+PyFrame_GetLineNumber
+PyFrozenSet_New
+PyFrozenSet_Type
+PyGC_Collect
+PyGILState_Ensure
+PyGILState_GetThisThreadState
+PyGILState_Release
+PyGetSetDescr_Type
+PyImport_AddModule
+PyImport_AddModuleObject
+PyImport_AppendInittab
+PyImport_ExecCodeModule
+PyImport_ExecCodeModuleEx
+PyImport_ExecCodeModuleObject
+PyImport_ExecCodeModuleWithPathnames
+PyImport_GetImporter
+PyImport_GetMagicNumber
+PyImport_GetMagicTag
+PyImport_GetModule
+PyImport_GetModuleDict
+PyImport_Import
+PyImport_ImportFrozenModule
+PyImport_ImportFrozenModuleObject
+PyImport_ImportModule
+PyImport_ImportModuleLevel
+PyImport_ImportModuleLevelObject
+PyImport_ImportModuleNoBlock
+PyImport_ReloadModule
+PyIndex_Check
+PyInterpreterState_Clear
+PyInterpreterState_Delete
+PyInterpreterState_Get
+PyInterpreterState_GetDict
+PyInterpreterState_GetID
+PyInterpreterState_New
+PyIter_Check
+PyIter_Next
+PyIter_Send
+PyListIter_Type
+PyListRevIter_Type
+PyList_Append
+PyList_AsTuple
+PyList_GetItem
+PyList_GetSlice
+PyList_Insert
+PyList_New
+PyList_Reverse
+PyList_SetItem
+PyList_SetSlice
+PyList_Size
+PyList_Sort
+PyList_Type
+PyLongRangeIter_Type
+PyLong_AsDouble
+PyLong_AsLong
+PyLong_AsLongAndOverflow
+PyLong_AsLongLong
+PyLong_AsLongLongAndOverflow
+PyLong_AsSize_t
+PyLong_AsSsize_t
+PyLong_AsUnsignedLong
+PyLong_AsUnsignedLongLong
+PyLong_AsUnsignedLongLongMask
+PyLong_AsUnsignedLongMask
+PyLong_AsVoidPtr
+PyLong_FromDouble
+PyLong_FromLong
+PyLong_FromLongLong
+PyLong_FromSize_t
+PyLong_FromSsize_t
+PyLong_FromString
+PyLong_FromUnsignedLong
+PyLong_FromUnsignedLongLong
+PyLong_FromVoidPtr
+PyLong_GetInfo
+PyLong_Type
+PyMap_Type
+PyMapping_Check
+PyMapping_GetItemString
+PyMapping_HasKey
+PyMapping_HasKeyString
+PyMapping_Items
+PyMapping_Keys
+PyMapping_Length
+PyMapping_SetItemString
+PyMapping_Size
+PyMapping_Values
+PyMarshal_ReadObjectFromString
+PyMarshal_WriteLongToFile
+PyMarshal_WriteObjectToFile
+PyMarshal_WriteObjectToString
+PyMem_Free
+PyMem_Malloc
+PyMem_Realloc
+PyMemberDescr_Type
+PyMember_GetOne
+PyMember_SetOne
+PyMemoryView_FromMemory
+PyMemoryView_FromObject
+PyMemoryView_GetContiguous
+PyMemoryView_Type
+PyMethodDescr_Type
+PyModuleDef_Init
+PyModuleDef_Type
+PyModule_AddFunctions
+PyModule_AddIntConstant
+PyModule_AddObject
+PyModule_AddObjectRef
+PyModule_AddStringConstant
+PyModule_AddType
+PyModule_Create2
+PyModule_ExecDef
+PyModule_FromDefAndSpec2
+PyModule_GetDef
+PyModule_GetDict
+PyModule_GetFilename
+PyModule_GetFilenameObject
+PyModule_GetName
+PyModule_GetNameObject
+PyModule_GetState
+PyModule_New
+PyModule_NewObject
+PyModule_SetDocString
+PyModule_Type
+PyNumber_Absolute
+PyNumber_Add
+PyNumber_And
+PyNumber_AsSsize_t
+PyNumber_Check
+PyNumber_Divmod
+PyNumber_Float
+PyNumber_FloorDivide
+PyNumber_InPlaceAdd
+PyNumber_InPlaceAnd
+PyNumber_InPlaceFloorDivide
+PyNumber_InPlaceLshift
+PyNumber_InPlaceMatrixMultiply
+PyNumber_InPlaceMultiply
+PyNumber_InPlaceOr
+PyNumber_InPlacePower
+PyNumber_InPlaceRemainder
+PyNumber_InPlaceRshift
+PyNumber_InPlaceSubtract
+PyNumber_InPlaceTrueDivide
+PyNumber_InPlaceXor
+PyNumber_Index
+PyNumber_Invert
+PyNumber_Long
+PyNumber_Lshift
+PyNumber_MatrixMultiply
+PyNumber_Multiply
+PyNumber_Negative
+PyNumber_Or
+PyNumber_Positive
+PyNumber_Power
+PyNumber_Remainder
+PyNumber_Rshift
+PyNumber_Subtract
+PyNumber_ToBase
+PyNumber_TrueDivide
+PyNumber_Xor
+PyOS_AfterFork
+PyOS_AfterFork_Child
+PyOS_AfterFork_Parent
+PyOS_BeforeFork
+PyOS_FSPath
+PyOS_InterruptOccurred
+PyOS_double_to_string
+PyOS_getsig
+PyOS_mystricmp
+PyOS_mystrnicmp
+PyOS_setsig
+PyOS_snprintf
+PyOS_string_to_double
+PyOS_strtol
+PyOS_strtoul
+PyOS_vsnprintf
+PyObject_ASCII
+PyObject_AsFileDescriptor
+PyObject_Bytes
+PyObject_Call
+PyObject_CallFunction
+PyObject_CallFunctionObjArgs
+PyObject_CallMethod
+PyObject_CallMethodObjArgs
+PyObject_CallNoArgs
+PyObject_CallObject
+PyObject_Calloc
+PyObject_ClearWeakRefs
+PyObject_DelItem
+PyObject_DelItemString
+PyObject_Dir
+PyObject_Format
+PyObject_Free
+PyObject_GC_Del
+PyObject_GC_IsFinalized
+PyObject_GC_IsTracked
+PyObject_GC_Track
+PyObject_GC_UnTrack
+PyObject_GenericGetAttr
+PyObject_GenericGetDict
+PyObject_GenericSetAttr
+PyObject_GenericSetDict
+PyObject_GetAttr
+PyObject_GetAttrString
+PyObject_GetItem
+PyObject_GetIter
+PyObject_HasAttr
+PyObject_HasAttrString
+PyObject_Hash
+PyObject_HashNotImplemented
+PyObject_Init
+PyObject_InitVar
+PyObject_IsInstance
+PyObject_IsSubclass
+PyObject_IsTrue
+PyObject_Length
+PyObject_Malloc
+PyObject_Not
+PyObject_Realloc
+PyObject_Repr
+PyObject_RichCompare
+PyObject_RichCompareBool
+PyObject_SelfIter
+PyObject_SetAttr
+PyObject_SetAttrString
+PyObject_SetItem
+PyObject_Size
+PyObject_Str
+PyObject_Type
+PyProperty_Type
+PyRangeIter_Type
+PyRange_Type
+PyReversed_Type
+PySeqIter_New
+PySeqIter_Type
+PySequence_Check
+PySequence_Concat
+PySequence_Contains
+PySequence_Count
+PySequence_DelItem
+PySequence_DelSlice
+PySequence_Fast
+PySequence_GetItem
+PySequence_GetSlice
+PySequence_In
+PySequence_InPlaceConcat
+PySequence_InPlaceRepeat
+PySequence_Index
+PySequence_Length
+PySequence_List
+PySequence_Repeat
+PySequence_SetItem
+PySequence_SetSlice
+PySequence_Size
+PySequence_Tuple
+PySetIter_Type
+PySet_Add
+PySet_Clear
+PySet_Contains
+PySet_Discard
+PySet_New
+PySet_Pop
+PySet_Size
+PySet_Type
+PySlice_AdjustIndices
+PySlice_GetIndices
+PySlice_GetIndicesEx
+PySlice_New
+PySlice_Type
+PySlice_Unpack
+PyState_AddModule
+PyState_FindModule
+PyState_RemoveModule
+PyStructSequence_GetItem
+PyStructSequence_New
+PyStructSequence_NewType
+PyStructSequence_SetItem
+PySuper_Type
+PySys_AddWarnOption
+PySys_AddWarnOptionUnicode
+PySys_AddXOption
+PySys_FormatStderr
+PySys_FormatStdout
+PySys_GetObject
+PySys_GetXOptions
+PySys_HasWarnOptions
+PySys_ResetWarnOptions
+PySys_SetArgv
+PySys_SetArgvEx
+PySys_SetObject
+PySys_SetPath
+PySys_WriteStderr
+PySys_WriteStdout
+PyThreadState_Clear
+PyThreadState_Delete
+PyThreadState_Get
+PyThreadState_GetDict
+PyThreadState_GetFrame
+PyThreadState_GetID
+PyThreadState_GetInterpreter
+PyThreadState_New
+PyThreadState_SetAsyncExc
+PyThreadState_Swap
+PyThread_GetInfo
+PyThread_ReInitTLS
+PyThread_acquire_lock
+PyThread_acquire_lock_timed
+PyThread_allocate_lock
+PyThread_create_key
+PyThread_delete_key
+PyThread_delete_key_value
+PyThread_exit_thread
+PyThread_free_lock
+PyThread_get_key_value
+PyThread_get_stacksize
+PyThread_get_thread_ident
+PyThread_get_thread_native_id
+PyThread_init_thread
+PyThread_release_lock
+PyThread_set_key_value
+PyThread_set_stacksize
+PyThread_start_new_thread
+PyThread_tss_alloc
+PyThread_tss_create
+PyThread_tss_delete
+PyThread_tss_free
+PyThread_tss_get
+PyThread_tss_is_created
+PyThread_tss_set
+PyTraceBack_Here
+PyTraceBack_Print
+PyTraceBack_Type
+PyTupleIter_Type
+PyTuple_GetItem
+PyTuple_GetSlice
+PyTuple_New
+PyTuple_Pack
+PyTuple_SetItem
+PyTuple_Size
+PyTuple_Type
+PyType_ClearCache
+PyType_FromModuleAndSpec
+PyType_FromSpec
+PyType_FromSpecWithBases
+PyType_GenericAlloc
+PyType_GenericNew
+PyType_GetFlags
+PyType_GetModule
+PyType_GetModuleState
+PyType_GetSlot
+PyType_IsSubtype
+PyType_Modified
+PyType_Ready
+PyType_Type
+PyUnicodeDecodeError_Create
+PyUnicodeDecodeError_GetEncoding
+PyUnicodeDecodeError_GetEnd
+PyUnicodeDecodeError_GetObject
+PyUnicodeDecodeError_GetReason
+PyUnicodeDecodeError_GetStart
+PyUnicodeDecodeError_SetEnd
+PyUnicodeDecodeError_SetReason
+PyUnicodeDecodeError_SetStart
+PyUnicodeEncodeError_GetEncoding
+PyUnicodeEncodeError_GetEnd
+PyUnicodeEncodeError_GetObject
+PyUnicodeEncodeError_GetReason
+PyUnicodeEncodeError_GetStart
+PyUnicodeEncodeError_SetEnd
+PyUnicodeEncodeError_SetReason
+PyUnicodeEncodeError_SetStart
+PyUnicodeIter_Type
+PyUnicodeTranslateError_GetEnd
+PyUnicodeTranslateError_GetObject
+PyUnicodeTranslateError_GetReason
+PyUnicodeTranslateError_GetStart
+PyUnicodeTranslateError_SetEnd
+PyUnicodeTranslateError_SetReason
+PyUnicodeTranslateError_SetStart
+PyUnicode_Append
+PyUnicode_AppendAndDel
+PyUnicode_AsASCIIString
+PyUnicode_AsCharmapString
+PyUnicode_AsDecodedObject
+PyUnicode_AsDecodedUnicode
+PyUnicode_AsEncodedObject
+PyUnicode_AsEncodedString
+PyUnicode_AsEncodedUnicode
+PyUnicode_AsLatin1String
+PyUnicode_AsRawUnicodeEscapeString
+PyUnicode_AsUCS4
+PyUnicode_AsUCS4Copy
+PyUnicode_AsUTF16String
+PyUnicode_AsUTF32String
+PyUnicode_AsUTF8AndSize
+PyUnicode_AsUTF8String
+PyUnicode_AsUnicodeEscapeString
+PyUnicode_AsWideChar
+PyUnicode_AsWideCharString
+PyUnicode_BuildEncodingMap
+PyUnicode_Compare
+PyUnicode_CompareWithASCIIString
+PyUnicode_Concat
+PyUnicode_Contains
+PyUnicode_Count
+PyUnicode_Decode
+PyUnicode_DecodeASCII
+PyUnicode_DecodeCharmap
+PyUnicode_DecodeFSDefault
+PyUnicode_DecodeFSDefaultAndSize
+PyUnicode_DecodeLatin1
+PyUnicode_DecodeLocale
+PyUnicode_DecodeLocaleAndSize
+PyUnicode_DecodeRawUnicodeEscape
+PyUnicode_DecodeUTF16
+PyUnicode_DecodeUTF16Stateful
+PyUnicode_DecodeUTF32
+PyUnicode_DecodeUTF32Stateful
+PyUnicode_DecodeUTF7
+PyUnicode_DecodeUTF7Stateful
+PyUnicode_DecodeUTF8
+PyUnicode_DecodeUTF8Stateful
+PyUnicode_DecodeUnicodeEscape
+PyUnicode_EncodeFSDefault
+PyUnicode_EncodeLocale
+PyUnicode_FSConverter
+PyUnicode_FSDecoder
+PyUnicode_Find
+PyUnicode_FindChar
+PyUnicode_Format
+PyUnicode_FromEncodedObject
+PyUnicode_FromFormat
+PyUnicode_FromFormatV
+PyUnicode_FromObject
+PyUnicode_FromOrdinal
+PyUnicode_FromString
+PyUnicode_FromStringAndSize
+PyUnicode_FromWideChar
+PyUnicode_GetDefaultEncoding
+PyUnicode_GetLength
+PyUnicode_GetSize
+PyUnicode_InternFromString
+PyUnicode_InternImmortal
+PyUnicode_InternInPlace
+PyUnicode_IsIdentifier
+PyUnicode_Join
+PyUnicode_Partition
+PyUnicode_RPartition
+PyUnicode_RSplit
+PyUnicode_ReadChar
+PyUnicode_Replace
+PyUnicode_Resize
+PyUnicode_RichCompare
+PyUnicode_Split
+PyUnicode_Splitlines
+PyUnicode_Substring
+PyUnicode_Tailmatch
+PyUnicode_Translate
+PyUnicode_Type
+PyUnicode_WriteChar
+PyWeakref_GetObject
+PyWeakref_NewProxy
+PyWeakref_NewRef
+PyWrapperDescr_Type
+PyWrapper_New
+PyZip_Type
+Py_AddPendingCall
+Py_AtExit
+Py_BuildValue
+Py_BytesMain
+Py_CompileString
+Py_DecRef
+Py_DecodeLocale
+Py_EncodeLocale
+Py_EndInterpreter
+Py_EnterRecursiveCall
+Py_Exit
+Py_FatalError
+Py_FileSystemDefaultEncodeErrors
+Py_FileSystemDefaultEncoding
+Py_Finalize
+Py_FinalizeEx
+Py_FrozenMain
+Py_GenericAlias
+Py_GenericAliasType
+Py_GetBuildInfo
+Py_GetCompiler
+Py_GetCopyright
+Py_GetExecPrefix
+Py_GetPath
+Py_GetPlatform
+Py_GetPrefix
+Py_GetProgramFullPath
+Py_GetProgramName
+Py_GetPythonHome
+Py_GetRecursionLimit
+Py_GetVersion
+Py_HasFileSystemDefaultEncoding
+Py_IncRef
+Py_Initialize
+Py_InitializeEx
+Py_IsInitialized
+Py_LeaveRecursiveCall
+Py_Main
+Py_MakePendingCalls
+Py_NewInterpreter
+Py_NewRef
+Py_ReprEnter
+Py_ReprLeave
+Py_SetPath
+Py_SetProgramName
+Py_SetPythonHome
+Py_SetRecursionLimit
+Py_SymtableString
+Py_UTF8Mode
+Py_VaBuildValue
+Py_XNewRef

Doc/glossary.rst

@@ -158,6 +158,18 @@ Glossary
       See also :term:`text file` for a file object able to read and write
       :class:`str` objects.
 
+   borrowed reference
+      In Python's C API, a borrowed reference is a reference to an object.
+      It does not modify the object reference count. It becomes a dangling
+      pointer if the object is destroyed. For example, a garbage collection can
+      remove the last :term:`strong reference` to the object and so destroy it.
+
+      Calling :c:func:`Py_INCREF` on the :term:`borrowed reference` is
+      recommended to convert it to a :term:`strong reference` in-place, except
+      when the object cannot be destroyed before the last usage of the borrowed
+      reference. The :c:func:`Py_NewRef` function can be used to create a new
+      :term:`strong reference`.
+
    bytes-like object
       An object that supports the :ref:`bufferobjects` and can
       export a C-:term:`contiguous` buffer. This includes all :class:`bytes`,
@@ -1100,6 +1112,18 @@ Glossary
       an :term:`expression` or one of several constructs with a keyword, such
       as :keyword:`if`, :keyword:`while` or :keyword:`for`.
 
+   strong reference
+      In Python's C API, a strong reference is a reference to an object
+      which increments the object's reference count when it is created and
+      decrements the object's reference count when it is deleted.
+
+      The :c:func:`Py_NewRef` function can be used to create a strong reference
+      to an object. Usually, the :c:func:`Py_DECREF` function must be called on
+      the strong reference before exiting the scope of the strong reference, to
+      avoid leaking one reference.
+
+      See also :term:`borrowed reference`.
+
    text encoding
       A codec which encodes Unicode strings to bytes.
 

Doc/howto/argparse.rst

@@ -83,7 +83,7 @@ Following is a result of running the code:
    $ python3 prog.py --help
    usage: prog.py [-h]
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
    $ python3 prog.py --verbose
    usage: prog.py [-h]
@@ -130,7 +130,7 @@ And running the code:
    positional arguments:
      echo
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
    $ python3 prog.py foo
    foo
@@ -172,7 +172,7 @@ And we get:
    positional arguments:
      echo        echo the string you use here
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
 
 Now, how about doing something even more useful::
@@ -241,7 +241,7 @@ And the output:
    $ python3 prog.py --help
    usage: prog.py [-h] [--verbosity VERBOSITY]
 
-   optional arguments:
+   options:
      -h, --help            show this help message and exit
      --verbosity VERBOSITY
                            increase output verbosity
@@ -289,7 +289,7 @@ And the output:
    $ python3 prog.py --help
    usage: prog.py [-h] [--verbose]
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
      --verbose   increase output verbosity
 
@@ -332,7 +332,7 @@ And here goes:
    $ python3 prog.py --help
    usage: prog.py [-h] [-v]
 
-   optional arguments:
+   options:
      -h, --help     show this help message and exit
      -v, --verbose  increase output verbosity
 
@@ -440,7 +440,7 @@ And the output:
    positional arguments:
      square                display a square of a given number
 
-   optional arguments:
+   options:
      -h, --help            show this help message and exit
      -v {0,1,2}, --verbosity {0,1,2}
                            increase output verbosity
@@ -468,7 +468,8 @@ verbosity argument (check the output of ``python --help``)::
        print(answer)
 
 We have introduced another action, "count",
-to count the number of occurrences of a specific optional arguments:
+to count the number of occurrences of specific options.
+
 
 .. code-block:: shell-session
 
@@ -489,7 +490,7 @@ to count the number of occurrences of a specific optional arguments:
    positional arguments:
      square           display a square of a given number
 
-   optional arguments:
+   options:
      -h, --help       show this help message and exit
      -v, --verbosity  increase output verbosity
    $ python3 prog.py 4 -vvv
@@ -626,7 +627,7 @@ Output:
      x                the base
      y                the exponent
 
-   optional arguments:
+   options:
      -h, --help       show this help message and exit
      -v, --verbosity
    $ python3 prog.py 4 2 -v
@@ -750,7 +751,7 @@ but not both at the same time:
      x              the base
      y              the exponent
 
-   optional arguments:
+   options:
      -h, --help     show this help message and exit
      -v, --verbose
      -q, --quiet

Doc/library/abc.rst

@@ -336,6 +336,7 @@ The :mod:`abc` module also provides the following functions:
    .. versionadded:: 3.4
 
 .. function:: update_abstractmethods(cls)
+
    A function to recalculate an abstract class's abstraction status. This
    function should be called if a class's abstract methods have been
    implemented or changed after it was created. Usually, this function should
@@ -343,7 +344,7 @@ The :mod:`abc` module also provides the following functions:
 
    Returns *cls*, to allow usage as a class decorator.
 
-   If *cls* is not an instance of ABCMeta, does nothing.
+   If *cls* is not an instance of :class:`ABCMeta`, does nothing.
 
    .. note::
 

Doc/library/argparse.rst

@@ -57,7 +57,7 @@ be run at the command line and provides useful help messages:
    positional arguments:
     N           an integer for the accumulator
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --sum       sum the integers (default: find the max)
 
@@ -217,14 +217,14 @@ The help for this program will display ``myprogram.py`` as the program name
    $ python myprogram.py --help
    usage: myprogram.py [-h] [--foo FOO]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO   foo help
    $ cd ..
    $ python subdir/myprogram.py --help
    usage: myprogram.py [-h] [--foo FOO]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO   foo help
 
@@ -235,7 +235,7 @@ To change this default behavior, another value can be supplied using the
    >>> parser.print_help()
    usage: myprogram [-h]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
 Note that the program name, whether determined from ``sys.argv[0]`` or from the
@@ -249,7 +249,7 @@ specifier.
    >>> parser.print_help()
    usage: myprogram [-h] [--foo FOO]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO   foo of the myprogram program
 
@@ -269,7 +269,7 @@ arguments it contains::
    positional arguments:
     bar          bar help
 
-   optional arguments:
+   options:
     -h, --help   show this help message and exit
     --foo [FOO]  foo help
 
@@ -284,7 +284,7 @@ The default message can be overridden with the ``usage=`` keyword argument::
    positional arguments:
     bar          bar help
 
-   optional arguments:
+   options:
     -h, --help   show this help message and exit
     --foo [FOO]  foo help
 
@@ -307,7 +307,7 @@ various arguments::
 
    A foo that bars
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
 By default, the description will be line-wrapped so that it fits within the
@@ -329,7 +329,7 @@ argument to :class:`ArgumentParser`::
 
    A foo that bars
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
    And that's how you'd foo a bar
@@ -403,7 +403,7 @@ epilog_ texts in command-line help messages::
 
    this description was indented weird but that is okay
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
    likewise for this epilog whose whitespace will be cleaned up and whose words
@@ -432,7 +432,7 @@ should not be line-wrapped::
       exactly the way
       I want it
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
 :class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
@@ -454,7 +454,7 @@ default values to each of the argument help messages::
    positional arguments:
     bar         BAR! (default: [1, 2, 3])
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO   FOO! (default: 42)
 
@@ -473,7 +473,7 @@ as the regular formatter does)::
    positional arguments:
      float
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
      --foo int
 
@@ -592,7 +592,7 @@ older arguments with the same option string.  To get this behavior, the value
    >>> parser.print_help()
    usage: PROG [-h] [-f FOO] [--foo FOO]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     -f FOO      old foo help
     --foo FOO   new foo help
@@ -623,7 +623,7 @@ help will be printed:
    $ python myprogram.py --help
    usage: myprogram.py [-h] [--foo FOO]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO   foo help
 
@@ -636,7 +636,7 @@ This can be achieved by passing ``False`` as the ``add_help=`` argument to
    >>> parser.print_help()
    usage: PROG [--foo FOO]
 
-   optional arguments:
+   options:
     --foo FOO  foo help
 
 The help option is typically ``-h/--help``. The exception to this is
@@ -649,7 +649,7 @@ the help options::
    >>> parser.print_help()
    usage: PROG [+h]
 
-   optional arguments:
+   options:
      +h, ++help  show this help message and exit
 
 
@@ -696,7 +696,7 @@ The add_argument() method
    * const_ - A constant value required by some action_ and nargs_ selections.
 
    * default_ - The value produced if the argument is absent from the
-     command line.
+     command line and if it is absent from the namespace object.
 
    * type_ - The type to which the command-line argument should be converted.
 
@@ -1006,6 +1006,14 @@ was not present at the command line::
    >>> parser.parse_args([])
    Namespace(foo=42)
 
+If the target namespace already has an attribute set, the action *default*
+will not over write it::
+
+   >>> parser = argparse.ArgumentParser()
+   >>> parser.add_argument('--foo', default=42)
+   >>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
+   Namespace(foo=101)
+
 If the ``default`` value is a string, the parser parses the value as if it
 were a command-line argument.  In particular, the parser applies any type_
 conversion argument, if provided, before setting the attribute on the
@@ -1042,63 +1050,70 @@ command-line argument was not present::
 type
 ^^^^
 
-By default, :class:`ArgumentParser` objects read command-line arguments in as simple
+By default, the parser reads command-line arguments in as simple
 strings. However, quite often the command-line string should instead be
-interpreted as another type, like a :class:`float` or :class:`int`.  The
-``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any
-necessary type-checking and type conversions to be performed.  Common built-in
-types and functions can be used directly as the value of the ``type`` argument::
+interpreted as another type, such as a :class:`float` or :class:`int`.  The
+``type`` keyword for :meth:`~ArgumentParser.add_argument` allows any
+necessary type-checking and type conversions to be performed.
 
-   >>> parser = argparse.ArgumentParser()
-   >>> parser.add_argument('foo', type=int)
-   >>> parser.add_argument('bar', type=open)
-   >>> parser.parse_args('2 temp.txt'.split())
-   Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
+If the type_ keyword is used with the default_ keyword, the type converter
+is only applied if the default is a string.
 
-See the section on the default_ keyword argument for information on when the
-``type`` argument is applied to default arguments.
+The argument to ``type`` can be any callable that accepts a single string.
+If the function raises :exc:`ArgumentTypeError`, :exc:`TypeError`, or
+:exc:`ValueError`, the exception is caught and a nicely formatted error
+message is displayed.  No other exception types are handled.
 
-To ease the use of various types of files, the argparse module provides the
-factory FileType which takes the ``mode=``, ``bufsize=``, ``encoding=`` and
-``errors=`` arguments of the :func:`open` function.  For example,
-``FileType('w')`` can be used to create a writable file::
+Common built-in types and functions can be used as type converters:
 
-   >>> parser = argparse.ArgumentParser()
-   >>> parser.add_argument('bar', type=argparse.FileType('w'))
-   >>> parser.parse_args(['out.txt'])
-   Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)
+.. testcode::
 
-``type=`` can take any callable that takes a single string argument and returns
-the converted value::
+   import argparse
+   import pathlib
 
-   >>> def perfect_square(string):
-   ...     value = int(string)
-   ...     sqrt = math.sqrt(value)
-   ...     if sqrt != int(sqrt):
-   ...         msg = "%r is not a perfect square" % string
-   ...         raise argparse.ArgumentTypeError(msg)
-   ...     return value
+   parser = argparse.ArgumentParser()
+   parser.add_argument('count', type=int)
+   parser.add_argument('distance', type=float)
+   parser.add_argument('street', type=ascii)
+   parser.add_argument('code_point', type=ord)
+   parser.add_argument('source_file', type=open)
+   parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
+   parser.add_argument('datapath', type=pathlib.Path)
+
+User defined functions can be used as well:
+
+.. doctest::
+
+   >>> def hyphenated(string):
+   ...     return '-'.join([word[:4] for word in string.casefold().split()])
    ...
-   >>> parser = argparse.ArgumentParser(prog='PROG')
-   >>> parser.add_argument('foo', type=perfect_square)
-   >>> parser.parse_args(['9'])
-   Namespace(foo=9)
-   >>> parser.parse_args(['7'])
-   usage: PROG [-h] foo
-   PROG: error: argument foo: '7' is not a perfect square
+   >>> parser = argparse.ArgumentParser()
+   >>> _ = parser.add_argument('short_title', type=hyphenated)
+   >>> parser.parse_args(['"The Tale of Two Cities"'])
+   Namespace(short_title='"the-tale-of-two-citi')
 
-The choices_ keyword argument may be more convenient for type checkers that
-simply check against a range of values::
+The :func:`bool` function is not recommended as a type converter.  All it does
+is convert empty strings to ``False`` and non-empty strings to ``True``.
+This is usually not what is desired.
 
-   >>> parser = argparse.ArgumentParser(prog='PROG')
-   >>> parser.add_argument('foo', type=int, choices=range(5, 10))
-   >>> parser.parse_args(['7'])
-   Namespace(foo=7)
-   >>> parser.parse_args(['11'])
-   usage: PROG [-h] {5,6,7,8,9}
-   PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
+In general, the ``type`` keyword is a convenience that should only be used for
+simple conversions that can only raise one of the three supported exceptions.
+Anything with more interesting error-handling or resource management should be
+done downstream after the arguments are parsed.
 
-See the choices_ section for more details.
+For example, JSON or YAML conversions have complex error cases that require
+better reporting than can be given by the ``type`` keyword.  An
+:exc:`~json.JSONDecodeError` would not be well formatted and a
+:exc:`FileNotFound` exception would not be handled at all.
+
+Even :class:`~argparse.FileType` has its limitations for use with the ``type``
+keyword.  If one argument uses *FileType* and then a subsequent argument fails,
+an error is reported but the file is not automatically closed.  In this case, it
+would be better to wait until after the parser has run and then use the
+:keyword:`with`-statement to manage the files.
+
+For type checkers that simply check against a fixed set of values, consider
+using the choices_ keyword instead.
 
 
 choices
@@ -1133,20 +1148,14 @@ container should match the type_ specified::
 
 Any container can be passed as the *choices* value, so :class:`list` objects,
 :class:`set` objects, and custom containers are all supported.
-This includes :class:`enum.Enum`, which could be used to restrain
-argument's choices; if we reuse previous rock/paper/scissors game example,
-this could be as follows::
 
-   >>> from enum import Enum
-   >>> class GameMove(Enum):
-   ...     ROCK = 'rock'
-   ...     PAPER = 'paper'
-   ...     SCISSORS = 'scissors'
-   ...
-   >>> parser = argparse.ArgumentParser(prog='game.py')
-   >>> parser.add_argument('move', type=GameMove, choices=GameMove)
-   >>> parser.parse_args(['rock'])
-   Namespace(move=<GameMove.ROCK: 'rock'>)
+Use of :class:`enum.Enum` is not recommended because it is difficult to
+control its appearance in usage, help, and error messages.
+
+Formatted choices overrides the default *metavar* which is normally derived
+from *dest*.  This is usually what you want because the user never sees the
+*dest* parameter.  If this display isn't desirable (perhaps because there are
+many choices), just specify an explicit metavar_.
 
 
 required
@@ -1194,7 +1203,7 @@ argument::
    positional arguments:
     bar     one of the bars to be frobbled
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo   foo the bars before frobbling
 
@@ -1212,7 +1221,7 @@ specifiers include the program name, ``%(prog)s`` and most keyword arguments to
    positional arguments:
     bar     the bar to frobble (default: 42)
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
 As the help string supports %-formatting, if you want a literal ``%`` to appear
@@ -1226,7 +1235,7 @@ setting the ``help`` value to ``argparse.SUPPRESS``::
    >>> parser.print_help()
    usage: frobble [-h]
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
 
 
@@ -1253,7 +1262,7 @@ will be referred to as ``FOO``.  An example::
    positional arguments:
     bar
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO
 
@@ -1270,7 +1279,7 @@ An alternative name can be specified with ``metavar``::
    positional arguments:
     XXX
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo YYY
 
@@ -1288,7 +1297,7 @@ arguments::
    >>> parser.print_help()
    usage: PROG [-h] [-x X X] [--foo bar baz]
 
-   optional arguments:
+   options:
     -h, --help     show this help message and exit
     -x X X
     --foo bar baz
@@ -1692,7 +1701,7 @@ Sub-commands
          a     a help
          b     b help
 
-     optional arguments:
+     options:
        -h, --help  show this help message and exit
        --foo   foo help
 
@@ -1702,13 +1711,13 @@ Sub-commands
      positional arguments:
        bar     bar help
 
-     optional arguments:
+     options:
        -h, --help  show this help message and exit
 
      >>> parser.parse_args(['b', '--help'])
      usage: PROG b [-h] [--baz {X,Y,Z}]
 
-     optional arguments:
+     options:
        -h, --help     show this help message and exit
        --baz {X,Y,Z}  baz help
 
@@ -1725,7 +1734,7 @@ Sub-commands
      >>> parser.parse_args(['-h'])
      usage:  [-h] {foo,bar} ...
 
-     optional arguments:
+     options:
        -h, --help  show this help message and exit
 
      subcommands:

Doc/library/ast.rst

@@ -80,12 +80,13 @@ Node classes
                   end_col_offset
 
       Instances of :class:`ast.expr` and :class:`ast.stmt` subclasses have
-      :attr:`lineno`, :attr:`col_offset`, :attr:`lineno`, and :attr:`col_offset`
-      attributes.  The :attr:`lineno` and :attr:`end_lineno` are the first and
-      last line numbers of source text span (1-indexed so the first line is line 1)
-      and the :attr:`col_offset` and :attr:`end_col_offset` are the corresponding
-      UTF-8 byte offsets of the first and last tokens that generated the node.
-      The UTF-8 offset is recorded because the parser uses UTF-8 internally.
+      :attr:`lineno`, :attr:`col_offset`, :attr:`end_lineno`, and
+      :attr:`end_col_offset` attributes.  The :attr:`lineno` and :attr:`end_lineno`
+      are the first and last line numbers of source text span (1-indexed so the
+      first line is line 1) and the :attr:`col_offset` and :attr:`end_col_offset`
+      are the corresponding UTF-8 byte offsets of the first and last tokens that
+      generated the node. The UTF-8 offset is recorded because the parser uses
+      UTF-8 internally.
 
       Note that the end positions are not required by the compiler and are
       therefore optional. The end offset is *after* the last symbol, for example
@@ -1575,7 +1576,7 @@ and classes for traversing abstract syntax trees:
    Safely evaluate an expression node or a string containing a Python literal or
    container display.  The string or node provided may only consist of the
    following Python literal structures: strings, bytes, numbers, tuples, lists,
-   dicts, sets, booleans, and ``None``.
+   dicts, sets, booleans, ``None`` and ``Ellipsis``.
 
    This can be used for safely evaluating strings containing Python values from
    untrusted sources without the need to parse the values oneself.  It is not
@@ -1587,6 +1588,10 @@ and classes for traversing abstract syntax trees:
       sufficiently large/complex string due to stack depth limitations
       in Python's AST compiler.
 
+      It can raise :exc:`ValueError`, :exc:`TypeError`, :exc:`SyntaxError`,
+      :exc:`MemoryError` and :exc:`RecursionError` depending on the malformed
+      input.
+
    .. versionchanged:: 3.2
       Now allows bytes and set literals.
 

Doc/library/asyncio-eventloop.rst

@@ -321,7 +321,7 @@ Creating Futures and Tasks
 
    .. versionadded:: 3.5.2
 
-.. method:: loop.create_task(coro, \*, name=None)
+.. method:: loop.create_task(coro, *, name=None)
 
    Schedule the execution of a :ref:`coroutine`.
    Return a :class:`Task` object.
@@ -356,7 +356,7 @@ Opening network connections
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. coroutinemethod:: loop.create_connection(protocol_factory, \
-                          host=None, port=None, \*, ssl=None, \
+                          host=None, port=None, *, ssl=None, \
                           family=0, proto=0, flags=0, sock=None, \
                           local_addr=None, server_hostname=None, \
                           ssl_handshake_timeout=None, \
@@ -482,7 +482,7 @@ Opening network connections
       that can be used directly in async/await code.
 
 .. coroutinemethod:: loop.create_datagram_endpoint(protocol_factory, \
-                        local_addr=None, remote_addr=None, \*, \
+                        local_addr=None, remote_addr=None, *, \
                         family=0, proto=0, flags=0, \
                         reuse_address=None, reuse_port=None, \
                         allow_broadcast=None, sock=None)
@@ -559,7 +559,7 @@ Opening network connections
       Added support for Windows.
 
 .. coroutinemethod:: loop.create_unix_connection(protocol_factory, \
-                        path=None, \*, ssl=None, sock=None, \
+                        path=None, *, ssl=None, sock=None, \
                         server_hostname=None, ssl_handshake_timeout=None)
 
    Create a Unix connection.
@@ -592,7 +592,7 @@ Creating network servers
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. coroutinemethod:: loop.create_server(protocol_factory, \
-                        host=None, port=None, \*, \
+                        host=None, port=None, *, \
                         family=socket.AF_UNSPEC, \
                         flags=socket.AI_PASSIVE, \
                         sock=None, backlog=100, ssl=None, \
@@ -683,7 +683,7 @@ Creating network servers
 
 
 .. coroutinemethod:: loop.create_unix_server(protocol_factory, path=None, \
-                          \*, sock=None, backlog=100, ssl=None, \
+                          *, sock=None, backlog=100, ssl=None, \
                           ssl_handshake_timeout=None, start_serving=True)
 
    Similar to :meth:`loop.create_server` but works with the
@@ -708,7 +708,7 @@ Creating network servers
       The *path* parameter can now be a :class:`~pathlib.Path` object.
 
 .. coroutinemethod:: loop.connect_accepted_socket(protocol_factory, \
-                        sock, \*, ssl=None, ssl_handshake_timeout=None)
+                        sock, *, ssl=None, ssl_handshake_timeout=None)
 
    Wrap an already accepted connection into a transport/protocol pair.
 
@@ -773,7 +773,7 @@ TLS Upgrade
 ^^^^^^^^^^^
 
 .. coroutinemethod:: loop.start_tls(transport, protocol, \
-                        sslcontext, \*, server_side=False, \
+                        sslcontext, *, server_side=False, \
                         server_hostname=None, ssl_handshake_timeout=None)
 
    Upgrade an existing transport-based connection to TLS.
@@ -806,7 +806,7 @@ TLS Upgrade
 Watching file descriptors
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. method:: loop.add_reader(fd, callback, \*args)
+.. method:: loop.add_reader(fd, callback, *args)
 
    Start monitoring the *fd* file descriptor for read availability and
    invoke *callback* with the specified arguments once *fd* is available for
@@ -816,7 +816,7 @@ Watching file descriptors
 
    Stop monitoring the *fd* file descriptor for read availability.
 
-.. method:: loop.add_writer(fd, callback, \*args)
+.. method:: loop.add_writer(fd, callback, *args)
 
    Start monitoring the *fd* file descriptor for write availability and
    invoke *callback* with the specified arguments once *fd* is available for
@@ -930,7 +930,7 @@ convenient.
       :meth:`loop.create_server` and :func:`start_server`.
 
 .. coroutinemethod:: loop.sock_sendfile(sock, file, offset=0, count=None, \
-                                        \*, fallback=True)
+                                        *, fallback=True)
 
    Send a file using high-performance :mod:`os.sendfile` if possible.
    Return the total number of bytes sent.
@@ -964,7 +964,7 @@ convenient.
 DNS
 ^^^
 
-.. coroutinemethod:: loop.getaddrinfo(host, port, \*, family=0, \
+.. coroutinemethod:: loop.getaddrinfo(host, port, *, family=0, \
                         type=0, proto=0, flags=0)
 
    Asynchronous version of :meth:`socket.getaddrinfo`.
@@ -1029,7 +1029,7 @@ Working with pipes
 Unix signals
 ^^^^^^^^^^^^
 
-.. method:: loop.add_signal_handler(signum, callback, \*args)
+.. method:: loop.add_signal_handler(signum, callback, *args)
 
    Set *callback* as the handler for the *signum* signal.
 
@@ -1064,7 +1064,7 @@ Unix signals
 Executing code in thread or process pools
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. awaitablemethod:: loop.run_in_executor(executor, func, \*args)
+.. awaitablemethod:: loop.run_in_executor(executor, func, *args)
 
    Arrange for *func* to be called in the specified executor.
 
@@ -1184,10 +1184,13 @@ Allows customizing how exceptions are handled in the event loop.
    * 'message': Error message;
    * 'exception' (optional): Exception object;
    * 'future' (optional): :class:`asyncio.Future` instance;
+   * 'task' (optional): :class:`asyncio.Task` instance;
    * 'handle' (optional): :class:`asyncio.Handle` instance;
    * 'protocol' (optional): :ref:`Protocol <asyncio-protocol>` instance;
    * 'transport' (optional): :ref:`Transport <asyncio-transport>` instance;
-   * 'socket' (optional): :class:`socket.socket` instance.
+   * 'socket' (optional): :class:`socket.socket` instance;
+   * 'asyncgen' (optional): Asynchronous generator that caused
+                            the exception.
 
    .. note::
 
@@ -1234,9 +1237,9 @@ async/await code consider using the high-level
    subprocesses. See :ref:`Subprocess Support on Windows
    <asyncio-windows-subprocess>` for details.
 
-.. coroutinemethod:: loop.subprocess_exec(protocol_factory, \*args, \
+.. coroutinemethod:: loop.subprocess_exec(protocol_factory, *args, \
                       stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
-                      stderr=subprocess.PIPE, \*\*kwargs)
+                      stderr=subprocess.PIPE, **kwargs)
 
    Create a subprocess from one or more string arguments specified by
    *args*.
@@ -1316,9 +1319,9 @@ async/await code consider using the high-level
    conforms to the :class:`asyncio.SubprocessTransport` base class and
    *protocol* is an object instantiated by the *protocol_factory*.
 
-.. coroutinemethod:: loop.subprocess_shell(protocol_factory, cmd, \*, \
+.. coroutinemethod:: loop.subprocess_shell(protocol_factory, cmd, *, \
                         stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
-                        stderr=subprocess.PIPE, \*\*kwargs)
+                        stderr=subprocess.PIPE, **kwargs)
 
    Create a subprocess from *cmd*, which can be a :class:`str` or a
    :class:`bytes` string encoded to the

Doc/library/asyncio-future.rst

@@ -31,7 +31,7 @@ Future Functions
    .. versionadded:: 3.5
 
 
-.. function:: ensure_future(obj, \*, loop=None)
+.. function:: ensure_future(obj, *, loop=None)
 
    Return:
 
@@ -58,7 +58,7 @@ Future Functions
       The function accepts any :term:`awaitable` object.
 
 
-.. function:: wrap_future(future, \*, loop=None)
+.. function:: wrap_future(future, *, loop=None)
 
    Wrap a :class:`concurrent.futures.Future` object in a
    :class:`asyncio.Future` object.
@@ -67,7 +67,7 @@ Future Functions
 Future Object
 =============
 
-.. class:: Future(\*, loop=None)
+.. class:: Future(*, loop=None)
 
    A Future represents an eventual result of an asynchronous
    operation.  Not thread-safe.

Doc/library/asyncio-policy.rst

@@ -159,7 +159,7 @@ implementation used by the asyncio event loop:
 
 .. class:: AbstractChildWatcher
 
-   .. method:: add_child_handler(pid, callback, \*args)
+   .. method:: add_child_handler(pid, callback, *args)
 
       Register a new child handler.
 
@@ -209,7 +209,7 @@ implementation used by the asyncio event loop:
    It works reliably even when the asyncio event loop is run in a non-main OS thread.
 
    There is no noticeable overhead when handling a big number of children (*O(1)* each
-   time a child terminates), but stating a thread per process requires extra memory.
+   time a child terminates), but starting a thread per process requires extra memory.
 
    This watcher is used by default.
 

Doc/library/asyncio-queue.rst

@@ -23,7 +23,7 @@ See also the `Examples`_ section below.
 Queue
 =====
 
-.. class:: Queue(maxsize=0, \*, loop=None)
+.. class:: Queue(maxsize=0)
 
    A first in, first out (FIFO) queue.
 
@@ -36,9 +36,6 @@ Queue
    the queue is always known and can be returned by calling the
    :meth:`qsize` method.
 
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
 
    This class is :ref:`not thread safe <asyncio-multithreading>`.
 

Doc/library/asyncio-stream.rst

@@ -48,9 +48,9 @@ The following top-level asyncio functions can be used to create
 and work with streams:
 
 
-.. coroutinefunction:: open_connection(host=None, port=None, \*, \
-                          loop=None, limit=None, ssl=None, family=0, \
-                          proto=0, flags=0, sock=None, local_addr=None, \
+.. coroutinefunction:: open_connection(host=None, port=None, *, \
+                          limit=None, ssl=None, family=0, proto=0, \
+                          flags=0, sock=None, local_addr=None, \
                           server_hostname=None, ssl_handshake_timeout=None)
 
    Establish a network connection and return a pair of
@@ -59,9 +59,6 @@ and work with streams:
    The returned *reader* and *writer* objects are instances of
    :class:`StreamReader` and :class:`StreamWriter` classes.
 
-   The *loop* argument is optional and can always be determined
-   automatically when this function is awaited from a coroutine.
-
    *limit* determines the buffer size limit used by the
    returned :class:`StreamReader` instance.  By default the *limit*
    is set to 64 KiB.
@@ -74,7 +71,7 @@ and work with streams:
       The *ssl_handshake_timeout* parameter.
 
 .. coroutinefunction:: start_server(client_connected_cb, host=None, \
-                          port=None, \*, loop=None, limit=None, \
+                          port=None, *, limit=None, \
                           family=socket.AF_UNSPEC, \
                           flags=socket.AI_PASSIVE, sock=None, \
                           backlog=100, ssl=None, reuse_address=None, \
@@ -92,9 +89,6 @@ and work with streams:
    :ref:`coroutine function <coroutine>`; if it is a coroutine function,
    it will be automatically scheduled as a :class:`Task`.
 
-   The *loop* argument is optional and can always be determined
-   automatically when this method is awaited from a coroutine.
-
    *limit* determines the buffer size limit used by the
    returned :class:`StreamReader` instance.  By default the *limit*
    is set to 64 KiB.
@@ -109,9 +103,9 @@ and work with streams:
 
 .. rubric:: Unix Sockets
 
-.. coroutinefunction:: open_unix_connection(path=None, \*, loop=None, \
-                        limit=None, ssl=None, sock=None, \
-                        server_hostname=None, ssl_handshake_timeout=None)
+.. coroutinefunction:: open_unix_connection(path=None, *, limit=None, \
+                        ssl=None, sock=None, server_hostname=None, \
+                        ssl_handshake_timeout=None)
 
    Establish a Unix socket connection and return a pair of
    ``(reader, writer)``.
@@ -132,9 +126,8 @@ and work with streams:
 
 
 .. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \
-                          \*, loop=None, limit=None, sock=None, \
-                          backlog=100, ssl=None, ssl_handshake_timeout=None, \
-                          start_serving=True)
+                          *, limit=None, sock=None, backlog=100, ssl=None, \
+                          ssl_handshake_timeout=None, start_serving=True)
 
    Start a Unix socket server.
 
@@ -192,7 +185,7 @@ StreamReader
       can be read.  Use the :attr:`IncompleteReadError.partial`
       attribute to get the partially read data.
 
-   .. coroutinemethod:: readuntil(separator=b'\\n')
+   .. coroutinemethod:: readuntil(separator=b'\n')
 
       Read data from the stream until *separator* is found.
 

Doc/library/asyncio-subprocess.rst

@@ -61,9 +61,8 @@ See also the `Examples`_ subsection.
 Creating Subprocesses
 =====================
 
-.. coroutinefunction:: create_subprocess_exec(program, \*args, stdin=None, \
-                          stdout=None, stderr=None, loop=None, \
-                          limit=None, \*\*kwds)
+.. coroutinefunction:: create_subprocess_exec(program, *args, stdin=None, \
+                          stdout=None, stderr=None, limit=None, **kwds)
 
    Create a subprocess.
 
@@ -76,13 +75,9 @@ Creating Subprocesses
    See the documentation of :meth:`loop.subprocess_exec` for other
    parameters.
 
-   .. deprecated-removed:: 3.8 3.10
-
-      The *loop* parameter.
 
 .. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, \
-                          stdout=None, stderr=None, loop=None, \
-                          limit=None, \*\*kwds)
+                          stdout=None, stderr=None, limit=None, **kwds)
 
    Run the *cmd* shell command.
 
@@ -104,10 +99,6 @@ Creating Subprocesses
       escape whitespace and special shell characters in strings that are going
       to be used to construct shell commands.
 
-   .. deprecated-removed:: 3.8 3.10
-
-      The *loop* parameter.
-
 .. note::
 
    Subprocesses are available for Windows if a :class:`ProactorEventLoop` is

Doc/library/asyncio-sync.rst

@@ -36,7 +36,7 @@ asyncio has the following basic synchronization primitives:
 Lock
 ====
 
-.. class:: Lock(\*, loop=None)
+.. class:: Lock()
 
    Implements a mutex lock for asyncio tasks.  Not thread-safe.
 
@@ -63,9 +63,6 @@ Lock
        finally:
            lock.release()
 
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
    .. coroutinemethod:: acquire()
 
       Acquire the lock.
@@ -96,7 +93,7 @@ Lock
 Event
 =====
 
-.. class:: Event(\*, loop=None)
+.. class:: Event()
 
    An event object.  Not thread-safe.
 
@@ -104,14 +101,10 @@ Event
    that some event has happened.
 
    An Event object manages an internal flag that can be set to *true*
-   with the :meth:`set` method and reset to *false* with the
-   :meth:`clear` method.  The :meth:`wait` method blocks until the
+   with the :meth:`~Event.set` method and reset to *false* with the
+   :meth:`clear` method.  The :meth:`~Event.wait` method blocks until the
    flag is set to *true*.  The flag is set to *false* initially.
 
-
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
    .. _asyncio_example_sync_event:
 
    Example::
@@ -142,7 +135,7 @@ Event
       Wait until the event is set.
 
       If the event is set, return ``True`` immediately.
-      Otherwise block until another task calls :meth:`set`.
+      Otherwise block until another task calls :meth:`~Event.set`.
 
    .. method:: set()
 
@@ -155,8 +148,8 @@ Event
 
       Clear (unset) the event.
 
-      Tasks awaiting on :meth:`wait` will now block until the
-      :meth:`set` method is called again.
+      Tasks awaiting on :meth:`~Event.wait` will now block until the
+      :meth:`~Event.set` method is called again.
 
    .. method:: is_set()
 
@@ -166,7 +159,7 @@ Event
 Condition
 =========
 
-.. class:: Condition(lock=None, \*, loop=None)
+.. class:: Condition(lock=None)
 
    A Condition object.  Not thread-safe.
 
@@ -184,10 +177,6 @@ Condition
    ``None``.  In the latter case a new Lock object is created
    automatically.
 
-
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
    The preferred way to use a Condition is an :keyword:`async with`
    statement::
 
@@ -270,7 +259,7 @@ Condition
 Semaphore
 =========
 
-.. class:: Semaphore(value=1, \*, loop=None)
+.. class:: Semaphore(value=1)
 
    A Semaphore object.  Not thread-safe.
 
@@ -284,10 +273,6 @@ Semaphore
    internal counter (``1`` by default). If the given value is
    less than ``0`` a :exc:`ValueError` is raised.
 
-
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
    The preferred way to use a Semaphore is an :keyword:`async with`
    statement::
 
@@ -332,7 +317,7 @@ Semaphore
 BoundedSemaphore
 ================
 
-.. class:: BoundedSemaphore(value=1, \*, loop=None)
+.. class:: BoundedSemaphore(value=1)
 
    A bounded semaphore object.  Not thread-safe.
 
@@ -340,10 +325,6 @@ BoundedSemaphore
    a :exc:`ValueError` in :meth:`~Semaphore.release` if it
    increases the internal counter above the initial *value*.
 
-
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
 ---------
 
 

Doc/library/asyncio-task.rst

@@ -210,7 +210,7 @@ is :meth:`loop.run_in_executor`.
 Running an asyncio Program
 ==========================
 
-.. function:: run(coro, \*, debug=False)
+.. function:: run(coro, *, debug=False)
 
     Execute the :term:`coroutine` *coro* and return the result.
 
@@ -247,7 +247,7 @@ Running an asyncio Program
 Creating Tasks
 ==============
 
-.. function:: create_task(coro, \*, name=None)
+.. function:: create_task(coro, *, name=None)
 
    Wrap the *coro* :ref:`coroutine <coroutine>` into a :class:`Task`
    and schedule its execution.  Return the Task object.
@@ -283,7 +283,7 @@ Creating Tasks
 Sleeping
 ========
 
-.. coroutinefunction:: sleep(delay, result=None, \*, loop=None)
+.. coroutinefunction:: sleep(delay, result=None)
 
    Block for *delay* seconds.
 
@@ -293,9 +293,6 @@ Sleeping
    ``sleep()`` always suspends the current task, allowing other tasks
    to run.
 
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
    .. _asyncio_example_sleep:
 
    Example of coroutine displaying the current date every second
@@ -319,7 +316,7 @@ Sleeping
 Running Tasks Concurrently
 ==========================
 
-.. awaitablefunction:: gather(\*aws, loop=None, return_exceptions=False)
+.. awaitablefunction:: gather(*aws, return_exceptions=False)
 
    Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
    sequence *concurrently*.
@@ -348,9 +345,6 @@ Running Tasks Concurrently
    cancellation of one submitted Task/Future to cause other
    Tasks/Futures to be cancelled.
 
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
    .. _asyncio_example_gather:
 
    Example::
@@ -403,7 +397,7 @@ Running Tasks Concurrently
 Shielding From Cancellation
 ===========================
 
-.. awaitablefunction:: shield(aw, \*, loop=None)
+.. awaitablefunction:: shield(aw)
 
    Protect an :ref:`awaitable object <asyncio-awaitables>`
    from being :meth:`cancelled <Task.cancel>`.
@@ -436,14 +430,11 @@ Shielding From Cancellation
        except CancelledError:
            res = None
 
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
 
 Timeouts
 ========
 
-.. coroutinefunction:: wait_for(aw, timeout, \*, loop=None)
+.. coroutinefunction:: wait_for(aw, timeout)
 
    Wait for the *aw* :ref:`awaitable <asyncio-awaitables>`
    to complete with a timeout.
@@ -466,9 +457,6 @@ Timeouts
 
    If the wait is cancelled, the future *aw* is also cancelled.
 
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
    .. _asyncio_example_waitfor:
 
    Example::
@@ -500,8 +488,7 @@ Timeouts
 Waiting Primitives
 ==================
 
-.. coroutinefunction:: wait(aws, \*, loop=None, timeout=None,\
-                            return_when=ALL_COMPLETED)
+.. coroutinefunction:: wait(aws, *, timeout=None, return_when=ALL_COMPLETED)
 
    Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
    iterable concurrently and block until the condition specified
@@ -553,10 +540,6 @@ Waiting Primitives
       ``wait()`` directly is deprecated as it leads to
       :ref:`confusing behavior <asyncio_example_wait_coroutine>`.
 
-   .. deprecated-removed:: 3.8 3.10
-
-      The *loop* parameter.
-
    .. _asyncio_example_wait_coroutine:
    .. note::
 
@@ -590,7 +573,7 @@ Waiting Primitives
       deprecated.
 
 
-.. function:: as_completed(aws, \*, loop=None, timeout=None)
+.. function:: as_completed(aws, *, timeout=None)
 
    Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
    iterable concurrently.  Return an iterator of coroutines.
@@ -600,9 +583,6 @@ Waiting Primitives
    Raises :exc:`asyncio.TimeoutError` if the timeout occurs before
    all Futures are done.
 
-   .. deprecated-removed:: 3.8 3.10
-      The *loop* parameter.
-
    Example::
 
        for coro in as_completed(aws):
@@ -613,12 +593,12 @@ Waiting Primitives
 Running in Threads
 ==================
 
-.. coroutinefunction:: to_thread(func, /, \*args, \*\*kwargs)
+.. coroutinefunction:: to_thread(func, /, *args, **kwargs)
 
    Asynchronously run function *func* in a separate thread.
 
    Any \*args and \*\*kwargs supplied for this function are directly passed
-   to *func*. Also, the current :class:`contextvars.Context` is propogated,
+   to *func*. Also, the current :class:`contextvars.Context` is propagated,
    allowing context variables from the event loop thread to be accessed in the
    separate thread.
 
@@ -743,7 +723,7 @@ Introspection
 Task Object
 ===========
 
-.. class:: Task(coro, \*, loop=None, name=None)
+.. class:: Task(coro, *, loop=None, name=None)
 
    A :class:`Future-like <Future>` object that runs a Python
    :ref:`coroutine <coroutine>`.  Not thread-safe.
@@ -909,7 +889,7 @@ Task Object
       See the documentation of :meth:`Future.remove_done_callback`
       for more details.
 
-   .. method:: get_stack(\*, limit=None)
+   .. method:: get_stack(*, limit=None)
 
       Return the list of stack frames for this Task.
 
@@ -930,7 +910,7 @@ Task Object
       stack are returned, but the oldest frames of a traceback are
       returned.  (This matches the behavior of the traceback module.)
 
-   .. method:: print_stack(\*, limit=None, file=None)
+   .. method:: print_stack(*, limit=None, file=None)
 
       Print the stack or traceback for this Task.
 

Doc/library/base64.rst

@@ -199,7 +199,7 @@ The modern interface provides:
    .. versionadded:: 3.4
 
 
-.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \\t\\n\\r\\v')
+.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\v')
 
    Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and
    return the decoded :class:`bytes`.

Doc/library/bz2.rst

@@ -266,7 +266,6 @@ Below are some examples of typical usage of the :mod:`bz2` module.
 Using :func:`compress` and :func:`decompress` to demonstrate round-trip compression:
 
     >>> import bz2
-
     >>> data = b"""\
     ... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
     ... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
@@ -275,11 +274,9 @@ Using :func:`compress` and :func:`decompress` to demonstrate round-trip compress
     ... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
     ... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
     ... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
-
     >>> c = bz2.compress(data)
     >>> len(data) / len(c)  # Data compression ratio
     1.513595166163142
-
     >>> d = bz2.decompress(c)
     >>> data == d  # Check equality to original object after round-trip
     True
@@ -287,7 +284,6 @@ Using :func:`compress` and :func:`decompress` to demonstrate round-trip compress
 Using :class:`BZ2Compressor` for incremental compression:
 
     >>> import bz2
-
     >>> def gen_data(chunks=10, chunksize=1000):
     ...     """Yield incremental blocks of chunksize bytes."""
     ...     for _ in range(chunks):
@@ -310,7 +306,6 @@ while ordered, repetitive data usually yields a high compression ratio.
 Writing and reading a bzip2-compressed file in binary mode:
 
     >>> import bz2
-
     >>> data = b"""\
     ... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
     ... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
@@ -319,14 +314,11 @@ Writing and reading a bzip2-compressed file in binary mode:
     ... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
     ... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
     ... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
-
     >>> with bz2.open("myfile.bz2", "wb") as f:
     ...     # Write compressed data to file
     ...     unused = f.write(data)
-
     >>> with bz2.open("myfile.bz2", "rb") as f:
     ...     # Decompress data from file
     ...     content = f.read()
-
     >>> content == data  # Check equality to original object after round-trip
     True

Doc/library/collections.abc.rst

@@ -291,7 +291,7 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
    :meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
    If the :class:`Set` mixin is being used in a class with a different
    constructor signature, you will need to override :meth:`_from_iterable`
-   with a classmethod that can construct new instances from
+   with a classmethod or regular method that can construct new instances from
    an iterable argument.
 
 (2)

Doc/library/collections.rst

@@ -862,6 +862,9 @@ they add the ability to access fields by name instead of position index.
     Named tuple instances do not have per-instance dictionaries, so they are
     lightweight and require no more memory than regular tuples.
 
+    To support pickling, the named tuple class should be assigned to a variable
+    that matches *typename*.
+
     .. versionchanged:: 3.1
        Added support for *rename*.
 

Doc/library/compileall.rst

@@ -148,7 +148,7 @@ runtime.
 Public functions
 ----------------
 
-.. function:: compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, \*, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
+.. function:: compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
 
    Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
    files along the way. Return a true value if all the files compiled successfully,
@@ -231,7 +231,7 @@ Public functions
       Added *stripdir*, *prependdir*, *limit_sl_dest* and *hardlink_dupes* arguments.
       Default value of *maxlevels* was changed from ``10`` to ``sys.getrecursionlimit()``
 
-.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, \*, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
+.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
 
    Compile the file with path *fullname*. Return a true value if the file
    compiled successfully, and a false value otherwise.

Doc/library/concurrent.futures.rst

@@ -67,7 +67,7 @@ Executor Objects
        .. versionchanged:: 3.5
           Added the *chunksize* argument.
 
-    .. method:: shutdown(wait=True, \*, cancel_futures=False)
+    .. method:: shutdown(wait=True, *, cancel_futures=False)
 
        Signal the executor that it should free any resources that it is using
        when the currently pending futures are done executing.  Calls to
@@ -236,9 +236,9 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
    An :class:`Executor` subclass that executes calls asynchronously using a pool
    of at most *max_workers* processes.  If *max_workers* is ``None`` or not
    given, it will default to the number of processors on the machine.
-   If *max_workers* is lower or equal to ``0``, then a :exc:`ValueError`
+   If *max_workers* is less than or equal to ``0``, then a :exc:`ValueError`
    will be raised.
-   On Windows, *max_workers* must be equal or lower than ``61``. If it is not
+   On Windows, *max_workers* must be less than or equal to ``61``. If it is not
    then :exc:`ValueError` will be raised. If *max_workers* is ``None``, then
    the default chosen will be at most ``61``, even if more processors are
    available.
@@ -250,7 +250,7 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
    each worker process; *initargs* is a tuple of arguments passed to the
    initializer.  Should *initializer* raise an exception, all currently
    pending jobs will raise a :exc:`~concurrent.futures.process.BrokenProcessPool`,
-   as well any attempt to submit more jobs to the pool.
+   as well as any attempt to submit more jobs to the pool.
 
    .. versionchanged:: 3.3
       When one of the worker processes terminates abruptly, a

Doc/library/contextlib.rst

@@ -126,6 +126,31 @@ Functions and classes provided:
 
    .. versionadded:: 3.7
 
+   Context managers defined with :func:`asynccontextmanager` can be used
+   either as decorators or with :keyword:`async with` statements::
+
+     import time
+
+     async def timeit():
+         now = time.monotonic()
+         try:
+             yield
+         finally:
+             print(f'it took {time.monotonic() - now}s to run')
+
+      @timeit()
+      async def main():
+          # ... async code ...
+
+   When used as a decorator, a new generator instance is implicitly created on
+   each function call. This allows the otherwise "one-shot" context managers
+   created by :func:`asynccontextmanager` to meet the requirement that context
+   managers support multiple invocations in order to be used as decorators.
+
+  .. versionchanged:: 3.10
+     Async context managers created with :func:`asynccontextmanager` can
+     be used as decorators.
+
 
 .. function:: closing(thing)
 
@@ -218,8 +243,26 @@ Functions and classes provided:
           with cm as file:
               # Perform processing on the file
 
+   It can also be used as a stand-in for
+   :ref:`asynchronous context managers <async-context-managers>`::
+
+       async def send_http(session=None):
+          if not session:
+              # If no http session, create it with aiohttp
+              cm = aiohttp.ClientSession()
+          else:
+              # Caller is responsible for closing the session
+              cm = nullcontext(session)
+
+          async with cm as session:
+              # Send http requests with session
+
    .. versionadded:: 3.7
 
+   .. versionchanged:: 3.10
+      :term:`asynchronous context manager` support was added.
+
+
 
 .. function:: suppress(*exceptions)
 
@@ -384,6 +427,45 @@ Functions and classes provided:
    .. versionadded:: 3.2
 
 
+.. class:: AsyncContextDecorator
+
+   Similar to :class:`ContextDecorator` but only for asynchronous functions.
+
+   Example of ``AsyncContextDecorator``::
+
+      from asyncio import run
+      from contextlib import AsyncContextDecorator
+
+      class mycontext(AsyncContextDecorator):
+          async def __aenter__(self):
+              print('Starting')
+              return self
+
+          async def __aexit__(self, *exc):
+              print('Finishing')
+              return False
+
+      >>> @mycontext()
+      ... async def function():
+      ...     print('The bit in the middle')
+      ...
+      >>> run(function())
+      Starting
+      The bit in the middle
+      Finishing
+
+      >>> async def function():
+      ...    async with mycontext():
+      ...         print('The bit in the middle')
+      ...
+      >>> run(function())
+      Starting
+      The bit in the middle
+      Finishing
+
+   .. versionadded:: 3.10
+
+
 .. class:: ExitStack()
 
    A context manager that is designed to make it easy to programmatically

Doc/library/contextvars.rst

@@ -26,7 +26,7 @@ See also :pep:`567` for additional details.
 Context Variables
 -----------------
 
-.. class:: ContextVar(name, [\*, default])
+.. class:: ContextVar(name, [*, default])
 
    This class is used to declare a new Context Variable, e.g.::
 
@@ -146,7 +146,7 @@ Manual Context Management
 
    Context implements the :class:`collections.abc.Mapping` interface.
 
-   .. method:: run(callable, \*args, \*\*kwargs)
+   .. method:: run(callable, *args, **kwargs)
 
       Execute ``callable(*args, **kwargs)`` code in the context object
       the *run* method is called on.  Return the result of the execution

Doc/library/ctypes.rst

@@ -2508,7 +2508,7 @@ other data types containing pointer type fields.
 Arrays and pointers
 ^^^^^^^^^^^^^^^^^^^
 
-.. class:: Array(\*args)
+.. class:: Array(*args)
 
    Abstract base class for arrays.
 

Doc/library/datetime.rst

@@ -1219,7 +1219,7 @@ Instance methods:
 
 .. method:: datetime.replace(year=self.year, month=self.month, day=self.day, \
    hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, \
-   tzinfo=self.tzinfo, * fold=0)
+   tzinfo=self.tzinfo, *, fold=0)
 
    Return a datetime with the same attributes, except for those attributes given
    new values by whichever keyword arguments are specified. Note that
@@ -1783,7 +1783,7 @@ Other constructor:
 Instance methods:
 
 .. method:: time.replace(hour=self.hour, minute=self.minute, second=self.second, \
-   microsecond=self.microsecond, tzinfo=self.tzinfo, * fold=0)
+   microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)
 
    Return a :class:`.time` with the same value, except for those attributes given
    new values by whichever keyword arguments are specified. Note that

Doc/library/dialog.rst

@@ -198,7 +198,7 @@ These do not emulate the native look-and-feel of the platform.
    A subclass of FileDialog that creates a dialog window for selecting a
    destination file.
 
-    .. method:: ok_command()
+   .. method:: ok_command()
 
       Test whether or not the selection points to a valid file that is not a
       directory. Confirmation is required if an already existing file is

Doc/library/difflib.rst

@@ -149,7 +149,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
    contains a good example of its use.
 
 
-.. function:: context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\\n')
+.. function:: context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')
 
    Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
    generating the delta lines) in context diff format.
@@ -279,7 +279,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
       emu
 
 
-.. function:: unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\\n')
+.. function:: unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')
 
    Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
    generating the delta lines) in unified diff format.
@@ -321,7 +321,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
 
    See :ref:`difflib-interface` for a more detailed example.
 
-.. function:: diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\\n')
+.. function:: diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\n')
 
    Compare *a* and *b* (lists of bytes objects) using *dfunc*; yield a
    sequence of delta lines (also bytes) in the format returned by *dfunc*.

Doc/library/dis.rst

@@ -708,7 +708,8 @@ iterations of the loop.
 
 .. opcode:: RERAISE
 
-    Re-raises the exception currently on top of the stack.
+    Re-raises the exception currently on top of the stack. If oparg is non-zero,
+    restores ``f_lasti`` of the current frame to its value when the exception was raised.
 
     .. versionadded:: 3.9
 
@@ -861,7 +862,7 @@ All of the following opcodes use their arguments.
 
 .. opcode:: LIST_TO_TUPLE
 
-    Pops a list from the stack and pushes a tuple containing the same values.
+   Pops a list from the stack and pushes a tuple containing the same values.
 
    .. versionadded:: 3.9
 
@@ -889,7 +890,7 @@ All of the following opcodes use their arguments.
 
 .. opcode:: DICT_MERGE
 
-    Like :opcode:`DICT_UPDATE` but raises an exception for duplicate keys.
+   Like :opcode:`DICT_UPDATE` but raises an exception for duplicate keys.
 
    .. versionadded:: 3.9
 
@@ -907,14 +908,14 @@ All of the following opcodes use their arguments.
 
 .. opcode:: IS_OP (invert)
 
-    Performs ``is`` comparison, or ``is not`` if ``invert`` is 1.
+   Performs ``is`` comparison, or ``is not`` if ``invert`` is 1.
 
    .. versionadded:: 3.9
 
 
 .. opcode:: CONTAINS_OP (invert)
 
-    Performs ``in`` comparison, or ``not in`` if ``invert`` is 1.
+   Performs ``in`` comparison, or ``not in`` if ``invert`` is 1.
 
    .. versionadded:: 3.9
 
@@ -955,8 +956,8 @@ All of the following opcodes use their arguments.
 
 .. opcode:: JUMP_IF_NOT_EXC_MATCH (target)
 
-    Tests whether the second value on the stack is an exception matching TOS,
-    and jumps if it is not. Pops two values from the stack.
+   Tests whether the second value on the stack is an exception matching TOS,
+   and jumps if it is not. Pops two values from the stack.
 
    .. versionadded:: 3.9
 
@@ -1144,11 +1145,13 @@ All of the following opcodes use their arguments.
    * ``0x01`` a tuple of default values for positional-only and
      positional-or-keyword parameters in positional order
    * ``0x02`` a dictionary of keyword-only parameters' default values
-   * ``0x04`` an annotation dictionary
+   * ``0x04`` a tuple of strings containing parameters' annotations
    * ``0x08`` a tuple containing cells for free variables, making a closure
    * the code associated with the function (at TOS1)
    * the :term:`qualified name` of the function (at TOS)
 
+   .. versionchanged:: 3.10
+      Flag value ``0x04`` is a tuple of strings instead of dictionary
 
 .. opcode:: BUILD_SLICE (argc)
 

Doc/library/doctest.rst

@@ -719,36 +719,51 @@ above.
 An example's doctest directives modify doctest's behavior for that single
 example.  Use ``+`` to enable the named behavior, or ``-`` to disable it.
 
-For example, this test passes::
+For example, this test passes:
 
-   >>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
+.. doctest::
+   :no-trim-doctest-flags:
+
+   >>> print(list(range(20)))  # doctest: +NORMALIZE_WHITESPACE
    [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
    10,  11, 12, 13, 14, 15, 16, 17, 18, 19]
 
 Without the directive it would fail, both because the actual output doesn't have
 two blanks before the single-digit list elements, and because the actual output
 is on a single line.  This test also passes, and also requires a directive to do
-so::
+so:
 
-   >>> print(list(range(20))) # doctest: +ELLIPSIS
+.. doctest::
+   :no-trim-doctest-flags:
+
+   >>> print(list(range(20)))  # doctest: +ELLIPSIS
    [0, 1, ..., 18, 19]
 
 Multiple directives can be used on a single physical line, separated by
-commas::
+commas:
 
-   >>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+.. doctest::
+   :no-trim-doctest-flags:
+
+   >>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
    [0,    1, ...,   18,    19]
 
 If multiple directive comments are used for a single example, then they are
-combined::
+combined:
 
-   >>> print(list(range(20))) # doctest: +ELLIPSIS
-   ...                        # doctest: +NORMALIZE_WHITESPACE
+.. doctest::
+   :no-trim-doctest-flags:
+
+   >>> print(list(range(20)))  # doctest: +ELLIPSIS
+   ...                         # doctest: +NORMALIZE_WHITESPACE
    [0,    1, ...,   18,    19]
 
 As the previous example shows, you can add ``...`` lines to your example
 containing only directives.  This can be useful when an example is too long for
-a directive to comfortably fit on the same line::
+a directive to comfortably fit on the same line:
+
+.. doctest::
+   :no-trim-doctest-flags:
 
    >>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
    ... # doctest: +ELLIPSIS
@@ -793,18 +808,23 @@ instead.  Another is to do ::
 
 There are others, but you get the idea.
 
-Another bad idea is to print things that embed an object address, like ::
+Another bad idea is to print things that embed an object address, like
 
-   >>> id(1.0) # certain to fail some of the time
+.. doctest::
+
+   >>> id(1.0) # certain to fail some of the time  # doctest: +SKIP
    7948648
    >>> class C: pass
-   >>> C()   # the default repr() for instances embeds an address
-   <__main__.C instance at 0x00AC18F0>
+   >>> C()   # the default repr() for instances embeds an address  # doctest: +SKIP
+   <C object at 0x00AC18F0>
 
-The :const:`ELLIPSIS` directive gives a nice approach for the last example::
+The :const:`ELLIPSIS` directive gives a nice approach for the last example:
 
-   >>> C() #doctest: +ELLIPSIS
-   <__main__.C instance at 0x...>
+.. doctest::
+   :no-trim-doctest-flags:
+
+   >>> C()  # doctest: +ELLIPSIS
+   <C object at 0x...>
 
 Floating-point numbers are also subject to small output variations across
 platforms, because Python defers to the platform C library for float formatting,

Doc/library/email.contentmanager.rst

@@ -116,7 +116,7 @@ Currently the email package provides only one concrete content manager,
       decoding the payload to unicode.  The default error handler is
       ``replace``.
 
-   .. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8' \
+   .. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8', \
                            cte=None, \
                            disposition=None, filename=None, cid=None, \
                            params=None, headers=None)

Doc/library/email.header.rst

@@ -116,7 +116,7 @@ Here is the :class:`Header` class description:
       if *s* is a byte string.
 
 
-   .. method:: encode(splitchars=';, \\t', maxlinelen=None, linesep='\\n')
+   .. method:: encode(splitchars=';, \t', maxlinelen=None, linesep='\n')
 
       Encode a message header into an RFC-compliant format, possibly wrapping
       long lines and encapsulating non-ASCII parts in base64 or quoted-printable

Doc/library/email.policy.rst

@@ -210,7 +210,7 @@ added matters.  To illustrate::
       :meth:`register_defect` method.
 
 
-   .. attribute:: mangle_from\_
+   .. attribute:: mangle_from_
 
       If :const:`True`, lines starting with *"From "* in the body are
       escaped by putting a ``>`` in front of them. This parameter is used when

Doc/library/enum.rst

@@ -61,16 +61,18 @@ helper, :class:`auto`.
     the bitwise operations without losing their :class:`Flag` membership.
 
 .. function:: unique
-   :noindex:
+    :noindex:
 
     Enum class decorator that ensures only one name is bound to any one value.
 
 .. class:: auto
 
-    Instances are replaced with an appropriate value for Enum members.  By default, the initial value starts at 1.
+    Instances are replaced with an appropriate value for Enum members.
+    :class:`StrEnum` defaults to the lower-cased version of the member name,
+    while other Enums default to 1 and increase from there.
 
 .. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
-
+.. versionadded:: 3.10  ``StrEnum``
 
 Creating an Enum
 ----------------
@@ -1164,6 +1166,15 @@ and raise an error if the two do not match::
     In Python 2 code the :attr:`_order_` attribute is necessary as definition
     order is lost before it can be recorded.
 
+
+_Private__names
+"""""""""""""""
+
+Private names are not converted to Enum members, but remain normal attributes.
+
+.. versionchanged:: 3.10
+
+
 ``Enum`` member type
 """"""""""""""""""""
 

Doc/library/exceptions.rst

@@ -90,8 +90,13 @@ The following exceptions are used mostly as base classes for other exceptions.
    .. method:: with_traceback(tb)
 
       This method sets *tb* as the new traceback for the exception and returns
-      the exception object.  It is usually used in exception handling code like
-      this::
+      the exception object.  It was more commonly used before the exception
+      chaining features of :pep:`3134` became available.  The following example
+      shows how we can convert an instance of ``SomeException`` into an
+      instance of ``OtherException`` while preserving the traceback.  Once
+      raised, the current frame is pushed onto the traceback of the
+      ``OtherException``, as would have happened to the traceback of the
+      original ``SomeException`` had we allowed it to propagate to the caller.
 
          try:
              ...

Doc/library/filecmp.rst

@@ -173,7 +173,13 @@ The :class:`dircmp` class
    .. attribute:: subdirs
 
       A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp`
-      objects.
+      instances (or MyDirCmp instances if this instance is of type MyDirCmp, a
+      subclass of :class:`dircmp`).
+
+      .. versionchanged:: 3.10
+         Previously entries were always :class:`dircmp` instances. Now entries
+         are the same type as *self*, if *self* is a subclass of
+         :class:`dircmp`.
 
 .. attribute:: DEFAULT_IGNORES
 

Doc/library/fnmatch.rst

@@ -75,7 +75,7 @@ patterns.
 
 .. function:: filter(names, pattern)
 
-   Return the subset of the list of *names* that match *pattern*. It is the same as
+   Construct a list from those elements of the iterable *names* that match *pattern*. It is the same as
    ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
 
 

Doc/library/formatter.rst

@@ -1,351 +0,0 @@
-:mod:`formatter` --- Generic output formatting
-==============================================
-
-.. module:: formatter
-   :synopsis: Generic output formatter and device interface.
-   :deprecated:
-
-.. deprecated:: 3.4
-   Due to lack of usage, the formatter module has been deprecated.
-
---------------
-
-This module supports two interface definitions, each with multiple
-implementations: The *formatter* interface, and the *writer* interface which is
-required by the formatter interface.
-
-Formatter objects transform an abstract flow of formatting events into specific
-output events on writer objects.  Formatters manage several stack structures to
-allow various properties of a writer object to be changed and restored; writers
-need not be able to handle relative changes nor any sort of "change back"
-operation.  Specific writer properties which may be controlled via formatter
-objects are horizontal alignment, font, and left margin indentations.  A
-mechanism is provided which supports providing arbitrary, non-exclusive style
-settings to a writer as well.  Additional interfaces facilitate formatting
-events which are not reversible, such as paragraph separation.
-
-Writer objects encapsulate device interfaces.  Abstract devices, such as file
-formats, are supported as well as physical devices.  The provided
-implementations all work with abstract devices.  The interface makes available
-mechanisms for setting the properties which formatter objects manage and
-inserting data into the output.
-
-
-.. _formatter-interface:
-
-The Formatter Interface
------------------------
-
-Interfaces to create formatters are dependent on the specific formatter class
-being instantiated.  The interfaces described below are the required interfaces
-which all formatters must support once initialized.
-
-One data element is defined at the module level:
-
-
-.. data:: AS_IS
-
-   Value which can be used in the font specification passed to the ``push_font()``
-   method described below, or as the new value to any other ``push_property()``
-   method.  Pushing the ``AS_IS`` value allows the corresponding ``pop_property()``
-   method to be called without having to track whether the property was changed.
-
-The following attributes are defined for formatter instance objects:
-
-
-.. attribute:: formatter.writer
-
-   The writer instance with which the formatter interacts.
-
-
-.. method:: formatter.end_paragraph(blanklines)
-
-   Close any open paragraphs and insert at least *blanklines* before the next
-   paragraph.
-
-
-.. method:: formatter.add_line_break()
-
-   Add a hard line break if one does not already exist.  This does not break the
-   logical paragraph.
-
-
-.. method:: formatter.add_hor_rule(*args, **kw)
-
-   Insert a horizontal rule in the output.  A hard break is inserted if there is
-   data in the current paragraph, but the logical paragraph is not broken.  The
-   arguments and keywords are passed on to the writer's :meth:`send_line_break`
-   method.
-
-
-.. method:: formatter.add_flowing_data(data)
-
-   Provide data which should be formatted with collapsed whitespace. Whitespace
-   from preceding and successive calls to :meth:`add_flowing_data` is considered as
-   well when the whitespace collapse is performed.  The data which is passed to
-   this method is expected to be word-wrapped by the output device.  Note that any
-   word-wrapping still must be performed by the writer object due to the need to
-   rely on device and font information.
-
-
-.. method:: formatter.add_literal_data(data)
-
-   Provide data which should be passed to the writer unchanged. Whitespace,
-   including newline and tab characters, are considered legal in the value of
-   *data*.
-
-
-.. method:: formatter.add_label_data(format, counter)
-
-   Insert a label which should be placed to the left of the current left margin.
-   This should be used for constructing bulleted or numbered lists.  If the
-   *format* value is a string, it is interpreted as a format specification for
-   *counter*, which should be an integer. The result of this formatting becomes the
-   value of the label; if *format* is not a string it is used as the label value
-   directly. The label value is passed as the only argument to the writer's
-   :meth:`send_label_data` method.  Interpretation of non-string label values is
-   dependent on the associated writer.
-
-   Format specifications are strings which, in combination with a counter value,
-   are used to compute label values.  Each character in the format string is copied
-   to the label value, with some characters recognized to indicate a transform on
-   the counter value.  Specifically, the character ``'1'`` represents the counter
-   value formatter as an Arabic number, the characters ``'A'`` and ``'a'``
-   represent alphabetic representations of the counter value in upper and lower
-   case, respectively, and ``'I'`` and ``'i'`` represent the counter value in Roman
-   numerals, in upper and lower case.  Note that the alphabetic and roman
-   transforms require that the counter value be greater than zero.
-
-
-.. method:: formatter.flush_softspace()
-
-   Send any pending whitespace buffered from a previous call to
-   :meth:`add_flowing_data` to the associated writer object.  This should be called
-   before any direct manipulation of the writer object.
-
-
-.. method:: formatter.push_alignment(align)
-
-   Push a new alignment setting onto the alignment stack.  This may be
-   :const:`AS_IS` if no change is desired.  If the alignment value is changed from
-   the previous setting, the writer's :meth:`new_alignment` method is called with
-   the *align* value.
-
-
-.. method:: formatter.pop_alignment()
-
-   Restore the previous alignment.
-
-
-.. method:: formatter.push_font((size, italic, bold, teletype))
-
-   Change some or all font properties of the writer object.  Properties which are
-   not set to :const:`AS_IS` are set to the values passed in while others are
-   maintained at their current settings.  The writer's :meth:`new_font` method is
-   called with the fully resolved font specification.
-
-
-.. method:: formatter.pop_font()
-
-   Restore the previous font.
-
-
-.. method:: formatter.push_margin(margin)
-
-   Increase the number of left margin indentations by one, associating the logical
-   tag *margin* with the new indentation.  The initial margin level is ``0``.
-   Changed values of the logical tag must be true values; false values other than
-   :const:`AS_IS` are not sufficient to change the margin.
-
-
-.. method:: formatter.pop_margin()
-
-   Restore the previous margin.
-
-
-.. method:: formatter.push_style(*styles)
-
-   Push any number of arbitrary style specifications.  All styles are pushed onto
-   the styles stack in order.  A tuple representing the entire stack, including
-   :const:`AS_IS` values, is passed to the writer's :meth:`new_styles` method.
-
-
-.. method:: formatter.pop_style(n=1)
-
-   Pop the last *n* style specifications passed to :meth:`push_style`.  A tuple
-   representing the revised stack, including :const:`AS_IS` values, is passed to
-   the writer's :meth:`new_styles` method.
-
-
-.. method:: formatter.set_spacing(spacing)
-
-   Set the spacing style for the writer.
-
-
-.. method:: formatter.assert_line_data(flag=1)
-
-   Inform the formatter that data has been added to the current paragraph
-   out-of-band.  This should be used when the writer has been manipulated
-   directly.  The optional *flag* argument can be set to false if the writer
-   manipulations produced a hard line break at the end of the output.
-
-
-.. _formatter-impls:
-
-Formatter Implementations
--------------------------
-
-Two implementations of formatter objects are provided by this module. Most
-applications may use one of these classes without modification or subclassing.
-
-
-.. class:: NullFormatter(writer=None)
-
-   A formatter which does nothing.  If *writer* is omitted, a :class:`NullWriter`
-   instance is created.  No methods of the writer are called by
-   :class:`NullFormatter` instances.  Implementations should inherit from this
-   class if implementing a writer interface but don't need to inherit any
-   implementation.
-
-
-.. class:: AbstractFormatter(writer)
-
-   The standard formatter.  This implementation has demonstrated wide applicability
-   to many writers, and may be used directly in most circumstances.  It has been
-   used to implement a full-featured World Wide Web browser.
-
-
-.. _writer-interface:
-
-The Writer Interface
---------------------
-
-Interfaces to create writers are dependent on the specific writer class being
-instantiated.  The interfaces described below are the required interfaces which
-all writers must support once initialized. Note that while most applications can
-use the :class:`AbstractFormatter` class as a formatter, the writer must
-typically be provided by the application.
-
-
-.. method:: writer.flush()
-
-   Flush any buffered output or device control events.
-
-
-.. method:: writer.new_alignment(align)
-
-   Set the alignment style.  The *align* value can be any object, but by convention
-   is a string or ``None``, where ``None`` indicates that the writer's "preferred"
-   alignment should be used. Conventional *align* values are ``'left'``,
-   ``'center'``, ``'right'``, and ``'justify'``.
-
-
-.. method:: writer.new_font(font)
-
-   Set the font style.  The value of *font* will be ``None``, indicating that the
-   device's default font should be used, or a tuple of the form ``(size,
-   italic, bold, teletype)``.  Size will be a string indicating the size of
-   font that should be used; specific strings and their interpretation must be
-   defined by the application.  The *italic*, *bold*, and *teletype* values are
-   Boolean values specifying which of those font attributes should be used.
-
-
-.. method:: writer.new_margin(margin, level)
-
-   Set the margin level to the integer *level* and the logical tag to *margin*.
-   Interpretation of the logical tag is at the writer's discretion; the only
-   restriction on the value of the logical tag is that it not be a false value for
-   non-zero values of *level*.
-
-
-.. method:: writer.new_spacing(spacing)
-
-   Set the spacing style to *spacing*.
-
-
-.. method:: writer.new_styles(styles)
-
-   Set additional styles.  The *styles* value is a tuple of arbitrary values; the
-   value :const:`AS_IS` should be ignored.  The *styles* tuple may be interpreted
-   either as a set or as a stack depending on the requirements of the application
-   and writer implementation.
-
-
-.. method:: writer.send_line_break()
-
-   Break the current line.
-
-
-.. method:: writer.send_paragraph(blankline)
-
-   Produce a paragraph separation of at least *blankline* blank lines, or the
-   equivalent.  The *blankline* value will be an integer.  Note that the
-   implementation will receive a call to :meth:`send_line_break` before this call
-   if a line break is needed;  this method should not include ending the last line
-   of the paragraph. It is only responsible for vertical spacing between
-   paragraphs.
-
-
-.. method:: writer.send_hor_rule(*args, **kw)
-
-   Display a horizontal rule on the output device.  The arguments to this method
-   are entirely application- and writer-specific, and should be interpreted with
-   care.  The method implementation may assume that a line break has already been
-   issued via :meth:`send_line_break`.
-
-
-.. method:: writer.send_flowing_data(data)
-
-   Output character data which may be word-wrapped and re-flowed as needed.  Within
-   any sequence of calls to this method, the writer may assume that spans of
-   multiple whitespace characters have been collapsed to single space characters.
-
-
-.. method:: writer.send_literal_data(data)
-
-   Output character data which has already been formatted for display.  Generally,
-   this should be interpreted to mean that line breaks indicated by newline
-   characters should be preserved and no new line breaks should be introduced.  The
-   data may contain embedded newline and tab characters, unlike data provided to
-   the :meth:`send_formatted_data` interface.
-
-
-.. method:: writer.send_label_data(data)
-
-   Set *data* to the left of the current left margin, if possible. The value of
-   *data* is not restricted; treatment of non-string values is entirely
-   application- and writer-dependent.  This method will only be called at the
-   beginning of a line.
-
-
-.. _writer-impls:
-
-Writer Implementations
-----------------------
-
-Three implementations of the writer object interface are provided as examples by
-this module.  Most applications will need to derive new writer classes from the
-:class:`NullWriter` class.
-
-
-.. class:: NullWriter()
-
-   A writer which only provides the interface definition; no actions are taken on
-   any methods.  This should be the base class for all writers which do not need to
-   inherit any implementation methods.
-
-
-.. class:: AbstractWriter()
-
-   A writer which can be used in debugging formatters, but not much else.  Each
-   method simply announces itself by printing its name and arguments on standard
-   output.
-
-
-.. class:: DumbWriter(file=None, maxcol=72)
-
-   Simple writer class which writes output on the :term:`file object` passed
-   in as *file* or, if *file* is omitted, on standard output.  The output is
-   simply word-wrapped to the number of columns specified by *maxcol*.  This
-   class is suitable for reflowing a sequence of paragraphs.
-

Doc/library/functions.rst

@@ -478,14 +478,15 @@ are always available.  They are listed here in alphabetical order.
    dictionaries as global and local namespace.  If the *globals* dictionary is
    present and does not contain a value for the key ``__builtins__``, a
    reference to the dictionary of the built-in module :mod:`builtins` is
-   inserted under that key before *expression* is parsed.  This means that
-   *expression* normally has full access to the standard :mod:`builtins`
-   module and restricted environments are propagated.  If the *locals*
-   dictionary is omitted it defaults to the *globals* dictionary.  If both
-   dictionaries are omitted, the expression is executed with the *globals* and
-   *locals* in the environment where :func:`eval` is called.  Note, *eval()*
-   does not have access to the :term:`nested scopes <nested scope>` (non-locals) in the
-   enclosing environment.
+   inserted under that key before *expression* is parsed.  That way you can
+   control what builtins are available to the executed code by inserting your
+   own ``__builtins__`` dictionary into *globals* before passing it to
+   :func:`eval`.  If the *locals* dictionary is omitted it defaults to the
+   *globals* dictionary.  If both dictionaries are omitted, the expression is
+   executed with the *globals* and *locals* in the environment where
+   :func:`eval` is called.  Note, *eval()* does not have access to the
+   :term:`nested scopes <nested scope>` (non-locals) in the enclosing
+   environment.
 
    The return value is the result of
    the evaluated expression. Syntax errors are reported as exceptions.  Example:
@@ -1333,7 +1334,7 @@ are always available.  They are listed here in alphabetical order.
       supported.
 
 
-.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False)
+.. function:: print(*objects, sep=' ', end='\n', file=sys.stdout, flush=False)
 
    Print *objects* to the text stream *file*, separated by *sep* and followed
    by *end*.  *sep*, *end*, *file* and *flush*, if present, must be given as keyword

Doc/library/http.client.rst

@@ -99,6 +99,11 @@ The module provides the following classes:
       :attr:`ssl.SSLContext.post_handshake_auth` for the default *context* or
       when *cert_file* is passed with a custom *context*.
 
+   .. versionchanged:: 3.10
+      This class now sends an ALPN extension with protocol indicator
+      ``http/1.1`` when no *context* is given. Custom *context* should set
+      ALPN protocols with :meth:`~ssl.SSLContext.set_alpn_protocol`.
+
    .. deprecated:: 3.6
 
        *key_file* and *cert_file* are deprecated in favor of *context*.

Doc/library/http.cookies.rst

@@ -93,7 +93,7 @@ Cookie Objects
    :meth:`value_decode` are inverses on the range of *value_decode*.
 
 
-.. method:: BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\\r\\n')
+.. method:: BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\r\n')
 
    Return a string representation suitable to be sent as HTTP headers. *attrs* and
    *header* are sent to each :class:`Morsel`'s :meth:`output` method. *sep* is used

Doc/library/imaplib.rst

@@ -174,9 +174,9 @@ example of usage.
 
 .. seealso::
 
-   Documents describing the protocol, and sources and binaries  for servers
-   implementing it, can all be found at the University of Washington's *IMAP
-   Information Center* (https://www.washington.edu/imap/).
+   Documents describing the protocol, sources for servers
+   implementing it, by the University of Washington's IMAP Information Center
+   can all be found at (**Source Code**) https://github.com/uw-imap/imap (**Not Maintained**).
 
 
 .. _imap4-objects:

Doc/library/importlib.rst

@@ -1138,7 +1138,7 @@ find and load modules.
       directory for ``''`` (i.e. the empty string).
 
 
-.. class:: FileFinder(path, \*loader_details)
+.. class:: FileFinder(path, *loader_details)
 
    A concrete implementation of :class:`importlib.abc.PathEntryFinder` which
    caches results from the file system.
@@ -1181,7 +1181,7 @@ find and load modules.
 
       Clear out the internal cache.
 
-   .. classmethod:: path_hook(\*loader_details)
+   .. classmethod:: path_hook(*loader_details)
 
       A class method which returns a closure for use on :attr:`sys.path_hooks`.
       An instance of :class:`FileFinder` is returned by the closure using the

Doc/library/index.rst

@@ -72,7 +72,6 @@ the `Python Package Index <https://pypi.org>`_.
    custominterp.rst
    modules.rst
    language.rst
-   misc.rst
    windows.rst
    unix.rst
    superseded.rst

Doc/library/inspect.rst

@@ -556,7 +556,7 @@ The Signature object represents the call signature of a callable object and its
 return annotation.  To retrieve a Signature object, use the :func:`signature`
 function.
 
-.. function:: signature(callable, \*, follow_wrapped=True)
+.. function:: signature(callable, *, follow_wrapped=True, globalns=None, localns=None)
 
    Return a :class:`Signature` object for the given ``callable``::
 
@@ -581,6 +581,9 @@ function.
    Raises :exc:`ValueError` if no signature can be provided, and
    :exc:`TypeError` if that type of object is not supported.
 
+   ``globalns`` and ``localns`` are passed into
+   :func:`typing.get_type_hints` when resolving the annotations.
+
    A slash(/) in the signature of a function denotes that the parameters prior
    to it are positional-only. For more info, see
    :ref:`the FAQ entry on positional-only parameters <faq-positional-only-arguments>`.
@@ -590,14 +593,23 @@ function.
       ``callable`` specifically (``callable.__wrapped__`` will not be used to
       unwrap decorated callables.)
 
+   .. versionadded:: 3.10
+      ``globalns`` and ``localns`` parameters.
+
    .. note::
 
       Some callables may not be introspectable in certain implementations of
       Python.  For example, in CPython, some built-in functions defined in
       C provide no metadata about their arguments.
 
+   .. note::
 
-.. class:: Signature(parameters=None, \*, return_annotation=Signature.empty)
+      Will first try to resolve the annotations, but when it fails and
+      encounters with an error while that operation, the annotations will be
+      returned unchanged (as strings).
+
+
+.. class:: Signature(parameters=None, *, return_annotation=Signature.empty)
 
    A Signature object represents the call signature of a function and its return
    annotation.  For each parameter accepted by the function it stores a
@@ -668,11 +680,12 @@ function.
          >>> str(new_sig)
          "(a, b) -> 'new return anno'"
 
-   .. classmethod:: Signature.from_callable(obj, \*, follow_wrapped=True)
+   .. classmethod:: Signature.from_callable(obj, *, follow_wrapped=True, globalns=None, localns=None)
 
        Return a :class:`Signature` (or its subclass) object for a given callable
        ``obj``.  Pass ``follow_wrapped=False`` to get a signature of ``obj``
-       without unwrapping its ``__wrapped__`` chain.
+       without unwrapping its ``__wrapped__`` chain. ``globalns`` and
+       ``localns`` will be used as the namespaces when resolving annotations.
 
        This method simplifies subclassing of :class:`Signature`::
 
@@ -683,8 +696,11 @@ function.
 
        .. versionadded:: 3.5
 
+       .. versionadded:: 3.10
+          ``globalns`` and ``localns`` parameters.
 
-.. class:: Parameter(name, kind, \*, default=Parameter.empty, annotation=Parameter.empty)
+
+.. class:: Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)
 
    Parameter objects are *immutable*.  Instead of modifying a Parameter object,
    you can use :meth:`Parameter.replace` to create a modified copy.

Doc/library/io.rst

@@ -964,7 +964,7 @@ Text I/O
       .. versionadded:: 3.7
 
 
-.. class:: StringIO(initial_value='', newline='\\n')
+.. class:: StringIO(initial_value='', newline='\n')
 
    A text stream using an in-memory text buffer.  It inherits
    :class:`TextIOBase`.

Doc/library/itertools.rst

@@ -55,6 +55,7 @@ Iterator                        Arguments                       Results
 :func:`filterfalse`             pred, seq                       elements of seq where pred(elem) is false           ``filterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8``
 :func:`groupby`                 iterable[, key]                 sub-iterators grouped by value of key(v)
 :func:`islice`                  seq, [start,] stop [, step]     elements from seq[start:stop:step]                  ``islice('ABCDEFG', 2, None) --> C D E F G``
+:func:`pairwise`                iterable                        (p[0], p[1]), (p[1], p[2])                          ``pairwise('ABCDEFG') --> AB BC CD DE EF FG``
 :func:`starmap`                 func, seq                       func(\*seq[0]), func(\*seq[1]), ...                 ``starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000``
 :func:`takewhile`               pred, seq                       seq[0], seq[1], until pred fails                    ``takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4``
 :func:`tee`                     it, n                           it1, it2, ... itn  splits one iterator into n
@@ -475,6 +476,22 @@ loops that truncate the stream.
    If *start* is ``None``, then iteration starts at zero. If *step* is ``None``,
    then the step defaults to one.
 
+.. function:: pairwise(iterable)
+
+   Return successive overlapping pairs taken from the input *iterable*.
+
+   The number of 2-tuples in the output iterator will be one fewer than the
+   number of inputs.  It will be empty if the input iterable has fewer than
+   two values.
+
+   Roughly equivalent to::
+
+        def pairwise(iterable):
+            # pairwise('ABCDEFG') --> AB BC CD DE EF FG
+            a, b = tee(iterable)
+            next(b, None)
+            return zip(a, b)
+
 
 .. function:: permutations(iterable, r=None)
 
@@ -565,7 +582,7 @@ loops that truncate the stream.
 
    Before :func:`product` runs, it completely consumes the input iterables,
    keeping pools of values in memory to generate the products.  Accordingly,
-   it only useful with finite inputs.
+   it is only useful with finite inputs.
 
 .. function:: repeat(object[, times])
 
@@ -755,7 +772,7 @@ which incur interpreter overhead.
        "Count how many times the predicate is true"
        return sum(map(pred, iterable))
 
-   def padnone(iterable):
+   def pad_none(iterable):
        """Returns the sequence elements and then returns None indefinitely.
 
        Useful for emulating the behavior of the built-in map() function.
@@ -769,6 +786,18 @@ which incur interpreter overhead.
    def dotproduct(vec1, vec2):
        return sum(map(operator.mul, vec1, vec2))
 
+   def convolve(signal, kernel):
+       # See:  https://betterexplained.com/articles/intuitive-convolution/
+       # convolve(data, [0.25, 0.25, 0.25, 0.25]) --> Moving average (blur)
+       # convolve(data, [1, -1]) --> 1st finite difference (1st derivative)
+       # convolve(data, [1, -2, 1]) --> 2nd finite difference (2nd derivative)
+       kernel = list(reversed(kernel))
+       n = len(kernel)
+       window = collections.deque([0] * n, maxlen=n)
+       for x in chain(signal, repeat(0, n-1)):
+           window.append(x)
+           yield sum(map(operator.mul, kernel, window))
+
    def flatten(list_of_lists):
        "Flatten one level of nesting"
        return chain.from_iterable(list_of_lists)
@@ -782,12 +811,6 @@ which incur interpreter overhead.
            return starmap(func, repeat(args))
        return starmap(func, repeat(args, times))
 
-   def pairwise(iterable):
-       "s -> (s0,s1), (s1,s2), (s2, s3), ..."
-       a, b = tee(iterable)
-       next(b, None)
-       return zip(a, b)
-
    def grouper(iterable, n, fillvalue=None):
        "Collect data into fixed-length chunks or blocks"
        # grouper('ABCDEFG', 3, 'x') --> ABC DEF Gxx"
@@ -809,7 +832,7 @@ which incur interpreter overhead.
                nexts = cycle(islice(nexts, num_active))
 
    def partition(pred, iterable):
-       'Use a predicate to partition entries into false entries and true entries'
+       "Use a predicate to partition entries into false entries and true entries"
        # partition(is_odd, range(10)) --> 0 2 4 6 8   and  1 3 5 7 9
        t1, t2 = tee(iterable)
        return filterfalse(pred, t1), filter(pred, t2)
@@ -881,7 +904,7 @@ which incur interpreter overhead.
    def random_product(*args, repeat=1):
        "Random selection from itertools.product(*args, **kwds)"
        pools = [tuple(pool) for pool in args] * repeat
-       return tuple(random.choice(pool) for pool in pools)
+       return tuple(map(random.choice, pools))
 
    def random_permutation(iterable, r=None):
        "Random selection from itertools.permutations(iterable, r)"
@@ -900,11 +923,11 @@ which incur interpreter overhead.
        "Random selection from itertools.combinations_with_replacement(iterable, r)"
        pool = tuple(iterable)
        n = len(pool)
-       indices = sorted(random.randrange(n) for i in range(r))
+       indices = sorted(random.choices(range(n), k=r))
        return tuple(pool[i] for i in indices)
 
    def nth_combination(iterable, r, index):
-       'Equivalent to list(combinations(iterable, r))[index]'
+       "Equivalent to list(combinations(iterable, r))[index]"
        pool = tuple(iterable)
        n = len(pool)
        if r < 0 or r > n:

Doc/library/logging.config.rst

@@ -35,45 +35,45 @@ in :mod:`logging` itself) and defining handlers which are declared either in
 
 .. function:: dictConfig(config)
 
-    Takes the logging configuration from a dictionary.  The contents of
-    this dictionary are described in :ref:`logging-config-dictschema`
-    below.
+   Takes the logging configuration from a dictionary.  The contents of
+   this dictionary are described in :ref:`logging-config-dictschema`
+   below.
 
-    If an error is encountered during configuration, this function will
-    raise a :exc:`ValueError`, :exc:`TypeError`, :exc:`AttributeError`
-    or :exc:`ImportError` with a suitably descriptive message.  The
-    following is a (possibly incomplete) list of conditions which will
-    raise an error:
+   If an error is encountered during configuration, this function will
+   raise a :exc:`ValueError`, :exc:`TypeError`, :exc:`AttributeError`
+   or :exc:`ImportError` with a suitably descriptive message.  The
+   following is a (possibly incomplete) list of conditions which will
+   raise an error:
 
-    * A ``level`` which is not a string or which is a string not
-      corresponding to an actual logging level.
-    * A ``propagate`` value which is not a boolean.
-    * An id which does not have a corresponding destination.
-    * A non-existent handler id found during an incremental call.
-    * An invalid logger name.
-    * Inability to resolve to an internal or external object.
+   * A ``level`` which is not a string or which is a string not
+     corresponding to an actual logging level.
+   * A ``propagate`` value which is not a boolean.
+   * An id which does not have a corresponding destination.
+   * A non-existent handler id found during an incremental call.
+   * An invalid logger name.
+   * Inability to resolve to an internal or external object.
 
-    Parsing is performed by the :class:`DictConfigurator` class, whose
-    constructor is passed the dictionary used for configuration, and
-    has a :meth:`configure` method.  The :mod:`logging.config` module
-    has a callable attribute :attr:`dictConfigClass`
-    which is initially set to :class:`DictConfigurator`.
-    You can replace the value of :attr:`dictConfigClass` with a
-    suitable implementation of your own.
+   Parsing is performed by the :class:`DictConfigurator` class, whose
+   constructor is passed the dictionary used for configuration, and
+   has a :meth:`configure` method.  The :mod:`logging.config` module
+   has a callable attribute :attr:`dictConfigClass`
+   which is initially set to :class:`DictConfigurator`.
+   You can replace the value of :attr:`dictConfigClass` with a
+   suitable implementation of your own.
 
-    :func:`dictConfig` calls :attr:`dictConfigClass` passing
-    the specified dictionary, and then calls the :meth:`configure` method on
-    the returned object to put the configuration into effect::
+   :func:`dictConfig` calls :attr:`dictConfigClass` passing
+   the specified dictionary, and then calls the :meth:`configure` method on
+   the returned object to put the configuration into effect::
 
-          def dictConfig(config):
-              dictConfigClass(config).configure()
+         def dictConfig(config):
+             dictConfigClass(config).configure()
 
-    For example, a subclass of :class:`DictConfigurator` could call
-    ``DictConfigurator.__init__()`` in its own :meth:`__init__()`, then
-    set up custom prefixes which would be usable in the subsequent
-    :meth:`configure` call. :attr:`dictConfigClass` would be bound to
-    this new subclass, and then :func:`dictConfig` could be called exactly as
-    in the default, uncustomized state.
+   For example, a subclass of :class:`DictConfigurator` could call
+   ``DictConfigurator.__init__()`` in its own :meth:`__init__()`, then
+   set up custom prefixes which would be usable in the subsequent
+   :meth:`configure` call. :attr:`dictConfigClass` would be bound to
+   this new subclass, and then :func:`dictConfig` could be called exactly as
+   in the default, uncustomized state.
 
    .. versionadded:: 3.2
 

Doc/library/logging.rst

@@ -1096,8 +1096,8 @@ functions.
    suitable value.
 
    .. versionchanged:: 3.7
-      The *level* parameter was defaulted to level ``CRITICAL``. See Issue
-      #28524 for more information about this change.
+      The *level* parameter was defaulted to level ``CRITICAL``. See
+      :issue:`28524` for more information about this change.
 
 .. function:: addLevelName(level, levelName)
 
@@ -1174,7 +1174,9 @@ functions.
    |              | to ``'a'``.                                 |
    +--------------+---------------------------------------------+
    | *format*     | Use the specified format string for the     |
-   |              | handler.                                    |
+   |              | handler. Defaults to attributes             |
+   |              | ``levelname``, ``name`` and ``message``     |
+   |              | separated by colons.                        |
    +--------------+---------------------------------------------+
    | *datefmt*    | Use the specified date/time format, as      |
    |              | accepted by :func:`time.strftime`.          |

Doc/library/lzma.rst

@@ -33,7 +33,7 @@ from multiple threads, it is necessary to protect it with a lock.
 Reading and writing compressed files
 ------------------------------------
 
-.. function:: open(filename, mode="rb", \*, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)
+.. function:: open(filename, mode="rb", *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)
 
    Open an LZMA-compressed file in binary or text mode, returning a :term:`file
    object`.
@@ -69,7 +69,7 @@ Reading and writing compressed files
       Accepts a :term:`path-like object`.
 
 
-.. class:: LZMAFile(filename=None, mode="r", \*, format=None, check=-1, preset=None, filters=None)
+.. class:: LZMAFile(filename=None, mode="r", *, format=None, check=-1, preset=None, filters=None)
 
    Open an LZMA-compressed file in binary mode.
 

Doc/library/misc.rst

@@ -1,13 +0,0 @@
-.. _misc:
-
-**********************
-Miscellaneous Services
-**********************
-
-The modules described in this chapter provide miscellaneous services that are
-available in all Python versions.  Here's an overview:
-
-
-.. toctree::
-
-   formatter.rst

Doc/library/mmap.rst

@@ -337,6 +337,8 @@ MADV_* Constants
           MADV_NOCORE
           MADV_CORE
           MADV_PROTECT
+          MADV_FREE_REUSABLE
+          MADV_FREE_REUSE
 
    These options can be passed to :meth:`mmap.madvise`.  Not every option will
    be present on every system.

Doc/library/multiprocessing.rst

@@ -98,7 +98,7 @@ to start a process.  These *start methods* are
   *spawn*
     The parent process starts a fresh python interpreter process.  The
     child process will only inherit those resources necessary to run
-    the process objects :meth:`~Process.run` method.  In particular,
+    the process object's :meth:`~Process.run` method.  In particular,
     unnecessary file descriptors and handles from the parent process
     will not be inherited.  Starting a process using this method is
     rather slow compared to using *fork* or *forkserver*.
@@ -2569,9 +2569,9 @@ Address Formats
   filesystem.
 
 * An ``'AF_PIPE'`` address is a string of the form
-   :samp:`r'\\\\.\\pipe\\{PipeName}'`.  To use :func:`Client` to connect to a named
-   pipe on a remote computer called *ServerName* one should use an address of the
-   form :samp:`r'\\\\{ServerName}\\pipe\\{PipeName}'` instead.
+  :samp:`r'\\\\.\\pipe\\{PipeName}'`.  To use :func:`Client` to connect to a named
+  pipe on a remote computer called *ServerName* one should use an address of the
+  form :samp:`r'\\\\{ServerName}\\pipe\\{PipeName}'` instead.
 
 Note that any string beginning with two backslashes is assumed by default to be
 an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address.
@@ -2661,6 +2661,46 @@ The :mod:`multiprocessing.dummy` module
 :mod:`multiprocessing.dummy` replicates the API of :mod:`multiprocessing` but is
 no more than a wrapper around the :mod:`threading` module.
 
+.. currentmodule:: multiprocessing.pool
+
+In particular, the ``Pool`` function provided by :mod:`multiprocessing.dummy`
+returns an instance of :class:`ThreadPool`, which is a subclass of
+:class:`Pool` that supports all the same method calls but uses a pool of
+worker threads rather than worker processes.
+
+
+.. class:: ThreadPool([processes[, initializer[, initargs]]])
+
+   A thread pool object which controls a pool of worker threads to which jobs
+   can be submitted.  :class:`ThreadPool` instances are fully interface
+   compatible with :class:`Pool` instances, and their resources must also be
+   properly managed, either by using the pool as a context manager or by
+   calling :meth:`~multiprocessing.pool.Pool.close` and
+   :meth:`~multiprocessing.pool.Pool.terminate` manually.
+
+   *processes* is the number of worker threads to use.  If *processes* is
+   ``None`` then the number returned by :func:`os.cpu_count` is used.
+
+   If *initializer* is not ``None`` then each worker process will call
+   ``initializer(*initargs)`` when it starts.
+
+   Unlike :class:`Pool`, *maxtasksperchild* and *context* cannot be provided.
+
+    .. note::
+
+        A :class:`ThreadPool` shares the same interface as :class:`Pool`, which
+        is designed around a pool of processes and predates the introduction of
+        the :class:`concurrent.futures` module.  As such, it inherits some
+        operations that don't make sense for a pool backed by threads, and it
+        has its own type for representing the status of asynchronous jobs,
+        :class:`AsyncResult`, that is not understood by any other libraries.
+
+        Users should generally prefer to use
+        :class:`concurrent.futures.ThreadPoolExecutor`, which has a simpler
+        interface that was designed around threads from the start, and which
+        returns :class:`concurrent.futures.Future` instances that are
+        compatible with many other libraries, including :mod:`asyncio`.
+
 
 .. _multiprocessing-programming:
 

Doc/library/os.rst

@@ -32,7 +32,7 @@ Notes on the availability of these functions:
   objects, and result in an object of the same type, if a path or file name is
   returned.
 
-* On VxWorks, os.fork, os.execv and os.spawn*p* are not supported.
+* On VxWorks, os.popen, os.fork, os.execv and os.spawn*p* are not supported.
 
 .. note::
 
@@ -113,6 +113,8 @@ of the UTF-8 encoding:
   :ref:`error handler <error-handlers>` being enabled for :data:`sys.stdin`
   and :data:`sys.stdout` (:data:`sys.stderr` continues to use
   ``backslashreplace`` as it does in the default locale-aware mode)
+* On Unix, :func:`os.device_encoding` returns ``'UTF-8'``. rather than the
+  device encoding.
 
 Note that the standard stream settings in UTF-8 mode can be overridden by
 :envvar:`PYTHONIOENCODING` (just as they can be in the default locale-aware
@@ -808,6 +810,12 @@ as internal buffering of data.
    Return a string describing the encoding of the device associated with *fd*
    if it is connected to a terminal; else return :const:`None`.
 
+   On Unix, if the :ref:`Python UTF-8 Mode <utf8-mode>` is enabled, return
+   ``'UTF-8'`` rather than the device encoding.
+
+   .. versionchanged:: 3.10
+      On Unix, the function now implements the Python UTF-8 Mode.
+
 
 .. function:: dup(fd)
 
@@ -1315,12 +1323,12 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
 
 .. data:: RWF_APPEND
 
-    Provide a per-write equivalent of the :data:`O_APPEND` :func:`os.open`
-    flag. This flag is meaningful only for :func:`os.pwritev`, and its
-    effect applies only to the data range written by the system call. The
-    *offset* argument does not affect the write operation; the data is always
-    appended to the end of the file. However, if the *offset* argument is
-    ``-1``, the current file *offset* is updated.
+   Provide a per-write equivalent of the :data:`O_APPEND` :func:`os.open`
+   flag. This flag is meaningful only for :func:`os.pwritev`, and its
+   effect applies only to the data range written by the system call. The
+   *offset* argument does not affect the write operation; the data is always
+   appended to the end of the file. However, if the *offset* argument is
+   ``-1``, the current file *offset* is updated.
 
    .. availability:: Linux 4.16 and newer.
 
@@ -1411,6 +1419,39 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    .. versionadded:: 3.3
 
 
+.. function:: splice(src, dst, count, offset_src=None, offset_dst=None)
+
+   Transfer *count* bytes from file descriptor *src*, starting from offset
+   *offset_src*, to file descriptor *dst*, starting from offset *offset_dst*.
+   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
+   pipe must be ``None``. The files pointed by *src* and *dst* must reside in
+   the same filesystem, otherwise an :exc:`OSError` is raised with
+   :attr:`~OSError.errno` set to :data:`errno.EXDEV`.
+
+   This copy is done without the additional cost of transferring data
+   from the kernel to user space and then back into the kernel. Additionally,
+   some filesystems could implement extra optimizations. The copy is done as if
+   both files are opened as binary.
+
+   Upon successful completion, returns the number of bytes spliced to or from
+   the pipe. A return value of 0 means end of input. If *src* refers to a
+   pipe, then this means that there was no data to transfer, and it would not
+   make sense to block because there are no writers connected to the write end
+   of the pipe.
+
+   .. availability:: Linux kernel >= 2.6.17 and glibc >= 2.5
+
+   .. versionadded:: 3.10
+
+
+.. data:: SPLICE_F_MOVE
+          SPLICE_F_NONBLOCK
+          SPLICE_F_MORE
+
+   .. versionadded:: 3.10
+
 .. function:: readv(fd, buffers)
 
    Read from a file descriptor *fd* into a number of mutable :term:`bytes-like
@@ -1950,7 +1991,7 @@ features:
       Accepts a :term:`path-like object`.
 
 
-.. function:: lstat(path, \*, dir_fd=None)
+.. function:: lstat(path, *, dir_fd=None)
 
    Perform the equivalent of an :c:func:`lstat` system call on the given path.
    Similar to :func:`~os.stat`, but does not follow symbolic links. Return a
@@ -2457,7 +2498,7 @@ features:
       On the first, uncached call, a system call is required on Windows but
       not on Unix.
 
-   .. method:: is_dir(\*, follow_symlinks=True)
+   .. method:: is_dir(*, follow_symlinks=True)
 
       Return ``True`` if this entry is a directory or a symbolic link pointing
       to a directory; return ``False`` if the entry is or points to any other
@@ -2481,7 +2522,7 @@ features:
       This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
       but :exc:`FileNotFoundError` is caught and not raised.
 
-   .. method:: is_file(\*, follow_symlinks=True)
+   .. method:: is_file(*, follow_symlinks=True)
 
       Return ``True`` if this entry is a file or a symbolic link pointing to a
       file; return ``False`` if the entry is or points to a directory or other
@@ -2511,7 +2552,7 @@ features:
       This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
       but :exc:`FileNotFoundError` is caught and not raised.
 
-   .. method:: stat(\*, follow_symlinks=True)
+   .. method:: stat(*, follow_symlinks=True)
 
       Return a :class:`stat_result` object for this entry. This method
       follows symbolic links by default; to stat a symbolic link add the
@@ -2543,7 +2584,7 @@ features:
       for :class:`bytes` paths on Windows.
 
 
-.. function:: stat(path, \*, dir_fd=None, follow_symlinks=True)
+.. function:: stat(path, *, dir_fd=None, follow_symlinks=True)
 
    Get the status of a file or a file descriptor. Perform the equivalent of a
    :c:func:`stat` system call on the given path. *path* may be specified as
@@ -3268,6 +3309,102 @@ features:
    .. versionadded:: 3.8
 
 
+.. function:: eventfd(initval[, flags=os.EFD_CLOEXEC])
+
+   Create and return an event file descriptor. The file descriptors supports
+   raw :func:`read` and :func:`write` with a buffer size of 8,
+   :func:`~select.select`, :func:`~select.poll` and similar. See man page
+   :manpage:`eventfd(2)` for more information.  By default, the
+   new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
+
+   *initval* is the initial value of the event counter. The initial value
+   must be an 32 bit unsigned integer. Please note that the initial value is
+   limited to a 32 bit unsigned int although the event counter is an unsigned
+   64 bit integer with a maximum value of 2\ :sup:`64`\ -\ 2.
+
+   *flags* can be constructed from :const:`EFD_CLOEXEC`,
+   :const:`EFD_NONBLOCK`, and :const:`EFD_SEMAPHORE`.
+
+   If :const:`EFD_SEMAPHORE` is specified and the event counter is non-zero,
+   :func:`eventfd_read` returns 1 and decrements the counter by one.
+
+   If :const:`EFD_SEMAPHORE` is not specified and the event counter is
+   non-zero, :func:`eventfd_read` returns the current event counter value and
+   resets the counter to zero.
+
+   If the event counter is zero and :const:`EFD_NONBLOCK` is not
+   specified, :func:`eventfd_read` blocks.
+
+   :func:`eventfd_write` increments the event counter. Write blocks if the
+   write operation would increment the counter to a value larger than
+   2\ :sup:`64`\ -\ 2.
+
+   Example::
+
+       import os
+
+       # semaphore with start value '1'
+       fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
+       try:
+           # acquire semaphore
+           v = os.eventfd_read(fd)
+           try:
+               do_work()
+           finally:
+               # release semaphore
+               os.eventfd_write(fd, v)
+       finally:
+           os.close(fd)
+
+   .. availability:: Linux 2.6.27 or newer with glibc 2.8 or newer.
+
+   .. versionadded:: 3.10
+
+.. function:: eventfd_read(fd)
+
+   Read value from an :func:`eventfd` file descriptor and return a 64 bit
+   unsigned int. The function does not verify that *fd* is an :func:`eventfd`.
+
+   .. availability:: See :func:`eventfd`
+
+   .. versionadded:: 3.10
+
+.. function:: eventfd_write(fd, value)
+
+   Add value to an :func:`eventfd` file descriptor. *value* must be a 64 bit
+   unsigned int. The function does not verify that *fd* is an :func:`eventfd`.
+
+   .. availability:: See :func:`eventfd`
+
+   .. versionadded:: 3.10
+
+.. data:: EFD_CLOEXEC
+
+   Set close-on-exec flag for new :func:`eventfd` file descriptor.
+
+   .. availability:: See :func:`eventfd`
+
+   .. versionadded:: 3.10
+
+.. data:: EFD_NONBLOCK
+
+   Set :const:`O_NONBLOCK` status flag for new :func:`eventfd` file
+   descriptor.
+
+   .. availability:: See :func:`eventfd`
+
+   .. versionadded:: 3.10
+
+.. data:: EFD_SEMAPHORE
+
+   Provide semaphore-like semantics for reads from a :func:`eventfd` file
+   descriptor. On read the internal counter is decremented by one.
+
+   .. availability:: Linux 2.6.30 or newer with glibc 2.8 or newer.
+
+   .. versionadded:: 3.10
+
+
 Linux extended attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

Doc/library/pathlib.rst

@@ -336,6 +336,8 @@ Pure paths provide the following methods and properties:
       >>> p.parents[2]
       PureWindowsPath('c:/')
 
+   .. versionchanged:: 3.10
+      The parents sequence now supports :term:`slices <slice>` and negative index values.
 
 .. data:: PurePath.parent
 

Doc/library/pickle.rst

@@ -213,7 +213,7 @@ The :mod:`pickle` module provides the following constants:
 The :mod:`pickle` module provides the following functions to make the pickling
 process more convenient:
 
-.. function:: dump(obj, file, protocol=None, \*, fix_imports=True, buffer_callback=None)
+.. function:: dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)
 
    Write the pickled representation of the object *obj* to the open
    :term:`file object` *file*.  This is equivalent to
@@ -225,7 +225,7 @@ process more convenient:
    .. versionchanged:: 3.8
       The *buffer_callback* argument was added.
 
-.. function:: dumps(obj, protocol=None, \*, fix_imports=True, buffer_callback=None)
+.. function:: dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None)
 
    Return the pickled representation of the object *obj* as a :class:`bytes` object,
    instead of writing it to a file.
@@ -236,7 +236,7 @@ process more convenient:
    .. versionchanged:: 3.8
       The *buffer_callback* argument was added.
 
-.. function:: load(file, \*, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
+.. function:: load(file, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
 
    Read the pickled representation of an object from the open :term:`file object`
    *file* and return the reconstituted object hierarchy specified therein.
@@ -252,7 +252,7 @@ process more convenient:
    .. versionchanged:: 3.8
       The *buffers* argument was added.
 
-.. function:: loads(data, /, \*, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
+.. function:: loads(data, /, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
 
    Return the reconstituted object hierarchy of the pickled representation
    *data* of an object. *data* must be a :term:`bytes-like object`.
@@ -296,7 +296,7 @@ The :mod:`pickle` module defines three exceptions:
 The :mod:`pickle` module exports three classes, :class:`Pickler`,
 :class:`Unpickler` and :class:`PickleBuffer`:
 
-.. class:: Pickler(file, protocol=None, \*, fix_imports=True, buffer_callback=None)
+.. class:: Pickler(file, protocol=None, *, fix_imports=True, buffer_callback=None)
 
    This takes a binary file for writing a pickle data stream.
 
@@ -391,7 +391,7 @@ The :mod:`pickle` module exports three classes, :class:`Pickler`,
       Use :func:`pickletools.optimize` if you need more compact pickles.
 
 
-.. class:: Unpickler(file, \*, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
+.. class:: Unpickler(file, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
 
    This takes a binary file for reading a pickle data stream.
 

Doc/library/pipes.rst

@@ -17,6 +17,8 @@ The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*
 Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible
 shell for :func:`os.system` and :func:`os.popen` is required.
 
+.. availability:: Unix. Not available on VxWorks.
+
 The :mod:`pipes` module defines the following class:
 
 

Doc/library/platform.rst

@@ -209,13 +209,6 @@ Windows Platform
    which means the OS version uses debugging code, i.e. code that checks arguments,
    ranges, etc.
 
-   .. note::
-
-      This function works best with Mark Hammond's
-      :mod:`win32all` package installed, but also on Python 2.3 and
-      later (support for this was added in Python 2.6). It obviously
-      only runs on Win32 compatible platforms.
-
 .. function:: win32_edition()
 
    Returns a string representing the current Windows edition.  Possible
@@ -260,3 +253,41 @@ Unix Platforms
    using :program:`gcc`.
 
    The file is read and scanned in chunks of *chunksize* bytes.
+
+
+Linux Platforms
+---------------
+
+.. function:: freedesktop_os_release()
+
+   Get operating system identification from ``os-release`` file and return
+   it as a dict. The ``os-release`` file is a `freedesktop.org standard
+   <https://www.freedesktop.org/software/systemd/man/os-release.html>`_ and
+   is available in most Linux distributions. A noticeable exception is
+   Android and Android-based distributions.
+
+   Raises :exc:`OSError` or subclass when neither ``/etc/os-release`` nor
+   ``/usr/lib/os-release`` can be read.
+
+   On success, the function returns a dictionary where keys and values are
+   strings. Values have their special characters like ``"`` and ``$``
+   unquoted. The fields ``NAME``, ``ID``, and ``PRETTY_NAME`` are always
+   defined according to the standard. All other fields are optional. Vendors
+   may include additional fields.
+
+   Note that fields like ``NAME``, ``VERSION``, and ``VARIANT`` are strings
+   suitable for presentation to users. Programs should use fields like
+   ``ID``, ``ID_LIKE``, ``VERSION_ID``, or ``VARIANT_ID`` to identify
+   Linux distributions.
+
+   Example::
+
+      def get_like_distro():
+          info = platform.freedesktop_os_release()
+          ids = [info["ID"]]
+          if "ID_LIKE" in info:
+              # ids are space separated and ordered by precedence
+              ids.extend(info["ID_LIKE"].split())
+          return ids
+
+   .. versionadded:: 3.10

Doc/library/plistlib.rst

@@ -52,7 +52,7 @@ or :class:`datetime.datetime` objects.
 
 This module defines the following functions:
 
-.. function:: load(fp, \*, fmt=None, dict_type=dict)
+.. function:: load(fp, *, fmt=None, dict_type=dict)
 
    Read a plist file. *fp* should be a readable and binary file object.
    Return the unpacked root object (which usually is a
@@ -80,7 +80,7 @@ This module defines the following functions:
    .. versionadded:: 3.4
 
 
-.. function:: loads(data, \*, fmt=None, dict_type=dict)
+.. function:: loads(data, *, fmt=None, dict_type=dict)
 
    Load a plist from a bytes object. See :func:`load` for an explanation of
    the keyword arguments.
@@ -88,7 +88,7 @@ This module defines the following functions:
    .. versionadded:: 3.4
 
 
-.. function:: dump(value, fp, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
+.. function:: dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)
 
    Write *value* to a plist file. *Fp* should be a writable, binary
    file object.
@@ -116,7 +116,7 @@ This module defines the following functions:
    .. versionadded:: 3.4
 
 
-.. function:: dumps(value, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
+.. function:: dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)
 
    Return *value* as a plist-formatted bytes object. See
    the documentation for :func:`dump` for an explanation of the keyword

Doc/library/profile.rst

@@ -525,16 +525,16 @@ Analysis of the profiler data is done using the :class:`~pstats.Stats` class.
       ordering are identical to the :meth:`~pstats.Stats.print_callers` method.
 
 
-    .. method:: get_stats_profile()
+   .. method:: get_stats_profile()
 
       This method returns an instance of StatsProfile, which contains a mapping
       of function names to instances of FunctionProfile. Each FunctionProfile
       instance holds information related to the function's profile such as how
       long the function took to run, how many times it was called, etc...
 
-       .. versionadded:: 3.9
-          Added the following dataclasses: StatsProfile, FunctionProfile.
-          Added the following function: get_stats_profile.
+      .. versionadded:: 3.9
+         Added the following dataclasses: StatsProfile, FunctionProfile.
+         Added the following function: get_stats_profile.
 
 .. _deterministic-profiling:
 

Doc/library/pyclbr.rst

@@ -97,6 +97,13 @@ statements.  They have the following attributes:
    .. versionadded:: 3.7
 
 
+.. attribute:: Function.is_async
+
+   ``True`` for functions that are defined with the ``async`` prefix, ``False`` otherwise.
+
+   .. versionadded:: 3.10
+
+
 .. _pyclbr-class-objects:
 
 Class Objects

Doc/library/random.rst

@@ -142,10 +142,11 @@ Functions for integers
 
 .. function:: getrandbits(k)
 
-   Returns a Python integer with *k* random bits. This method is supplied with
-   the MersenneTwister generator and some other generators may also provide it
-   as an optional part of the API. When available, :meth:`getrandbits` enables
-   :meth:`randrange` to handle arbitrarily large ranges.
+   Returns a non-negative Python integer with *k* random bits. This method
+   is supplied with the MersenneTwister generator and some other generators
+   may also provide it as an optional part of the API. When available,
+   :meth:`getrandbits` enables :meth:`randrange` to handle arbitrarily large
+   ranges.
 
    .. versionchanged:: 3.9
       This method now accepts zero for *k*.

Doc/library/shlex.rst

@@ -61,6 +61,20 @@ The :mod:`shlex` module defines the following functions:
    string that can safely be used as one token in a shell command line, for
    cases where you cannot use a list.
 
+   .. _shlex-quote-warning:
+
+   .. warning::
+
+      The ``shlex`` module is **only designed for Unix shells**.
+
+      The :func:`quote` function is not guaranteed to be correct on non-POSIX
+      compliant shells or shells from other operating systems such as Windows.
+      Executing commands quoted by this module on such shells can open up the
+      possibility of a command injection vulnerability.
+
+      Consider using functions that pass command arguments with lists such as
+      :func:`subprocess.run` with ``shell=False``.
+
    This idiom would be unsafe:
 
       >>> filename = 'somefile; rm -rf ~'

Doc/library/shutil.rst

@@ -218,7 +218,7 @@ Directory and files operations
       copy the file more efficiently. See
       :ref:`shutil-platform-dependent-efficient-copy-operations` section.
 
-.. function:: ignore_patterns(\*patterns)
+.. function:: ignore_patterns(*patterns)
 
    This factory function creates a function that can be used as a callable for
    :func:`copytree`\'s *ignore* argument, ignoring files and directories that

Doc/library/signal.rst

@@ -117,7 +117,7 @@ The variables defined in the :mod:`signal` module are:
 
    Child process stopped or terminated.
 
-   .. availability:: Windows.
+   .. availability:: Unix.
 
 .. data:: SIGCLD
 

Doc/library/smtplib.rst

@@ -32,7 +32,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
    than a success code, an :exc:`SMTPConnectError` is raised. The optional
    *timeout* parameter specifies a timeout in seconds for blocking operations
    like the connection attempt (if not specified, the global default timeout
-   setting will be used).  If the timeout expires, :exc:`socket.timeout` is
+   setting will be used).  If the timeout expires, :exc:`TimeoutError` is
    raised.  The optional source_address parameter allows binding
    to some specific source address in a machine with multiple network
    interfaces, and/or to some specific source TCP port. It takes a 2-tuple
@@ -115,7 +115,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
       If the *timeout* parameter is set to be zero, it will raise a
       :class:`ValueError` to prevent the creation of a non-blocking socket
 
-.. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None,
+.. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None, \
                 source_address=None[, timeout])
 
    The LMTP protocol, which is very similar to ESMTP, is heavily based on the

Doc/library/socket.rst

@@ -56,12 +56,12 @@ created.  Socket addresses are represented as follows:
   bytes-like object can be used for either type of address when
   passing it as an argument.
 
-   .. versionchanged:: 3.3
-      Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8
-      encoding.
+  .. versionchanged:: 3.3
+     Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8
+     encoding.
 
-   .. versionchanged:: 3.5
-      Writable :term:`bytes-like object` is now accepted.
+  .. versionchanged:: 3.5
+     Writable :term:`bytes-like object` is now accepted.
 
 .. _host_port:
 
@@ -283,6 +283,8 @@ Exceptions
 
 .. exception:: timeout
 
+   A deprecated alias of :exc:`TimeoutError`.
+
    A subclass of :exc:`OSError`, this exception is raised when a timeout
    occurs on a socket which has had timeouts enabled via a prior call to
    :meth:`~socket.settimeout` (or implicitly through
@@ -292,6 +294,9 @@ Exceptions
    .. versionchanged:: 3.3
       This class was made a subclass of :exc:`OSError`.
 
+   .. versionchanged:: 3.10
+      This class was made an alias of :exc:`TimeoutError`.
+
 
 Constants
 ^^^^^^^^^
@@ -1208,7 +1213,7 @@ to sockets.
    address family --- see above.)
 
    If the connection is interrupted by a signal, the method waits until the
-   connection completes, or raise a :exc:`socket.timeout` on timeout, if the
+   connection completes, or raise a :exc:`TimeoutError` on timeout, if the
    signal handler doesn't raise an exception and the socket is blocking or has
    a timeout. For non-blocking sockets, the method raises an
    :exc:`InterruptedError` exception if the connection is interrupted by a

Doc/library/sqlite3.rst

@@ -198,7 +198,9 @@ Module functions and constants
 
    *detect_types* defaults to 0 (i. e. off, no type detection), you can set it to
    any combination of :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES` to turn
-   type detection on.
+   type detection on. Due to SQLite behaviour, types can't be detected for generated
+   fields (for example ``max(data)``), even when *detect_types* parameter is set. In
+   such case, the returned type is :class:`str`.
 
    By default, *check_same_thread* is :const:`True` and only the creating thread may
    use the connection. If set :const:`False`, the returned connection may be shared

Doc/library/statistics.rst

@@ -156,10 +156,11 @@ However, for reading convenience, most of the examples show sorted sequences.
    .. versionadded:: 3.8
 
 
-.. function:: harmonic_mean(data)
+.. function:: harmonic_mean(data, weights=None)
 
    Return the harmonic mean of *data*, a sequence or iterable of
-   real-valued numbers.
+   real-valued numbers.  If *weights* is omitted or *None*, then
+   equal weighting is assumed.
 
    The harmonic mean, sometimes called the subcontrary mean, is the
    reciprocal of the arithmetic :func:`mean` of the reciprocals of the
@@ -179,17 +180,17 @@ However, for reading convenience, most of the examples show sorted sequences.
       >>> harmonic_mean([40, 60])
       48.0
 
-   Suppose an investor purchases an equal value of shares in each of
-   three companies, with P/E (price/earning) ratios of 2.5, 3 and 10.
-   What is the average P/E ratio for the investor's portfolio?
+   Suppose a car travels 40 km/hr for 5 km, and when traffic clears,
+   speeds-up to 60 km/hr for the remaining 30 km of the journey. What
+   is the average speed?
 
    .. doctest::
 
-      >>> harmonic_mean([2.5, 3, 10])  # For an equal investment portfolio.
-      3.6
+      >>> harmonic_mean([40, 60], weights=[5, 30])
+      56.0
 
-   :exc:`StatisticsError` is raised if *data* is empty, or any element
-   is less than zero.
+   :exc:`StatisticsError` is raised if *data* is empty, any element
+   is less than zero, or if the weighted sum isn't positive.
 
    The current algorithm has an early-out when it encounters a zero
    in the input.  This means that the subsequent inputs are not tested
@@ -197,6 +198,8 @@ However, for reading convenience, most of the examples show sorted sequences.
 
    .. versionadded:: 3.6
 
+   .. versionchanged:: 3.8
+      Added support for *weights*.
 
 .. function:: median(data)
 

Doc/library/stdtypes.rst

@@ -499,7 +499,7 @@ class`. In addition, it provides a few more methods:
 
     .. versionadded:: 3.10
 
-.. method:: int.to_bytes(length, byteorder, \*, signed=False)
+.. method:: int.to_bytes(length, byteorder, *, signed=False)
 
     Return an array of bytes representing an integer.
 
@@ -531,7 +531,7 @@ class`. In addition, it provides a few more methods:
 
     .. versionadded:: 3.2
 
-.. classmethod:: int.from_bytes(bytes, byteorder, \*, signed=False)
+.. classmethod:: int.from_bytes(bytes, byteorder, *, signed=False)
 
     Return the integer represented by the given array of bytes.
 
@@ -5065,7 +5065,7 @@ instantiated from the type::
 
       >>> class M(type):
       ...     def __or__(self, other):
-      ...     return "Hello"
+      ...         return "Hello"
       ...
       >>> class C(metaclass=M):
       ...     pass
@@ -5353,8 +5353,8 @@ types, where they are relevant.  Some of these are not reported by the
 .. method:: class.__subclasses__
 
    Each class keeps a list of weak references to its immediate subclasses.  This
-   method returns a list of all those references still alive.
-   Example::
+   method returns a list of all those references still alive.  The list is in
+   definition order.  Example::
 
       >>> int.__subclasses__()
       [<class 'bool'>]

Doc/library/string.rst

@@ -384,10 +384,10 @@ following:
 
 The ``'#'`` option causes the "alternate form" to be used for the
 conversion.  The alternate form is defined differently for different
-types.  This option is only valid for integer, float, complex and
-Decimal types. For integers, when binary, octal, or hexadecimal output
+types.  This option is only valid for integer, float and complex
+types. For integers, when binary, octal, or hexadecimal output
 is used, this option adds the prefix respective ``'0b'``, ``'0o'``, or
-``'0x'`` to the output value. For floats, complex and Decimal the
+``'0x'`` to the output value. For float and complex the
 alternate form causes the result of the conversion to always contain a
 decimal-point character, even if no digits follow it. Normally, a
 decimal-point character appears in the result of these conversions
@@ -476,20 +476,36 @@ with the floating point presentation types listed below (except
 ``'n'`` and ``None``). When doing so, :func:`float` is used to convert the
 integer to a floating point number before formatting.
 
-The available presentation types for floating point and decimal values are:
+The available presentation types for :class:`float` and
+:class:`~decimal.Decimal` values are:
 
    +---------+----------------------------------------------------------+
    | Type    | Meaning                                                  |
    +=========+==========================================================+
-   | ``'e'`` | Exponent notation. Prints the number in scientific       |
-   |         | notation using the letter 'e' to indicate the exponent.  |
-   |         | The default precision is ``6``.                          |
+   | ``'e'`` | Scientific notation. For a given precision ``p``,        |
+   |         | formats the number in scientific notation with the       |
+   |         | letter 'e' separating the coefficient from the exponent. |
+   |         | The coefficient has one digit before and ``p`` digits    |
+   |         | after the decimal point, for a total of ``p + 1``        |
+   |         | significant digits. With no precision given, uses a      |
+   |         | precision of ``6`` digits after the decimal point for    |
+   |         | :class:`float`, and shows all coefficient digits         |
+   |         | for :class:`~decimal.Decimal`. If no digits follow the   |
+   |         | decimal point, the decimal point is also removed unless  |
+   |         | the ``#`` option is used.                                |
    +---------+----------------------------------------------------------+
-   | ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an     |
-   |         | upper case 'E' as the separator character.               |
+   | ``'E'`` | Scientific notation. Same as ``'e'`` except it uses      |
+   |         | an upper case 'E' as the separator character.            |
    +---------+----------------------------------------------------------+
-   | ``'f'`` | Fixed-point notation. Displays the number as a           |
-   |         | fixed-point number.  The default precision is ``6``.     |
+   | ``'f'`` | Fixed-point notation. For a given precision ``p``,       |
+   |         | formats the number as a decimal number with exactly      |
+   |         | ``p`` digits following the decimal point. With no        |
+   |         | precision given, uses a precision of ``6`` digits after  |
+   |         | the decimal point for :class:`float`, and uses a         |
+   |         | precision large enough to show all coefficient digits    |
+   |         | for :class:`~decimal.Decimal`. If no digits follow the   |
+   |         | decimal point, the decimal point is also removed unless  |
+   |         | the ``#`` option is used.                                |
    +---------+----------------------------------------------------------+
    | ``'F'`` | Fixed-point notation. Same as ``'f'``, but converts      |
    |         | ``nan`` to  ``NAN`` and ``inf`` to ``INF``.              |
@@ -498,6 +514,8 @@ The available presentation types for floating point and decimal values are:
    |         | this rounds the number to ``p`` significant digits and   |
    |         | then formats the result in either fixed-point format     |
    |         | or in scientific notation, depending on its magnitude.   |
+   |         | A precision of ``0`` is treated as equivalent to a       |
+   |         | precision of ``1``.                                      |
    |         |                                                          |
    |         | The precise rules are as follows: suppose that the       |
    |         | result formatted with presentation type ``'e'`` and      |
@@ -512,13 +530,19 @@ The available presentation types for floating point and decimal values are:
    |         | removed if there are no remaining digits following it,   |
    |         | unless the ``'#'`` option is used.                       |
    |         |                                                          |
+   |         | With no precision given, uses a precision of ``6``       |
+   |         | significant digits for :class:`float`. For               |
+   |         | :class:`~decimal.Decimal`, the coefficient of the result |
+   |         | is formed from the coefficient digits of the value;      |
+   |         | scientific notation is used for values smaller than      |
+   |         | ``1e-6`` in absolute value and values where the place    |
+   |         | value of the least significant digit is larger than 1,   |
+   |         | and fixed-point notation is used otherwise.              |
+   |         |                                                          |
    |         | Positive and negative infinity, positive and negative    |
    |         | zero, and nans, are formatted as ``inf``, ``-inf``,      |
    |         | ``0``, ``-0`` and ``nan`` respectively, regardless of    |
    |         | the precision.                                           |
-   |         |                                                          |
-   |         | A precision of ``0`` is treated as equivalent to a       |
-   |         | precision of ``1``.  The default precision is ``6``.     |
    +---------+----------------------------------------------------------+
    | ``'G'`` | General format. Same as ``'g'`` except switches to       |
    |         | ``'E'`` if the number gets too large. The                |
@@ -531,12 +555,18 @@ The available presentation types for floating point and decimal values are:
    | ``'%'`` | Percentage. Multiplies the number by 100 and displays    |
    |         | in fixed (``'f'``) format, followed by a percent sign.   |
    +---------+----------------------------------------------------------+
-   | None    | Similar to ``'g'``, except that fixed-point notation,    |
-   |         | when used, has at least one digit past the decimal point.|
-   |         | The default precision is as high as needed to represent  |
-   |         | the particular value. The overall effect is to match the |
-   |         | output of :func:`str` as altered by the other format     |
-   |         | modifiers.                                               |
+   | None    | For :class:`float` this is the same as ``'g'``, except   |
+   |         | that when fixed-point notation is used to format the     |
+   |         | result, it always includes at least one digit past the   |
+   |         | decimal point. The precision used is as large as needed  |
+   |         | to represent the given value faithfully.                 |
+   |         |                                                          |
+   |         | For :class:`~decimal.Decimal`, this is the same as       |
+   |         | either ``'g'`` or ``'G'`` depending on the value of      |
+   |         | ``context.capitals`` for the current decimal context.    |
+   |         |                                                          |
+   |         | The overall effect is to match the output of :func:`str` |
+   |         | as altered by the other format modifiers.                |
    +---------+----------------------------------------------------------+
 
 

Doc/library/subprocess.rst

@@ -339,7 +339,7 @@ functions.
                  stderr=None, preexec_fn=None, close_fds=True, shell=False, \
                  cwd=None, env=None, universal_newlines=None, \
                  startupinfo=None, creationflags=0, restore_signals=True, \
-                 start_new_session=False, pass_fds=(), \*, group=None, \
+                 start_new_session=False, pass_fds=(), *, group=None, \
                  extra_groups=None, user=None, umask=-1, \
                  encoding=None, errors=None, text=None, pipesize=-1)
 
@@ -718,11 +718,8 @@ If the shell is invoked explicitly, via ``shell=True``, it is the application's
 responsibility to ensure that all whitespace and metacharacters are
 quoted appropriately to avoid
 `shell injection <https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
-vulnerabilities.
-
-When using ``shell=True``, the :func:`shlex.quote` function can be
-used to properly escape whitespace and shell metacharacters in strings
-that are going to be used to construct shell commands.
+vulnerabilities. On :ref:`some platforms <shlex-quote-warning>`, it is possible
+to use :func:`shlex.quote` for this escaping.
 
 
 Popen Objects
@@ -1190,8 +1187,9 @@ calls these functions.
    The arguments shown above are merely some common ones.
    The full function signature is largely the same as that of :func:`run` -
    most arguments are passed directly through to that interface.
-   However, explicitly passing ``input=None`` to inherit the parent's
-   standard input file handle is not supported.
+   One API deviation from :func:`run` behavior exists: passing ``input=None``
+   will behave the same as ``input=b''`` (or ``input=''``, depending on other
+   arguments) rather than using the parent's standard input file handle.
 
    By default, this function will return the data as encoded bytes. The actual
    encoding of the output data may depend on the command being invoked, so the
@@ -1284,7 +1282,7 @@ be used directly:
 
 becomes::
 
-   output=check_output("dmesg | grep hda", shell=True)
+   output = check_output("dmesg | grep hda", shell=True)
 
 
 Replacing :func:`os.system`

Doc/library/symtable.rst

@@ -156,7 +156,7 @@ Examining Symbol Tables
 
       Return ``True`` if the symbol is local to its block.
 
-    .. method:: is_annotated()
+   .. method:: is_annotated()
 
       Return ``True`` if the symbol is annotated.