Merge remote-tracking branch 'upstream/master' into doc-8264

2021-01-01 23:08:09 +08:00 · 2021-01-01 23:08:09 +08:00 · d7399d585b
parent 2c5f6acfaf ec3165320e
commit d7399d585b
650 changed files with 21084 additions and 11506 deletions
--- a/.azure-pipelines/docs-steps.yml
+++ b/.azure-pipelines/docs-steps.yml
@ -12,7 +12,7 @@ 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') }}:
@ -31,7 +31,7 @@ steps:
 - ${{ if eq(parameters.upload, 'true') }}:
  - task: PublishBuildArtifacts@1
    displayName: 'Publish docs'
-  
+
    inputs:
      PathToPublish: '$(build.sourcesDirectory)/Doc/build'
      ArtifactName: docs
--- a/.github/CODEOWNERS
+++ b/.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

--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@ -7,3 +7,7 @@ updates:
    labels:
      - "skip issue"
      - "skip news"
+    target_branch:
+      - "master"
+      - "3.9"
+      - "3.8"
--- a/.github/problem-matchers/msvc.json
+++ b/.github/problem-matchers/msvc.json
@ -0,0 +1,19 @@
+{
+    "__comment": "Taken from vscode's vs/workbench/contrib/tasks/common/problemMatcher.ts msCompile rule",
+    "problemMatcher": [
+      {
+        "owner": "msvc-problem-matcher",
+        "pattern": [
+          {
+            "regexp": "^(?:\\s+\\d+\\>)?([^\\s].*)\\((\\d+),?(\\d+)?(?:,\\d+,\\d+)?\\)\\s*:\\s+(error|warning|info)\\s+(\\w{1,2}\\d+)\\s*:\\s*(.*)$",
+            "file": 1,
+            "line": 2,
+            "column": 3,
+            "severity": 4,
+            "code": 5,
+            "message": 6
+          }
+        ]
+      }
+    ]
+  }
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@ -28,7 +28,7 @@ jobs:
      - name: Check for source changes
        id: check
        run: |
-          if [ -z "GITHUB_BASE_REF" ]; then
+          if [ -z "$GITHUB_BASE_REF" ]; then
            echo '::set-output name=run_tests::true'
          else
            git fetch origin $GITHUB_BASE_REF --depth=1
@ -75,6 +75,8 @@ jobs:
          fi
      - name: Check exported libpython symbols
        run: make smelly
+      - name: Check limited ABI symbols
+        run: make check-limited-abi

  build_win32:
    name: 'Windows (x86)'
@ -97,6 +99,8 @@ jobs:
    if: needs.check_source.outputs.run_tests == 'true'
    steps:
    - uses: actions/checkout@v2
+    - name: Register MSVC problem matcher
+      run: echo "::add-matcher::.github/problem-matchers/msvc.json"
    - name: Build CPython
      run: .\PCbuild\build.bat -e -p x64
    - name: Display build info
@ -135,7 +139,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 }}
--- a/.github/workflows/coverage.yml
+++ b/.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 }}
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@ -38,7 +38,7 @@ jobs:
    - name: 'Build documentation'
      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
--- a/.github/workflows/stale.yml
+++ b/.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
--- a/.travis.yml
+++ b/.travis.yml
@ -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
--- a/Doc/Makefile
+++ b/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
--- a/Doc/c-api/tuple.rst
+++ b/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)
--- a/Doc/conf.py
+++ b/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:
--- a/Doc/data/stable_abi.dat
+++ b/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
--- a/Doc/howto/argparse.rst
+++ b/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
--- a/Doc/howto/descriptor.rst
+++ b/Doc/howto/descriptor.rst
@ -934,32 +934,42 @@ here is a pure Python equivalent:
            if doc is None and fget is not None:
                doc = fget.__doc__
            self.__doc__ = doc
+            self._name = ''
+
+        def __set_name__(self, owner, name):
+            self._name = name

        def __get__(self, obj, objtype=None):
            if obj is None:
                return self
            if self.fget is None:
-                raise AttributeError("unreadable attribute")
+                raise AttributeError(f'unreadable attribute {self._name}')
            return self.fget(obj)

        def __set__(self, obj, value):
            if self.fset is None:
-                raise AttributeError("can't set attribute")
+                raise AttributeError(f"can't set attribute {self._name}")
            self.fset(obj, value)

        def __delete__(self, obj):
            if self.fdel is None:
-                raise AttributeError("can't delete attribute")
+                raise AttributeError(f"can't delete attribute {self._name}")
            self.fdel(obj)

        def getter(self, fget):
-            return type(self)(fget, self.fset, self.fdel, self.__doc__)
+            prop = type(self)(fget, self.fset, self.fdel, self.__doc__)
+            prop._name = self._name
+            return prop

        def setter(self, fset):
-            return type(self)(self.fget, fset, self.fdel, self.__doc__)
+            prop = type(self)(self.fget, fset, self.fdel, self.__doc__)
+            prop._name = self._name
+            return prop

        def deleter(self, fdel):
-            return type(self)(self.fget, self.fset, fdel, self.__doc__)
+            prop = type(self)(self.fget, self.fset, fdel, self.__doc__)
+            prop._name = self._name
+            return prop

 .. testcode::
    :hide:
--- a/Doc/library/abc.rst
+++ b/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::

--- a/Doc/library/argparse.rst
+++ b/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:
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@ -1576,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
@ -1588,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.

--- a/Doc/library/asyncio-eventloop.rst
+++ b/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
--- a/Doc/library/asyncio-future.rst
+++ b/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.
--- a/Doc/library/asyncio-policy.rst
+++ b/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.

--- a/Doc/library/asyncio-queue.rst
+++ b/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>`.

--- a/Doc/library/asyncio-stream.rst
+++ b/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.

--- a/Doc/library/asyncio-subprocess.rst
+++ b/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
--- a/Doc/library/asyncio-sync.rst
+++ b/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.
-
 ---------


--- a/Doc/library/asyncio-task.rst
+++ b/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,7 +593,7 @@ 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.

@ -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.

--- a/Doc/library/base64.rst
+++ b/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`.
--- a/Doc/library/bz2.rst
+++ b/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
--- a/Doc/library/compileall.rst
+++ b/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.
--- a/Doc/library/concurrent.futures.rst
+++ b/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
--- a/Doc/library/contextvars.rst
+++ b/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
--- a/Doc/library/ctypes.rst
+++ b/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.

--- a/Doc/library/datetime.rst
+++ b/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
--- a/Doc/library/dialog.rst
+++ b/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
--- a/Doc/library/difflib.rst
+++ b/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*.
--- a/Doc/library/dis.rst
+++ b/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

--- a/Doc/library/doctest.rst
+++ b/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,
--- a/Doc/library/email.contentmanager.rst
+++ b/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)
--- a/Doc/library/email.header.rst
+++ b/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
--- a/Doc/library/email.headerregistry.rst
+++ b/Doc/library/email.headerregistry.rst
@ -289,7 +289,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
    A :class:`ParameterizedMIMEHeader` class that handles the
    :mailheader:`Content-Disposition` header.

-    .. attribute:: content-disposition
+    .. attribute:: content_disposition

       ``inline`` and ``attachment`` are the only valid values in common use.

--- a/Doc/library/email.policy.rst
+++ b/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
--- a/Doc/library/enum.rst
+++ b/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
 """"""""""""""""""""

--- a/Doc/library/exceptions.rst
+++ b/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:
             ...
--- a/Doc/library/fnmatch.rst
+++ b/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.


--- a/Doc/library/functions.rst
+++ b/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:
@ -1340,7 +1341,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
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@ -62,16 +62,26 @@ The :mod:`functools` module defines the following functions:
   Example::

       class DataSet:
+
           def __init__(self, sequence_of_numbers):
-               self._data = sequence_of_numbers
+               self._data = tuple(sequence_of_numbers)

           @cached_property
           def stdev(self):
               return statistics.stdev(self._data)

-           @cached_property
-           def variance(self):
-               return statistics.variance(self._data)
+   The mechanics of :func:`cached_property` are somewhat different from
+   :func:`property`.  A regular property blocks attribute writes unless a
+   setter is defined. In contrast, a *cached_property* allows writes.
+
+   The *cached_property* decorator only runs on lookups and only when an
+   attribute of the same name doesn't exist.  When it does run, the
+   *cached_property* writes to the attribute with the same name. Subsequent
+   attribute reads and writes take precedence over the *cached_property*
+   method and it works like a normal attribute.
+
+   The cached value can be cleared by deleting the attribute.  This
+   allows the *cached_property* method to run again.

   Note, this decorator interferes with the operation of :pep:`412`
   key-sharing dictionaries.  This means that instance dictionaries
--- a/Doc/library/http.cookies.rst
+++ b/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
--- a/Doc/library/importlib.metadata.rst
+++ b/Doc/library/importlib.metadata.rst
@ -115,8 +115,9 @@ Every distribution includes some metadata, which you can extract using the

    >>> wheel_metadata = metadata('wheel')  # doctest: +SKIP

-The keys of the returned data structure [#f1]_ name the metadata keywords, and
-their values are returned unparsed from the distribution metadata::
+The keys of the returned data structure, a ``PackageMetadata``,
+name the metadata keywords, and
+the values are returned unparsed from the distribution metadata::

    >>> wheel_metadata['Requires-Python']  # doctest: +SKIP
    '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
@ -206,9 +207,9 @@ Thus, an alternative way to get the version number is through the
 There are all kinds of additional metadata available on the ``Distribution``
 instance::

-    >>> d.metadata['Requires-Python']  # doctest: +SKIP
+    >>> dist.metadata['Requires-Python']  # doctest: +SKIP
    '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
-    >>> d.metadata['License']  # doctest: +SKIP
+    >>> dist.metadata['License']  # doctest: +SKIP
    'MIT'

 The full set of available metadata is not described here.  See :pep:`566`
@ -259,9 +260,3 @@ a custom finder, return instances of this derived ``Distribution`` in the


 .. rubric:: Footnotes
-
-.. [#f1] Technically, the returned distribution metadata object is an
-         :class:`email.message.EmailMessage`
-         instance, but this is an implementation detail, and not part of the
-         stable API.  You should only use dictionary-like methods and syntax
-         to access the metadata contents.
--- a/Doc/library/importlib.rst
+++ b/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
--- a/Doc/library/inspect.rst
+++ b/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.
--- a/Doc/library/io.rst
+++ b/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`.
--- a/Doc/library/itertools.rst
+++ b/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 = tuple(kernel)[::-1]
+       n = len(kernel)
+       window = collections.deque([0], maxlen=n) * 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:
--- a/Doc/library/logging.config.rst
+++ b/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

--- a/Doc/library/logging.rst
+++ b/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`.          |
--- a/Doc/library/lzma.rst
+++ b/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.

--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@ -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:

--- a/Doc/library/os.rst
+++ b/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::

@ -1323,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.

@ -1991,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
@ -2498,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
@ -2522,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
@ -2552,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
@ -2584,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
--- a/Doc/library/pickle.rst
+++ b/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.

--- a/Doc/library/pipes.rst
+++ b/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:


--- a/Doc/library/platform.rst
+++ b/Doc/library/platform.rst
@ -253,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
--- a/Doc/library/plistlib.rst
+++ b/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
--- a/Doc/library/profile.rst
+++ b/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:

--- a/Doc/library/pyexpat.rst
+++ b/Doc/library/pyexpat.rst
@ -665,14 +665,14 @@ The ``errors`` module has the following attributes:

 .. data:: codes

-   A dictionary mapping numeric error codes to their string descriptions.
+   A dictionary mapping string descriptions to their error codes.

   .. versionadded:: 3.2


 .. data:: messages

-   A dictionary mapping string descriptions to their error codes.
+   A dictionary mapping numeric error codes to their string descriptions.

   .. versionadded:: 3.2

--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@ -135,6 +135,15 @@ Functions for integers
      values.  Formerly it used a style like ``int(random()*n)`` which could produce
      slightly uneven distributions.

+   .. deprecated:: 3.10
+      The automatic conversion of non-integer types to equivalent integers is
+      deprecated.  Currently ``randrange(10.0)`` is losslessly converted to
+      ``randrange(10)``.  In the future, this will raise a :exc:`TypeError`.
+
+   .. deprecated:: 3.10
+      The exception raised for non-integral values such as ``range(10.5)``
+      will be changed from :exc:`ValueError` to :exc:`TypeError`.
+
 .. function:: randint(a, b)

   Return a random integer *N* such that ``a <= N <= b``.  Alias for
@ -142,10 +151,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*.
--- a/Doc/library/shutil.rst
+++ b/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
--- a/Doc/library/socket.rst
+++ b/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:

@ -907,11 +907,9 @@ The :mod:`socket` module also offers various network-related services:
   where the host byte order is the same as network byte order, this is a no-op;
   otherwise, it performs a 2-byte swap operation.

-   .. deprecated:: 3.7
-      In case *x* does not fit in 16-bit unsigned integer, but does fit in a
-      positive C int, it is silently truncated to 16-bit unsigned integer.
-      This silent truncation feature is deprecated, and will raise an
-      exception in future versions of Python.
+   .. versionchanged:: 3.10
+      Raises :exc:`OverflowError` if *x* does not fit in a 16-bit unsigned
+      integer.


 .. function:: htonl(x)
@ -927,11 +925,9 @@ The :mod:`socket` module also offers various network-related services:
   where the host byte order is the same as network byte order, this is a no-op;
   otherwise, it performs a 2-byte swap operation.

-   .. deprecated:: 3.7
-      In case *x* does not fit in 16-bit unsigned integer, but does fit in a
-      positive C int, it is silently truncated to 16-bit unsigned integer.
-      This silent truncation feature is deprecated, and will raise an
-      exception in future versions of Python.
+   .. versionchanged:: 3.10
+      Raises :exc:`OverflowError` if *x* does not fit in a 16-bit unsigned
+      integer.


 .. function:: inet_aton(ip_string)
--- a/Doc/library/sqlite3.rst
+++ b/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
@ -544,7 +546,7 @@ Connection Objects
         con.close()


-   .. method:: backup(target, *, pages=0, progress=None, name="main", sleep=0.250)
+   .. method:: backup(target, *, pages=-1, progress=None, name="main", sleep=0.250)

      This method makes a backup of a SQLite database even while it's being accessed
      by other clients, or concurrently by the same connection.  The copy will be
--- a/Doc/library/statistics.rst
+++ b/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)

--- a/Doc/library/stdtypes.rst
+++ b/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.

@ -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'>]
--- a/Doc/library/string.rst
+++ b/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.                |
   +---------+----------------------------------------------------------+


--- a/Doc/library/subprocess.rst
+++ b/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)

@ -1187,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
@ -1281,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`
--- a/Doc/library/symtable.rst
+++ b/Doc/library/symtable.rst
@ -156,10 +156,12 @@ 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.

+      .. versionadded:: 3.6
+
   .. method:: is_free()

      Return ``True`` if the symbol is referenced in its block, but not assigned
--- a/Doc/library/sysconfig.rst
+++ b/Doc/library/sysconfig.rst
@ -32,7 +32,7 @@ can be accessed using :func:`get_config_vars` or :func:`get_config_var`.

 Notice that on Windows, it's a much smaller set.

-.. function:: get_config_vars(\*args)
+.. function:: get_config_vars(*args)

   With no arguments, return a dictionary of all configuration variables
   relevant for the current platform.
--- a/Doc/library/tarfile.rst
+++ b/Doc/library/tarfile.rst
@ -37,7 +37,7 @@ Some facts and figures:
   Added support for :mod:`lzma` compression.


-.. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, \*\*kwargs)
+.. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

   Return a :class:`TarFile` object for the pathname *name*. For detailed
   information on :class:`TarFile` objects and the keyword arguments that are
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@ -453,7 +453,7 @@ The :mod:`test.support` module defines the following functions:
   Define match test with regular expression *patterns*.


-.. function:: run_unittest(\*classes)
+.. function:: run_unittest(*classes)

   Execute :class:`unittest.TestCase` subclasses passed to the function. The
   function scans the classes for methods starting with the prefix ``test_``
@ -1599,7 +1599,7 @@ The :mod:`test.support.warnings_helper` module provides support for warnings tes
   .. versionadded:: 3.8


-.. function:: check_warnings(\*filters, quiet=True)
+.. function:: check_warnings(*filters, quiet=True)

   A convenience wrapper for :func:`warnings.catch_warnings()` that makes it
   easier to test that a warning was correctly raised.  It is approximately
--- a/Doc/library/tkinter.font.rst
+++ b/Doc/library/tkinter.font.rst
@ -91,6 +91,9 @@ The different font weights and slants are:

   Return the names of defined fonts.

-.. function:: nametofont(name)
+.. function:: nametofont(name, root=None)

-   Return a :class:`Font` representation of a tk named font.
+   Return a :class:`Font` representation of a tk named font.
+
+   .. versionchanged:: 3.10
+      The *root* parameter was added.
--- a/Doc/library/trace.rst
+++ b/Doc/library/trace.rst
@ -153,47 +153,47 @@ Programmatic Interface
   count information.  *timing* enables a timestamp relative to when tracing was
   started to be displayed.

-    .. method:: run(cmd)
+   .. method:: run(cmd)

-       Execute the command and gather statistics from the execution with
-       the current tracing parameters.  *cmd* must be a string or code object,
-       suitable for passing into :func:`exec`.
+      Execute the command and gather statistics from the execution with
+      the current tracing parameters.  *cmd* must be a string or code object,
+      suitable for passing into :func:`exec`.

-    .. method:: runctx(cmd, globals=None, locals=None)
+   .. method:: runctx(cmd, globals=None, locals=None)

-       Execute the command and gather statistics from the execution with the
-       current tracing parameters, in the defined global and local
-       environments.  If not defined, *globals* and *locals* default to empty
-       dictionaries.
+      Execute the command and gather statistics from the execution with the
+      current tracing parameters, in the defined global and local
+      environments.  If not defined, *globals* and *locals* default to empty
+      dictionaries.

-    .. method:: runfunc(func, /, *args, **kwds)
+   .. method:: runfunc(func, /, *args, **kwds)

-       Call *func* with the given arguments under control of the :class:`Trace`
-       object with the current tracing parameters.
+      Call *func* with the given arguments under control of the :class:`Trace`
+      object with the current tracing parameters.

-    .. method:: results()
+   .. method:: results()

-       Return a :class:`CoverageResults` object that contains the cumulative
-       results of all previous calls to ``run``, ``runctx`` and ``runfunc``
-       for the given :class:`Trace` instance.  Does not reset the accumulated
-       trace results.
+      Return a :class:`CoverageResults` object that contains the cumulative
+      results of all previous calls to ``run``, ``runctx`` and ``runfunc``
+      for the given :class:`Trace` instance.  Does not reset the accumulated
+      trace results.

 .. class:: CoverageResults

   A container for coverage results, created by :meth:`Trace.results`.  Should
   not be created directly by the user.

-    .. method:: update(other)
+   .. method:: update(other)

-       Merge in data from another :class:`CoverageResults` object.
+      Merge in data from another :class:`CoverageResults` object.

-    .. method:: write_results(show_missing=True, summary=False, coverdir=None)
+   .. method:: write_results(show_missing=True, summary=False, coverdir=None)

-       Write coverage results.  Set *show_missing* to show lines that had no
-       hits.  Set *summary* to include in the output the coverage summary per
-       module.  *coverdir* specifies the directory into which the coverage
-       result files will be output.  If ``None``, the results for each source
-       file are placed in its directory.
+      Write coverage results.  Set *show_missing* to show lines that had no
+      hits.  Set *summary* to include in the output the coverage summary per
+      module.  *coverdir* specifies the directory into which the coverage
+      result files will be output.  If ``None``, the results for each source
+      file are placed in its directory.

 A simple example demonstrating the use of the programmatic interface::

--- a/Doc/library/turtle.rst
+++ b/Doc/library/turtle.rst
@ -913,8 +913,8 @@ Color control
      Set pencolor to the RGB color represented by *r*, *g*, and *b*.  Each of
      *r*, *g*, and *b* must be in the range 0..colormode.

-    If turtleshape is a polygon, the outline of that polygon is drawn with the
-    newly set pencolor.
+   If turtleshape is a polygon, the outline of that polygon is drawn with the
+   newly set pencolor.

   .. doctest::
      :skipif: _tkinter is None
@ -962,8 +962,8 @@ Color control
      Set fillcolor to the RGB color represented by *r*, *g*, and *b*.  Each of
      *r*, *g*, and *b* must be in the range 0..colormode.

-    If turtleshape is a polygon, the interior of that polygon is drawn
-    with the newly set fillcolor.
+   If turtleshape is a polygon, the interior of that polygon is drawn
+   with the newly set fillcolor.

   .. doctest::
      :skipif: _tkinter is None
@ -1001,8 +1001,8 @@ Color control
      Equivalent to ``pencolor(colorstring1)`` and ``fillcolor(colorstring2)``
      and analogously if the other input format is used.

-    If turtleshape is a polygon, outline and interior of that polygon is drawn
-    with the newly set colors.
+   If turtleshape is a polygon, outline and interior of that polygon is drawn
+   with the newly set colors.

   .. doctest::
      :skipif: _tkinter is None
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@ -280,6 +280,10 @@ Standard names are defined for the following types:

   .. versionadded:: 3.9

+   .. versionchanged:: 3.9.2
+      This type can now be subclassed.
+
+
 .. data:: Union

   The type of :ref:`union type expressions<types-union>`.
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@ -262,9 +262,10 @@ the *new_callable* argument to :func:`patch`.
      this is a new Mock (created on first access). See the
      :attr:`return_value` attribute.

-    * *unsafe*: By default if any attribute starts with *assert* or
-      *assret* will raise an :exc:`AttributeError`. Passing ``unsafe=True``
-      will allow access to these attributes.
+    * *unsafe*: By default, accessing any attribute with name starting with
+      *assert*, *assret*, *asert*, *aseert* or *assrt* will raise an
+      :exc:`AttributeError`. Passing ``unsafe=True`` will allow access to
+      these attributes.

      .. versionadded:: 3.5

--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@ -491,7 +491,7 @@ Available Functions
 Available Context Managers
 --------------------------

-.. class:: catch_warnings(\*, record=False, module=None)
+.. class:: catch_warnings(*, record=False, module=None)

    A context manager that copies and, upon exit, restores the warnings filter
    and the :func:`showwarning` function.
--- a/Doc/library/winreg.rst
+++ b/Doc/library/winreg.rst
@ -791,7 +791,7 @@ integer handle, and also disconnect the Windows handle from the handle object.


 .. method:: PyHKEY.__enter__()
-            PyHKEY.__exit__(\*exc_info)
+            PyHKEY.__exit__(*exc_info)

   The HKEY object implements :meth:`~object.__enter__` and
   :meth:`~object.__exit__` and thus supports the context protocol for the
--- a/Doc/library/xml.dom.minidom.rst
+++ b/Doc/library/xml.dom.minidom.rst
@ -174,7 +174,7 @@ module documentation.  This section lists the differences between the API and
      The :meth:`toxml` method now preserves the attribute order specified
      by the user.

-.. method:: Node.toprettyxml(indent="\\t", newl="\\n", encoding=None, \
+.. method:: Node.toprettyxml(indent="\t", newl="\n", encoding=None, \
                             standalone=None)

   Return a pretty-printed version of the document. *indent* specifies the
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@ -483,7 +483,7 @@ Path Objects
 Path objects expose the following features of :mod:`pathlib.Path`
 objects:

-Path objects are traversable using the ``/`` operator.
+Path objects are traversable using the ``/`` operator or ``joinpath``.

 .. attribute:: Path.name

@ -532,6 +532,19 @@ Path objects are traversable using the ``/`` operator.

   Read the current file as bytes.

+.. method:: Path.joinpath(*other)
+
+   Return a new Path object with each of the *other* arguments
+   joined. The following are equivalent::
+
+   >>> Path(...).joinpath('child').joinpath('grandchild')
+   >>> Path(...).joinpath('child', 'grandchild')
+   >>> Path(...) / 'child' / 'grandchild'
+
+   .. versionchanged:: 3.10
+      Prior to 3.10, ``joinpath`` was undocumented and accepted
+      exactly one parameter.
+

 .. _pyzipfile-objects:

--- a/Doc/library/zipimport.rst
+++ b/Doc/library/zipimport.rst
@ -121,7 +121,7 @@ zipimporter Objects
   .. method:: get_code(fullname)

      Return the code object for the specified module. Raise
-      :exc:`ZipImportError` if the module couldn't be found.
+      :exc:`ZipImportError` if the module couldn't be imported.


   .. method:: get_data(pathname)
@ -137,7 +137,7 @@ zipimporter Objects

      Return the value ``__file__`` would be set to if the specified module
      was imported. Raise :exc:`ZipImportError` if the module couldn't be
-      found.
+      imported.

      .. versionadded:: 3.1

@ -159,14 +159,13 @@ zipimporter Objects
   .. method:: load_module(fullname)

      Load the module specified by *fullname*. *fullname* must be the fully
-      qualified (dotted) module name. It returns the imported module, or raises
-      :exc:`ZipImportError` if it wasn't found.
+      qualified (dotted) module name. Returns the imported module on success,
+      raises :exc:`ZipImportError` on failure.

      .. deprecated:: 3.10

         Use :meth:`exec_module` instead.

-
   .. attribute:: archive

      The file name of the importer's associated ZIP file, without a possible
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@ -254,7 +254,8 @@ present, must be last; it matches any exception.  For an except clause with an
 expression, that expression is evaluated, and the clause matches the exception
 if the resulting object is "compatible" with the exception.  An object is
 compatible with an exception if it is the class or a base class of the exception
-object or a tuple containing an item compatible with the exception.
+object, or a tuple containing an item that is the class or a base class of
+the exception object.

 If no except clause matches the exception, the search for an exception handler
 continues in the surrounding code and on the invocation stack.  [#]_
@ -301,9 +302,27 @@ Before an except clause's suite is executed, details about the exception are
 stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`.
 :func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the
 exception instance and a traceback object (see section :ref:`types`) identifying
-the point in the program where the exception occurred.  :func:`sys.exc_info`
-values are restored to their previous values (before the call) when returning
-from a function that handled an exception.
+the point in the program where the exception occurred.  The details about the
+exception accessed via :func:`sys.exc_info` are restored to their previous values
+when leaving an exception handler::
+
+   >>> print(sys.exc_info())
+   (None, None, None)
+   >>> try:
+   ...     raise TypeError
+   ... except:
+   ...     print(sys.exc_info())
+   ...     try:
+   ...          raise ValueError
+   ...     except:
+   ...         print(sys.exc_info())
+   ...     print(sys.exc_info())
+   ...
+   (<class 'TypeError'>, TypeError(), <traceback object at 0x10efad080>)
+   (<class 'ValueError'>, ValueError(), <traceback object at 0x10efad040>)
+   (<class 'TypeError'>, TypeError(), <traceback object at 0x10efad080>)
+   >>> print(sys.exc_info())
+   (None, None, None)

 .. index::
   keyword: else
@ -796,12 +815,12 @@ The :keyword:`!async for` statement
 .. productionlist:: python-grammar
   async_for_stmt: "async" `for_stmt`

-An :term:`asynchronous iterable` is able to call asynchronous code in its
-*iter* implementation, and :term:`asynchronous iterator` can call asynchronous
-code in its *next* method.
+An :term:`asynchronous iterable` provides an ``__aiter__`` method that directly
+returns an :term:`asynchronous iterator`, which can call asynchronous code in
+its ``__anext__`` method.

 The ``async for`` statement allows convenient iteration over asynchronous
-iterators.
+iterables.

 The following code::

--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@ -217,7 +217,6 @@ Ellipsis
      There are two types of integers:

      Integers (:class:`int`)
-
         These represent numbers in an unlimited range, subject to available (virtual)
         memory only.  For the purpose of shift and mask operations, a binary
         representation is assumed, and negative numbers are represented in a variant of
--- a/Doc/reference/grammar.rst
+++ b/Doc/reference/grammar.rst
@ -13,7 +13,8 @@ In particular, ``&`` followed by a symbol, token or parenthesized
 group indicates a positive lookahead (i.e., is required to match but
 not consumed), while ``!`` indicates a negative lookahead (i.e., is
 required _not_ to match).  We use the ``|`` separator to mean PEG's
-"ordered choice" (written as ``/`` in traditional PEG grammars).
+"ordered choice" (written as ``/`` in traditional PEG grammars). See
+:pep:`617` for more details on the grammar's syntax.

 .. literalinclude:: ../../Grammar/python.gram
  :language: peg
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@ -950,7 +950,7 @@ Names listed in a :keyword:`global` statement must not be used in the same code
 block textually preceding that :keyword:`!global` statement.

 Names listed in a :keyword:`global` statement must not be defined as formal
-parameters or in a :keyword:`for` loop control target, :keyword:`class`
+parameters, or as targets in :keyword:`with` statements or :keyword:`except` clauses, or in a :keyword:`for` target list, :keyword:`class`
 definition, function definition, :keyword:`import` statement, or variable
 annotation.

--- a/Doc/tools/extensions/glossary_search.py
+++ b/Doc/tools/extensions/glossary_search.py
@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""
+    glossary_search.py
+    ~~~~~~~~~~~~~~~~
+
+    Feature search results for glossary items prominently.
+
+    :license: Python license.
+"""
+from os import path
+from sphinx.addnodes import glossary
+from sphinx.util import logging
+from docutils.nodes import definition_list_item
+import json
+
+
+logger = logging.getLogger(__name__)
+
+
+def process_glossary_nodes(app, doctree, fromdocname):
+    if app.builder.format != 'html':
+        return
+
+    terms = {}
+
+    for node in doctree.traverse(glossary):
+        for glossary_item in node.traverse(definition_list_item):
+            term = glossary_item[0].astext().lower()
+            definition = glossary_item[1]
+
+            rendered = app.builder.render_partial(definition)
+            terms[term] = {
+                'title': glossary_item[0].astext(),
+                'body': rendered['html_body']
+            }
+
+    if hasattr(app.env, 'glossary_terms'):
+        app.env.glossary_terms.update(terms)
+    else:
+        app.env.glossary_terms = terms
+
+def on_build_finish(app, exc):
+    if not hasattr(app.env, 'glossary_terms'):
+        return
+    if not app.env.glossary_terms:
+        return
+
+    logger.info('Writing glossary.json', color='green')
+    with open(path.join(app.outdir, '_static', 'glossary.json'), 'w') as f:
+        json.dump(app.env.glossary_terms, f)
+
+
+def setup(app):
+    app.connect('doctree-resolved', process_glossary_nodes)
+    app.connect('build-finished', on_build_finish)
+
+    return {'version': '0.1', 'parallel_read_safe': True}
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@ -394,7 +394,12 @@ class DeprecatedRemoved(Directive):
                                   translatable=False)
            node.append(para)
        env = self.state.document.settings.env
-        env.get_domain('changeset').note_changeset(node)
+        # deprecated pre-Sphinx-2 method
+        if hasattr(env, 'note_versionchange'):
+            env.note_versionchange('deprecated', version[0], node, self.lineno)
+        # new method
+        else:
+            env.get_domain('changeset').note_changeset(node)
        return [node] + messages


--- a/Doc/tools/rstlint.py
+++ b/Doc/tools/rstlint.py
@ -13,6 +13,7 @@ import os
 import re
 import sys
 import getopt
+from string import ascii_letters
 from os.path import join, splitext, abspath, exists
 from collections import defaultdict

@ -128,6 +129,81 @@ def check_leaked_markup(fn, lines):
            yield lno+1, 'possibly leaked markup: %r' % line


+def hide_literal_blocks(lines):
+    """Tool to remove literal blocks from given lines.
+
+    It yields empty lines in place of blocks, so line numbers are
+    still meaningful.
+    """
+    in_block = False
+    for line in lines:
+        if line.endswith("::\n"):
+            in_block = True
+        elif in_block:
+            if line == "\n" or line.startswith(" "):
+                line = "\n"
+            else:
+                in_block = False
+        yield line
+
+
+def type_of_explicit_markup(line):
+    if re.match(fr'\.\. {all_directives}::', line):
+        return 'directive'
+    if re.match(r'\.\. \[[0-9]+\] ', line):
+        return 'footnote'
+    if re.match(r'\.\. \[[^\]]+\] ', line):
+        return 'citation'
+    if re.match(r'\.\. _.*[^_]: ', line):
+        return 'target'
+    if re.match(r'\.\. \|[^\|]*\| ', line):
+        return 'substitution_definition'
+    return 'comment'
+
+
+def hide_comments(lines):
+    """Tool to remove comments from given lines.
+
+    It yields empty lines in place of comments, so line numbers are
+    still meaningfull.
+    """
+    in_multiline_comment = False
+    for line in lines:
+        if line == "..\n":
+            in_multiline_comment = True
+        elif in_multiline_comment:
+            if line == "\n" or line.startswith(" "):
+                line = "\n"
+            else:
+                in_multiline_comment = False
+        if line.startswith(".. ") and type_of_explicit_markup(line) == 'comment':
+            line = "\n"
+        yield line
+
+
+
+@checker(".rst", severity=2)
+def check_missing_surrogate_space_on_plural(fn, lines):
+    r"""Check for missing 'backslash-space' between a code sample a letter.
+
+    Good: ``Point``\ s
+    Bad: ``Point``s
+    """
+    in_code_sample = False
+    check_next_one = False
+    for lno, line in enumerate(hide_comments(hide_literal_blocks(lines))):
+        tokens = line.split("``")
+        for token_no, token in enumerate(tokens):
+            if check_next_one:
+                if token[0] in ascii_letters:
+                    yield lno + 1, f"Missing backslash-space between code sample and {token!r}."
+                check_next_one = False
+            if token_no == len(tokens) - 1:
+                continue
+            if in_code_sample:
+                check_next_one = True
+            in_code_sample = not in_code_sample
+
 def main(argv):
    usage = '''\
 Usage: %s [-v] [-f] [-s sev] [-i path]* [path]
--- a/Doc/tools/templates/search.html
+++ b/Doc/tools/templates/search.html
@ -0,0 +1,48 @@
+{% extends "!search.html" %}
+{% block extrahead %}
+    {{ super() }}
+    <script type="text/javascript">
+        var GLOSSARY_PAGE = 'glossary.html';
+
+        jQuery(function() {
+            $.getJSON("_static/glossary.json", function(glossary) {
+                var RESULT_TEMPLATE = '<div style="display: none" class="admonition seealso" id="glossary-result">' + 
+                                      '  <p class="topic-title">' +
+                                      '    <a class="glossary-title" href="#"></a>' +
+                                      '  </p>' +
+                                      '  <div class="glossary-body"></div>' +
+                                      '</div>';
+                $("#search-results").prepend(RESULT_TEMPLATE);
+
+                var params = $.getQueryParameters();
+                if (params.q) {
+                    var search_param = params.q[0].toLowerCase();
+                    var glossary_item = glossary[search_param];
+                    if (glossary_item) {
+                        var resultDiv = $("#glossary-result");
+                        
+                        // set up the title text with a link to the glossary page
+                        resultDiv.find(".glossary-title").text('Glossary: ' + glossary_item.title);
+                        var link_target = search_param.replace(/ /g, '-');
+                        resultDiv.find(".glossary-title").attr(
+                            'href', GLOSSARY_PAGE + '#term-' + link_target
+                        );
+
+                        // rewrite any anchor links (to other glossary terms)
+                        // to have a full reference to the glossary page
+                        var body = $(glossary_item.body).children();
+                        body.find("a[href^='#']").each(function() {
+                            var current_url = $(this).attr('href');
+                            $(this).attr('href', GLOSSARY_PAGE + current_url);
+                        });
+                        resultDiv.find(".glossary-body").html(body);
+
+                        resultDiv.show();
+                    } else {
+                        $("#glossary-result").hide('');
+                    }
+                }
+            });
+        });
+    </script>
+{% endblock %}
--- a/Doc/tutorial/datastructures.rst
+++ b/Doc/tutorial/datastructures.rst
@ -78,7 +78,7 @@ objects:
   Return the number of times *x* appears in the list.


-.. method:: list.sort(key=None, reverse=False)
+.. method:: list.sort(*, key=None, reverse=False)
   :noindex:

   Sort the items of the list in place (the arguments can be used for sort
--- a/Doc/tutorial/errors.rst
+++ b/Doc/tutorial/errors.rst
@ -281,17 +281,17 @@ chaining exceptions. For example::
 This can be useful when you are transforming exceptions. For example::

    >>> def func():
-    ...     raise IOError
+    ...     raise ConnectionError
    ...
    >>> try:
    ...     func()
-    ... except IOError as exc:
+    ... except ConnectionError as exc:
    ...     raise RuntimeError('Failed to open database') from exc
    ...
    Traceback (most recent call last):
      File "<stdin>", line 2, in <module>
      File "<stdin>", line 2, in func
-    OSError
+    ConnectionError
    <BLANKLINE>
    The above exception was the direct cause of the following exception:
    <BLANKLINE>
@ -300,7 +300,7 @@ This can be useful when you are transforming exceptions. For example::
    RuntimeError: Failed to open database

 Exception chaining happens automatically when an exception is raised inside an
-:keyword:`except` or :keyword:`finally` section. Exception chaining can be
+:keyword:`except` or :keyword:`finally` section. This can be
 disabled by using ``from None`` idiom:

    >>> try:
--- a/Doc/tutorial/inputoutput.rst
+++ b/Doc/tutorial/inputoutput.rst
@ -329,11 +329,16 @@ equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::

 If you're not using the :keyword:`with` keyword, then you should call
 ``f.close()`` to close the file and immediately free up any system
-resources used by it. If you don't explicitly close a file, Python's
-garbage collector will eventually destroy the object and close the
-open file for you, but the file may stay open for a while.  Another
-risk is that different Python implementations will do this clean-up at
-different times.
+resources used by it.
+
+.. warning::
+   Calling ``f.write()`` without using the :keyword:`!with` keyword or calling
+   ``f.close()`` **might** result in the arguments
+   of ``f.write()`` not being completely written to the disk, even if the
+   program exits successfully.
+
+..
+   See also https://bugs.python.org/issue17852

 After a file object is closed, either by a :keyword:`with` statement
 or by calling ``f.close()``, attempts to use the file object will
--- a/Doc/using/windows.rst
+++ b/Doc/using/windows.rst
@ -23,8 +23,8 @@ available for application-local distributions.

 As specified in :pep:`11`, a Python release only supports a Windows platform
 while Microsoft considers the platform under extended support. This means that
-Python |version| supports Windows Vista and newer. If you require Windows XP
-support then please install Python 3.4.
+Python |version| supports Windows 8.1 and newer. If you require Windows 7
+support, please install Python 3.8.

 There are a number of different installers available for Windows, each with
 certain benefits and downsides.
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@ -179,6 +179,21 @@ codecs
 Add a :func:`codecs.unregister` function to unregister a codec search function.
 (Contributed by Hai Shi in :issue:`41842`.)

+collections.abc
+---------------
+
+The ``__args__`` of the :ref:`parameterized generic <types-genericalias>` for
+:class:`collections.abc.Callable` are now consistent with :data:`typing.Callable`.
+:class:`collections.abc.Callable` generic now flattens type parameters, similar
+to what :data:`typing.Callable` currently does.  This means that
+``collections.abc.Callable[[int, str], str]`` will have ``__args__`` of
+``(int, str, str)``; previously this was ``([int, str], str)``.  To allow this
+change, :class:`types.GenericAlias` can now be subclassed, and a subclass will
+be returned when subscripting the :class:`collections.abc.Callable` type.  Note
+that a :exc:`TypeError` may be raised for invalid forms of parameterizing
+:class:`collections.abc.Callable` which may have passed silently in Python 3.9.
+(Contributed by Ken Jin in :issue:`42195`.)
+
 contextlib
 ----------

@ -223,6 +238,11 @@ inspect
 When a module does not define ``__loader__``, fall back to ``__spec__.loader``.
 (Contributed by Brett Cannon in :issue:`42133`.)

+Added *globalns* and *localns* parameters in :func:`~inspect.signature` and
+:meth:`inspect.Signature.from_callable` to retrieve the annotations in given
+local and global namespaces.
+(Contributed by Batuhan Taskaya in :issue:`41960`.)
+
 linecache
 ---------

@ -254,6 +274,14 @@ Added negative indexing support to :attr:`PurePath.parents
 <pathlib.PurePath.parents>`.
 (Contributed by Yaroslav Pankovych in :issue:`21041`)

+platform
+--------
+
+Added :func:`platform.freedesktop_os_release()` to retrieve operation system
+identification from `freedesktop.org os-release
+<https://www.freedesktop.org/software/systemd/man/os-release.html>`_ standard file.
+(Contributed by Christian Heimes in :issue:`28468`)
+
 py_compile
 ----------

@ -386,7 +414,8 @@ Optimizations
  with ``gcc`` by up to 30%. See `this article
  <https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/>`_
  for more details. (Contributed by Victor Stinner and Pablo Galindo in
-  :issue:`38980`)
+  :issue:`38980`.)
+

 * Function parameters and their annotations are no longer computed at runtime,
  but rather at compilation time.  They are stored as a tuple of strings at the
@ -413,6 +442,21 @@ Deprecated
  as appropriate to help identify code which needs updating during
  this transition.

+* The various ``load_module()`` methods of :mod:`importlib` have been
+  documented as deprecated since Python 3.6, but will now also trigger
+  a :exc:`DeprecationWarning`. Use
+  :meth:`~importlib.abc.Loader.exec_module` instead.
+  (Contributed by Brett Cannon in :issue:`26131`.)
+
+* :meth:`zimport.zipimporter.load_module` has been deprecated in
+  preference for :meth:`~zipimport.zipimporter.exec_module`.
+  (Contributed by Brett Cannon in :issue:`26131`.)
+
+* The use of :meth:`~importlib.abc.Loader.load_module` by the import
+  system now triggers an :exc:`ImportWarning` as
+  :meth:`~importlib.abc.Loader.exec_module` is preferred.
+  (Contributed by Brett Cannon in :issue:`26131`.)
+
 * ``sqlite3.OptimizedUnicode`` has been undocumented and obsolete since Python
  3.3, when it was made an alias to :class:`str`.  It is now deprecated,
  scheduled for removal in Python 3.12.
@ -456,6 +500,11 @@ Removed
  into their code.
  (Contributed by Dong-hee Na and Terry J. Reedy in :issue:`42299`.)

+* Removed the :c:func:`PyModule_GetWarningsModule` function that was useless
+  now due to the _warnings module was converted to a builtin module in 2.6.
+  (Contributed by Hai Shi in :issue:`42599`.)
+
+
 Porting to Python 3.10
 ======================

@ -472,6 +521,28 @@ Changes in the Python API
  have been renamed to *exc*.
  (Contributed by Zackery Spytz and Matthias Bussonnier in :issue:`26389`.)

+* :mod:`atexit`: At Python exit, if a callback registered with
+  :func:`atexit.register` fails, its exception is now logged. Previously, only
+  some exceptions were logged, and the last exception was always silently
+  ignored.
+  (Contributed by Victor Stinner in :issue:`42639`.)
+
+* :class:`collections.abc.Callable` generic now flattens type parameters, similar
+  to what :data:`typing.Callable` currently does.  This means that
+  ``collections.abc.Callable[[int, str], str]`` will have ``__args__`` of
+  ``(int, str, str)``; previously this was ``([int, str], str)``.  Code which
+  accesses the arguments via :func:`typing.get_args` or ``__args__`` need to account
+  for this change.  Furthermore, :exc:`TypeError` may be raised for invalid forms
+  of parameterizing :class:`collections.abc.Callable` which may have passed
+  silently in Python 3.9.
+  (Contributed by Ken Jin in :issue:`42195`.)
+
+* :meth:`socket.htons` and :meth:`socket.ntohs` now raise :exc:`OverflowError`
+  instead of :exc:`DeprecationWarning` if the given parameter will not fit in
+  a 16-bit unsigned integer.
+  (Contributed by Erlend E. Aasland in :issue:`42393`.)
+
+
 CPython bytecode changes
 ========================

@ -490,6 +561,12 @@ Build Changes
 * :mod:`sqlite3` requires SQLite 3.7.3 or higher.
  (Contributed by Sergey Fedoseev and Erlend E. Aasland :issue:`40744`.)

+* The :mod:`atexit` module must now always be built as a built-in module.
+  (Contributed by Victor Stinner in :issue:`42639`.)
+
+* Added ``--disable-test-modules`` option to the ``configure`` script:
+  don't build nor install test modules.
+  (Contributed by Xavier de Gaye, Thomas Petazzoni and Peixing Xin in :issue:`27640`.)


 C API Changes
@ -587,6 +664,13 @@ Porting to Python 3.10
  :ref:`Python Path Configuration.  <init-path-config>`.
  (Contributed by Victor Stinner in :issue:`42260`.)

+* :c:func:`PyList_SET_ITEM`, :c:func:`PyTuple_SET_ITEM` and
+  :c:func:`PyCell_SET` macros can no longer be used as l-value or r-value.
+  For example, ``x = PyList_SET_ITEM(a, b, c)`` and
+  ``PyList_SET_ITEM(a, b, c) = x`` now fail with a compiler error. It prevents
+  bugs like ``if (PyList_SET_ITEM (a, b, c) < 0) ...`` test.
+  (Contributed by Zackery Spytz and Victor Stinner in :issue:`30459`.)
+
 Deprecated
 ----------

--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@ -2113,9 +2113,6 @@ Changes in the C API

  (Contributed by Antoine Pitrou in :issue:`32388`.)

-* The :c:func:`PyCode_New` has a new parameter in the second position (*posonlyargcount*)
-  to support :pep:`570`, indicating the number of positional-only arguments.
-
 * The functions :c:func:`PyNode_AddChild` and :c:func:`PyParser_AddToken` now accept
  two additional ``int`` arguments *end_lineno* and *end_col_offset*.

--- a/Doc/whatsnew/3.9.rst
+++ b/Doc/whatsnew/3.9.rst
@ -1482,4 +1482,37 @@ and to match the behavior of static type checkers specified in the PEP.
        File "<stdin>", line 1, in <module>
      TypeError: unhashable type: 'set'

-(Contributed by Yurii Karabas in :issue:`42345`.)
+(Contributed by Yurii Karabas in :issue:`42345`.)
+
+macOS 11.0 (Big Sur) and Apple Silicon Mac support
+--------------------------------------------------
+
+As of 3.9.1, Python now fully supports building and running on macOS 11.0
+(Big Sur) and on Apple Silicon Macs (based on the ``ARM64`` architecture).
+A new universal build variant, ``universal2``, is now available to natively
+support both ``ARM64`` and ``Intel 64`` in one set of executables. Binaries
+can also now be built on current versions of macOS to be deployed on a range
+of older macOS versions (tested to 10.9) while making some newer OS
+functions and options conditionally available based on the operating system
+version in use at runtime ("weaklinking").
+
+(Contributed by Ronald Oussoren and Lawrence D'Anna in :issue:`41100`.)
+
+Notable changes in Python 3.9.2
+===============================
+
+collections.abc
+---------------
+
+:class:`collections.abc.Callable` generic now flattens type parameters, similar
+to what :data:`typing.Callable` currently does.  This means that
+``collections.abc.Callable[[int, str], str]`` will have ``__args__`` of
+``(int, str, str)``; previously this was ``([int, str], str)``.  To allow this
+change, :class:`types.GenericAlias` can now be subclassed, and a subclass will
+be returned when subscripting the :class:`collections.abc.Callable` type.
+Code which accesses the arguments via :func:`typing.get_args` or ``__args__``
+need to account for this change.  A :exc:`DeprecationWarning` may be emitted for
+invalid forms of parameterizing :class:`collections.abc.Callable` which may have
+passed silently in Python 3.9.1.  This :exc:`DeprecationWarning` will
+become a :exc:`TypeError` in Python 3.10.
+(Contributed by Ken Jin in :issue:`42195`.)
--- a/Show More
+++ b/Show More