Merge branch 'master' into fix-issue-30688

.gitattributes

@@ -27,9 +27,6 @@ Lib/test/test_email/data/*.txt -text
 Lib/test/xmltestdata/* -text
 Lib/test/coding20731.py -text
 
-# Special files in third party code
-Modules/zlib/zlib.map -text
-
 # CRLF files
 *.bat text eol=crlf
 *.ps1 text eol=crlf

.github/CODEOWNERS

@@ -0,0 +1,53 @@
+# See https://help.github.com/articles/about-codeowners/
+# for more info about CODEOWNERS file
+
+# It uses the same pattern rule for gitignore file
+# https://git-scm.com/docs/gitignore#_pattern_format
+
+# asyncio
+**/*asyncio*                  @1st1
+
+# Core
+**/*genobject*                @1st1
+
+# Hashing
+**/*hashlib*                  @python/crypto-team
+**/*pyhash*                   @python/crypto-team
+
+# Import (including importlib)
+**/*import*                   @python/import-team
+
+# SSL
+**/*ssl*                      @python/crypto-team
+
+# CSPRNG
+Python/bootstrap_hash.c       @python/crypto-team
+
+# Email and related
+**/*mail*                     @python/email-team
+**/*smtp*                     @python/email-team
+**/*mime*                     @python/email-team
+**/*imap*                     @python/email-team
+**/*poplib*                   @python/email-team
+
+# subprocess
+**/*subprocess*               @gpshead
+
+# Windows
+/PC/                          @python/windows-team
+/PCbuild/                     @python/windows-team
+
+# Windows installer packages
+/Tools/msi/                   @python/windows-team
+/Tools/nuget/                 @python/windows-team
+
+**/*itertools*                @rhettinger
+**/*collections*              @rhettinger
+**/*random*                   @rhettinger
+**/*queue*                    @rhettinger
+**/*bisect*                   @rhettinger
+**/*heapq*                    @rhettinger
+**/*functools*                @ncoghlan @rhettinger
+**/*decimal*                  @rhettinger @skrah
+
+**/*idlelib*                  @terryjreedy

.github/CODE_OF_CONDUCT.rst

@@ -0,0 +1,14 @@
+Code of Conduct
+===============
+
+Please note that all interactions on
+`Python Software Foundation <https://www.python.org/psf-landing/>`__-supported
+infrastructure is `covered
+<https://www.python.org/psf/records/board/minutes/2014-01-06/#management-of-the-psfs-web-properties>`__
+by the `PSF Code of Conduct <https://www.python.org/psf/codeofconduct/>`__,
+which includes all infrastructure used in the development of Python itself
+(e.g. mailing lists, issue trackers, GitHub, etc.).
+
+In general this means everyone is expected to be open, considerate, and
+respectful of others no matter what their position is within the project.
+

.github/CONTRIBUTING.rst

@@ -12,31 +12,47 @@ Build Status
 
   + `Stable buildbots <http://buildbot.python.org/3.6.stable/>`_
 
-- 3.5
-
-  + `Stable buildbots <http://buildbot.python.org/3.5.stable/>`_
-
 - 2.7
 
   + `Stable buildbots <http://buildbot.python.org/2.7.stable/>`_
 
 
+Thank You
+---------
+First off, thanks for contributing to the maintenance of the Python programming
+language and the CPython interpreter! Even if your contribution is not
+ultimately accepted, the fact you put time and effort into helping out is
+greatly appreciated.
+
+
 Contribution Guidelines
 -----------------------
-Please read the `devguide <https://cpython-devguide.readthedocs.io/>`_ for
+Please read the `devguide <https://devguide.python.org/>`_ for
 guidance on how to contribute to this project. The documentation covers
 everything from how to build the code to submitting a pull request. There are
 also suggestions on how you can most effectively help the project.
 
 Please be aware that our workflow does deviate slightly from the typical GitHub
 project. Details on how to properly submit a pull request are covered in
-`Lifecycle of a Pull Request <https://cpython-devguide.readthedocs.io/pullrequest.html>`_.
+`Lifecycle of a Pull Request <https://devguide.python.org/pullrequest/>`_.
-One key point is to keep comments on GitHub to only those related to the reviewing
+We utilize various bots and status checks to help with this, so do follow the
-the code in the pull request. All other discussions -- e.g. about the issue being
+comments they leave and their "Details" links, respectively. The key points of
-fixed -- should happen on bugs.python.org.
+our workflow that are not covered by a bot or status check are:
 
-If you are making a code contribution or large documentation contribution,
+- All discussions that are not directly related to the code in the pull request
-please feel free to add yourself to the ``Misc/ACKS`` file alphabetically.
+  should happen on bugs.python.org
+- Upon your first non-trivial pull request (which includes documentation changes),
+  feel free to add yourself to ``Misc/ACKS``
+
+
+Setting Expectations
+--------------------
+Due to the fact that this project is entirely volunteer-run (i.e. no one is paid
+to work on Python full-time), we unfortunately can make no guarantees as to if
+or when a core developer will get around to reviewing your pull request.
+If no core developer has done a review or responded to changes made because of a
+"changes requested" review, please feel free to email python-dev to ask if
+someone could take a look at your pull request.
 
 
 Code of Conduct

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+!!! If this is a backport PR (PR made against branches other than `master`),
+please ensure that the PR title is in the following format:
+```
+[X.Y] <title from the original PR> (GH-NNNN)
+```
+Where: [X.Y] is the branch name, e.g. [3.6].
+
+GH-NNNN refers to the PR number from `master`.
+
+PLEASE: Remove this headline!!!

.github/appveyor.yml

@@ -5,10 +5,17 @@ branches:
     - master
     - /\d\.\d/
     - buildbot-custom
+cache:
+  - externals -> PCbuild\*
 build_script:
 - cmd: PCbuild\build.bat -e
+- cmd: PCbuild\win32\python.exe -m test.pythoninfo
 test_script:
-- cmd: PCbuild\rt.bat -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
+- cmd: PCbuild\rt.bat -q -uall -u-cpu -rwW --slowest --timeout=1200 --fail-env-changed -j0
+environment:
+  HOST_PYTHON: C:\Python36\python.exe
+image:
+- Visual Studio 2017
 
 # Only trigger AppVeyor if actual code or its configuration changes
 only_commits:
@@ -21,7 +28,7 @@ only_commits:
     - Modules/
     - Objects/
     - PC/
-    - PCBuild/
+    - PCbuild/
     - Parser/
     - Programs/
     - Python/

.gitignore

@@ -19,6 +19,9 @@
 .gdb_history
 Doc/build/
 Doc/venv/
+Doc/.venv/
+Doc/env/
+Doc/.env/
 Include/pydtrace_probes.h
 Lib/distutils/command/*.pdb
 Lib/lib2to3/*.pickle
@@ -60,7 +63,7 @@ PCbuild/*.VC.opendb
 PCbuild/.vs/
 PCbuild/amd64/
 PCbuild/obj/
-PCBuild/win32/
+PCbuild/win32/
 .purify
 Parser/pgen
 Parser/pgen.exe

.mention-bot

@@ -1,20 +0,0 @@
-{
-  "numFilesToCheck": 10,
-  "findPotentialReviewers": true,
-  "fileBlacklist": [
-    "Misc/ACKS",
-    "Misc/NEWS",
-    "Doc/whatsnew/*.rst"
-  ],
-  "userBlacklist": ["gvanrossum", "skrah", "haypo"],
-  "userBlacklistForPR": ["benjaminp", "skrah", "berkerpeksag"],
-  "alwaysNotifyForPaths": [
-    {"name": "tiran",
-     "files": [
-       "Doc/library/hashlib.rst", "Doc/library/ssl.rst", "Lib/hashlib.py",
-       "Lib/ssl.py", "Lib/test/test_hashlib.py", "Lib/test/test_ssl.py",
-       "Modules/_hashopenssl.c", "Modules/_ssl*", "Modules/hashlib.h",
-       "Python/pyhash.c", "Include/pyhash.h"]
-    }
-  ]
-}

.travis.yml

@@ -3,8 +3,10 @@ dist: trusty
 sudo: false
 group: beta
 
-# To cache doc-building dependencies.
+# To cache doc-building dependencies and C compiler output.
-cache: pip
+cache:
+    - pip
+    - ccache
 
 branches:
   only:
@@ -23,15 +25,6 @@ matrix:
       # compiler here and the other to run the coverage build. Clang is preferred
       # in this instance for its better error messages.
       env: TESTING=cpython
-    - os: osx
-      language: c
-      compiler: clang
-      # Testing under macOS is optional until testing stability has been demonstrated.
-      env: OPTIONAL=true
-      before_install:
-        - brew install openssl xz
-        - export CPPFLAGS="-I$(brew --prefix openssl)/include"
-        - export LDFLAGS="-L$(brew --prefix openssl)/lib"
     - os: linux
       language: python
       # Build the docs against a stable version of Python so code bugs don't hold up doc-related PRs.
@@ -41,7 +34,7 @@ matrix:
         - cd Doc
         # Sphinx is pinned so that new versions that introduce new warnings won't suddenly cause build failures.
         # (Updating the version is fine as long as no warnings are raised by doing so.)
-        - python -m pip install sphinx~=1.6.1
+        - python -m pip install sphinx~=1.6.1 blurb
       script:
         - make check suspicious html SPHINXOPTS="-q -W -j4"
     - os: linux
@@ -60,9 +53,10 @@ matrix:
             # Need a venv that can parse covered code.
             ./python -m venv venv
             ./venv/bin/python -m pip install -U coverage
+            ./venv/bin/python -m test.pythoninfo
       script:
         # Skip tests that re-run the entire test suite.
-        - ./venv/bin/python -m coverage run --pylib -m test -uall,-cpu,-tzdata -x test_multiprocessing_fork -x test_multiprocessing_forkserver -x test_multiprocessing_spawn
+        - ./venv/bin/python -m coverage run --pylib -m test --fail-env-changed -uall,-cpu -x test_multiprocessing_fork -x test_multiprocessing_forkserver -x test_multiprocessing_spawn -x test_concurrent_futures
       after_script:  # Probably should be after_success once test suite updated to run under coverage.py.
         # Make the `coverage` command available to Codecov w/ a version of Python that can parse all source files.
         - source ./venv/bin/activate
@@ -87,10 +81,18 @@ before_script:
         echo "$changes"
         exit 1
       fi
+      make pythoninfo
 
 script:
+  # Using the built Python as patchcheck.py is built around the idea of using
+  # a checkout-build of CPython to know things like what base branch the changes
+  # should be compared against.
+  # Only run on Linux as the check only needs to be run once.
+  - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then ./python Tools/scripts/patchcheck.py --travis $TRAVIS_PULL_REQUEST; fi
   # `-r -w` implicitly provided through `make buildbottest`.
-  - make buildbottest TESTOPTS="-j4 -uall,-cpu,-tzdata"
+  - make buildbottest TESTOPTS="-j4 -uall,-cpu"
+  # Check that all symbols exported by libpython start with "Py" or "_Py"
+  - make smelly
 
 notifications:
   email: false

Doc/Makefile

@@ -5,7 +5,9 @@
 
 # You can set these variables from the command line.
 PYTHON       = python3
-SPHINXBUILD  = sphinx-build
+VENVDIR      = ./venv
+SPHINXBUILD  = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
+BLURB        = PATH=$(VENVDIR)/bin:$$PATH blurb
 PAPER        =
 SOURCES      =
 DISTVERSION  = $(shell $(PYTHON) tools/extensions/patchlevel.py)
@@ -38,6 +40,20 @@ help:
 	@echo "  serve      to serve the documentation on the localhost (8000)"
 
 build:
+	-mkdir -p build
+# Look first for a Misc/NEWS file (building from a source release tarball
+# or old repo) and use that, otherwise look for a Misc/NEWS.d directory
+# (building from a newer repo) and use blurb to generate the NEWS file.
+	@if [ -f  ../Misc/NEWS ] ; then \
+		echo "Using existing Misc/NEWS file"; \
+		cp ../Misc/NEWS build/NEWS; \
+	elif [ -d ../Misc/NEWS.d ]; then \
+		echo "Building NEWS from Misc/NEWS.d with blurb"; \
+		$(BLURB) merge -f build/NEWS; \
+	else \
+		echo "Neither Misc/NEWS.d nor Misc/NEWS found; cannot build docs"; \
+		exit 1; \
+	fi
 	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 	@echo
 
@@ -103,11 +119,12 @@ htmlview: html
 	 $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
 
 clean:
-	-rm -rf build/* venv/*
+	-rm -rf build/* $(VENVDIR)/*
 
 venv:
-	$(PYTHON) -m venv venv
+	$(PYTHON) -m venv $(VENVDIR)
-	./venv/bin/python3 -m pip install -U Sphinx
+	$(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb
+	@echo "The venv has been created in the $(VENVDIR) directory"
 
 dist:
 	rm -rf dist
@@ -153,7 +170,7 @@ dist:
 	cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
 
 check:
-	$(PYTHON) tools/rstlint.py -i tools -i venv -i README.rst
+	$(PYTHON) tools/rstlint.py -i tools -i $(VENVDIR) -i README.rst
 
 serve:
 	../Tools/scripts/serve.py build/html
@@ -167,12 +184,12 @@ serve:
 
 # for development releases: always build
 autobuild-dev:
-	make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A versionswitcher=1'
+	make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switchers=1'
 	-make suspicious
 
 # for quick rebuilds (HTML only)
 autobuild-dev-html:
-	make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A versionswitcher=1'
+	make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switchers=1'
 
 # for stable releases: only build if not in pre-release stage (alpha, beta)
 # release candidate downloads are okay, since the stable tree can be in that stage

Doc/README.rst

@@ -7,45 +7,53 @@ available <https://docs.python.org/dev/download.html>`_.
 
 Documentation on authoring Python documentation, including information about
 both style and markup, is available in the "`Documenting Python
-<https://docs.python.org/devguide/documenting.html>`_" chapter of the
+<https://devguide.python.org/documenting/>`_" chapter of the
 developers guide.
 
 
 Building the docs
 =================
 
-You need to have `Sphinx <http://sphinx-doc.org/>`_ installed; it is the toolset
+The documentation is built with several tools which are not included in this
-used to build the docs.  It is not included in this tree, but maintained
+tree but are maintained separately and are available from
-separately and `available from PyPI <https://pypi.python.org/pypi/Sphinx>`_.
+`PyPI <https://pypi.org/>`_.
+
+* `Sphinx <https://pypi.org/project/Sphinx/>`_
+* `blurb <https://pypi.org/project/blurb/>`_
+
+The easiest way to install these tools is to create a virtual environment and
+install the tools into there.
 
 
 Using make
 ----------
 
-A Makefile has been prepared so that on Unix, provided you have installed
+To get started on UNIX, you can create a virtual environment with the command ::
-Sphinx, you can just run ::
+
+  make venv
+
+That will install all the tools necessary to build the documentation. Assuming
+the virtual environment was created in the ``env`` directory (the default;
+configurable with the VENVDIR variable), you can run the following command to
+build the HTML output files::
 
   make html
 
-to build the HTML output files.
+By default, if the virtual environment is not created, the Makefile will
+look for instances of sphinxbuild and blurb installed on your process PATH
+(configurable with the SPHINXBUILD and BLURB variables).
 
 On Windows, we try to emulate the Makefile as closely as possible with a
-``make.bat`` file.
+``make.bat`` file. If you need to specify the Python interpreter to use,
-
+set the PYTHON environment variable instead.
-To use a Python interpreter that's not called ``python``, use the standard
-way to set Makefile variables, using e.g. ::
-
-   make html PYTHON=python3
-
-On Windows, set the PYTHON environment variable instead.
-
-To use a specific sphinx-build (something other than ``sphinx-build``), set
-the SPHINXBUILD variable.
 
 Available make targets are:
 
 * "clean", which removes all build files.
 
+* "venv", which creates a virtual environment with all necessary tools
+  installed.
+
 * "html", which builds standalone HTML files for offline viewing.
 
 * "htmlview", which re-uses the "html" builder, but then opens the main page
@@ -96,7 +104,7 @@ Available make targets are:
 Without make
 ------------
 
-Install the Sphinx package and its dependencies from PyPI.
+First, install the tool dependencies from PyPI.
 
 Then, from the ``Doc`` directory, run ::
 
@@ -112,8 +120,7 @@ Contributing
 Bugs in the content should be reported to the
 `Python bug tracker <https://bugs.python.org>`_.
 
-Bugs in the toolset should be reported in the 
+Bugs in the toolset should be reported to the tools themselves.
-`Sphinx bug tracker <https://github.com/sphinx-doc/sphinx/issues>`_.
 
 You can also send a mail to the Python Documentation Team at docs@python.org,
 and we will process your request as soon as possible.

Doc/bugs.rst

@@ -88,5 +88,5 @@ the `core-mentorship mailing list`_ is a friendly place to get answers to
 any and all questions pertaining to the process of fixing issues in Python.
 
 .. _Documentation bugs: https://bugs.python.org/issue?@filter=status&@filter=components&components=4&status=1&@columns=id,activity,title,status&@sort=-activity
-.. _Python Developer's Guide: https://docs.python.org/devguide/
+.. _Python Developer's Guide: https://devguide.python.org/
 .. _core-mentorship mailing list: https://mail.python.org/mailman/listinfo/core-mentorship/

Doc/c-api/buffer.rst

@@ -473,7 +473,7 @@ Buffer-related functions
    (*order* is ``'A'``).  Return ``0`` otherwise.
 
 
-.. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char order)
+.. c:function:: void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
 
    Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style if
    *order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the

Doc/c-api/datetime.rst

@@ -188,7 +188,7 @@ not be *NULL*, and the type is not checked:
    .. versionadded:: 3.3
 
 
-.. c:function:: int PyDateTime_DELTA_GET_MICROSECOND(PyDateTime_Delta *o)
+.. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)
 
    Return the number of microseconds, as an int from 0 through 999999.
 

Doc/c-api/import.rst

@@ -204,6 +204,13 @@ Importing Modules
    Return the dictionary used for the module administration (a.k.a.
    ``sys.modules``).  Note that this is a per-interpreter variable.
 
+.. c:function:: PyObject* PyImport_GetModule(PyObject *name)
+
+   Return the already imported module with the given name.  If the
+   module has not been imported yet then returns NULL but does not set
+   an error.  Returns NULL and sets an error if the lookup failed.
+
+   .. versionadded:: 3.7
 
 .. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
 

Doc/c-api/init.rst

@@ -1192,3 +1192,160 @@ These functions are only intended to be used by advanced debugging tools.
    Return the next thread state object after *tstate* from the list of all such
    objects belonging to the same :c:type:`PyInterpreterState` object.
 
+
+.. _thread-local-storage:
+
+Thread Local Storage Support
+============================
+
+.. sectionauthor:: Masayuki Yamamoto <ma3yuki.8mamo10@gmail.com>
+
+The Python interpreter provides low-level support for thread-local storage
+(TLS) which wraps the underlying native TLS implementation to support the
+Python-level thread local storage API (:class:`threading.local`).  The
+CPython C level APIs are similar to those offered by pthreads and Windows:
+use a thread key and functions to associate a :c:type:`void\*` value per
+thread.
+
+The GIL does *not* need to be held when calling these functions; they supply
+their own locking.
+
+Note that :file:`Python.h` does not include the declaration of the TLS APIs,
+you need to include :file:`pythread.h` to use thread-local storage.
+
+.. note::
+   None of these API functions handle memory management on behalf of the
+   :c:type:`void\*` values.  You need to allocate and deallocate them yourself.
+   If the :c:type:`void\*` values happen to be :c:type:`PyObject\*`, these
+   functions don't do refcount operations on them either.
+
+.. _thread-specific-storage-api:
+
+Thread Specific Storage (TSS) API
+---------------------------------
+
+TSS API is introduced to supersede the use of the existing TLS API within the
+CPython interpreter.  This API uses a new type :c:type:`Py_tss_t` instead of
+:c:type:`int` to represent thread keys.
+
+.. versionadded:: 3.7
+
+.. seealso:: "A New C-API for Thread-Local Storage in CPython" (:pep:`539`)
+
+
+.. c:type:: Py_tss_t
+
+   This data structure represents the state of a thread key, the definition of
+   which may depend on the underlying TLS implementation, and it has an
+   internal field representing the key's initialization state.  There are no
+   public members in this structure.
+
+   When :ref:`Py_LIMITED_API <stable>` is not defined, static allocation of
+   this type by :c:macro:`Py_tss_NEEDS_INIT` is allowed.
+
+
+.. c:macro:: Py_tss_NEEDS_INIT
+
+   This macro expands to the initializer for :c:type:`Py_tss_t` variables.
+   Note that this macro won't be defined with :ref:`Py_LIMITED_API <stable>`.
+
+
+Dynamic Allocation
+~~~~~~~~~~~~~~~~~~
+
+Dynamic allocation of the :c:type:`Py_tss_t`, required in extension modules
+built with :ref:`Py_LIMITED_API <stable>`, where static allocation of this type
+is not possible due to its implementation being opaque at build time.
+
+
+.. c:function:: Py_tss_t* PyThread_tss_alloc()
+
+   Return a value which is the same state as a value initialized with
+   :c:macro:`Py_tss_NEEDS_INIT`, or *NULL* in the case of dynamic allocation
+   failure.
+
+
+.. c:function:: void PyThread_tss_free(Py_tss_t *key)
+
+   Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after
+   first calling :c:func:`PyThread_tss_delete` to ensure any associated
+   thread locals have been unassigned. This is a no-op if the *key*
+   argument is `NULL`.
+
+   .. note::
+      A freed key becomes a dangling pointer, you should reset the key to
+      `NULL`.
+
+
+Methods
+~~~~~~~
+
+The parameter *key* of these functions must not be *NULL*.  Moreover, the
+behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are
+undefined if the given :c:type:`Py_tss_t` has not been initialized by
+:c:func:`PyThread_tss_create`.
+
+
+.. c:function:: int PyThread_tss_is_created(Py_tss_t *key)
+
+   Return a non-zero value if the given :c:type:`Py_tss_t` has been initialized
+   by :c:func:`PyThread_tss_create`.
+
+
+.. c:function:: int PyThread_tss_create(Py_tss_t *key)
+
+   Return a zero value on successful initialization of a TSS key.  The behavior
+   is undefined if the value pointed to by the *key* argument is not
+   initialized by :c:macro:`Py_tss_NEEDS_INIT`.  This function can be called
+   repeatedly on the same key -- calling it on an already initialized key is a
+   no-op and immediately returns success.
+
+
+.. c:function:: void PyThread_tss_delete(Py_tss_t *key)
+
+   Destroy a TSS key to forget the values associated with the key across all
+   threads, and change the key's initialization state to uninitialized.  A
+   destroyed key is able to be initialized again by
+   :c:func:`PyThread_tss_create`. This function can be called repeatedly on
+   the same key -- calling it on an already destroyed key is a no-op.
+
+
+.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value)
+
+   Return a zero value to indicate successfully associating a :c:type:`void\*`
+   value with a TSS key in the current thread.  Each thread has a distinct
+   mapping of the key to a :c:type:`void\*` value.
+
+
+.. c:function:: void* PyThread_tss_get(Py_tss_t *key)
+
+   Return the :c:type:`void\*` value associated with a TSS key in the current
+   thread.  This returns *NULL* if no value is associated with the key in the
+   current thread.
+
+
+.. _thread-local-storage-api:
+
+Thread Local Storage (TLS) API
+------------------------------
+
+.. deprecated:: 3.7
+   This API is superseded by
+   :ref:`Thread Specific Storage (TSS) API <thread-specific-storage-api>`.
+
+.. note::
+   This version of the API does not support platforms where the native TLS key
+   is defined in a way that cannot be safely cast to ``int``.  On such platforms,
+   :c:func:`PyThread_create_key` will return immediately with a failure status,
+   and the other TLS functions will all be no-ops on such platforms.
+
+Due to the compatibility problem noted above, this version of the API should not
+be used in new code.
+
+.. c:function:: int PyThread_create_key()
+.. c:function:: void PyThread_delete_key(int key)
+.. c:function:: int PyThread_set_key_value(int key, void *value)
+.. c:function:: void* PyThread_get_key_value(int key)
+.. c:function:: void PyThread_delete_key_value(int key)
+.. c:function:: void PyThread_ReInitTLS()
+

Doc/c-api/intro.rst

@@ -20,8 +20,8 @@ in an application.
 Writing an extension module is a relatively well-understood process, where a
 "cookbook" approach works well.  There are several tools that automate the
 process to some extent.  While people have embedded Python in other
-applications since its early existence, the process of  embedding Python is less
+applications since its early existence, the process of embedding Python is
-straightforward than writing an extension.
+less straightforward than writing an extension.
 
 Many API functions are useful independent of whether you're embedding  or
 extending Python; moreover, most applications that embed Python  will need to
@@ -30,6 +30,16 @@ familiar with writing an extension before  attempting to embed Python in a real
 application.
 
 
+Coding standards
+================
+
+If you're writing C code for inclusion in CPython, you **must** follow the
+guidelines and standards defined in :PEP:`7`.  These guidelines apply
+regardless of the version of Python you are contributing to.  Following these
+conventions is not necessary for your own third party extension modules,
+unless you eventually expect to contribute them to Python.
+
+
 .. _api-includes:
 
 Include Files
@@ -81,6 +91,72 @@ header files do properly declare the entry points to be ``extern "C"``, so there
 is no need to do anything special to use the API from C++.
 
 
+Useful macros
+=============
+
+Several useful macros are defined in the Python header files.  Many are
+defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
+Others of a more general utility are defined here.  This is not necessarily a
+complete listing.
+
+.. c:macro:: Py_UNREACHABLE()
+
+   Use this when you have a code path that you do not expect to be reached.
+   For example, in the ``default:`` clause in a ``switch`` statement for which
+   all possible values are covered in ``case`` statements.  Use this in places
+   where you might be tempted to put an ``assert(0)`` or ``abort()`` call.
+
+   .. versionadded:: 3.7
+
+.. c:macro:: Py_ABS(x)
+
+   Return the absolute value of ``x``.
+
+   .. versionadded:: 3.3
+
+.. c:macro:: Py_MIN(x, y)
+
+   Return the minimum value between ``x`` and ``y``.
+
+   .. versionadded:: 3.3
+
+.. c:macro:: Py_MAX(x, y)
+
+   Return the maximum value between ``x`` and ``y``.
+
+   .. versionadded:: 3.3
+
+.. c:macro:: Py_STRINGIFY(x)
+
+   Convert ``x`` to a C string.  E.g. ``Py_STRINGIFY(123)`` returns
+   ``"123"``.
+
+   .. versionadded:: 3.4
+
+.. c:macro:: Py_MEMBER_SIZE(type, member)
+
+   Return the size of a structure (``type``) ``member`` in bytes.
+
+   .. versionadded:: 3.6
+
+.. c:macro:: Py_CHARMASK(c)
+
+   Argument must be a character or an integer in the range [-128, 127] or [0,
+   255].  This macro returns ``c`` cast to an ``unsigned char``.
+
+.. c:macro:: Py_GETENV(s)
+
+   Like ``getenv(s)``, but returns *NULL* if :option:`-E` was passed on the
+   command line (i.e. if ``Py_IgnoreEnvironmentFlag`` is set).
+
+.. c:macro:: Py_UNUSED(arg)
+
+   Use this for unused arguments in a function definition to silence compiler
+   warnings, e.g. ``PyObject* func(PyObject *Py_UNUSED(ignored))``.
+
+   .. versionadded:: 3.4
+
+
 .. _api-objects:
 
 Objects, Types and Reference Counts

Doc/c-api/mapping.rst

@@ -50,20 +50,29 @@ Mapping Protocol
 
 .. c:function:: PyObject* PyMapping_Keys(PyObject *o)
 
-   On success, return a list or tuple of the keys in object *o*.  On failure,
+   On success, return a list of the keys in object *o*.  On failure, return
-   return *NULL*.
+   *NULL*.
+
+   .. versionchanged:: 3.7
+      Previously, the function returned a list or a tuple.
 
 
 .. c:function:: PyObject* PyMapping_Values(PyObject *o)
 
-   On success, return a list or tuple of the values in object *o*.  On failure,
+   On success, return a list of the values in object *o*.  On failure, return
-   return *NULL*.
+   *NULL*.
+
+   .. versionchanged:: 3.7
+      Previously, the function returned a list or a tuple.
 
 
 .. c:function:: PyObject* PyMapping_Items(PyObject *o)
 
-   On success, return a list or tuple of the items in object *o*, where each item
+   On success, return a list of the items in object *o*, where each item is a
-   is a tuple containing a key-value pair.  On failure, return *NULL*.
+   tuple containing a key-value pair.  On failure, return *NULL*.
+
+   .. versionchanged:: 3.7
+      Previously, the function returned a list or a tuple.
 
 
 .. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)

Doc/c-api/memory.rst

@@ -150,7 +150,7 @@ The default raw memory block allocator uses the following functions:
 
    Frees the memory block pointed to by *p*, which must have been returned by a
    previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or
-   :c:func:`PyMem_RawCalloc`.  Otherwise, or if ``PyMem_Free(p)`` has been
+   :c:func:`PyMem_RawCalloc`.  Otherwise, or if ``PyMem_RawFree(p)`` has been
    called before, undefined behavior occurs.
 
    If *p* is *NULL*, no operation is performed.
@@ -263,6 +263,69 @@ versions and is therefore deprecated in extension modules.
 * ``PyMem_DEL(ptr)``
 
 
+Object allocators
+=================
+
+The following function sets, modeled after the ANSI C standard, but specifying
+behavior when requesting zero bytes, are available for allocating and releasing
+memory from the Python heap.
+
+By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`.
+
+.. warning::
+
+   The :term:`GIL <global interpreter lock>` must be held when using these
+   functions.
+
+.. c:function:: void* PyObject_Malloc(size_t n)
+
+   Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
+   allocated memory, or *NULL* if the request fails.
+
+   Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as
+   if ``PyObject_Malloc(1)`` had been called instead. The memory will not have
+   been initialized in any way.
+
+
+.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+   request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a distinct
+   non-*NULL* pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called
+   instead.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: void* PyObject_Realloc(void *p, size_t n)
+
+   Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
+   unchanged to the minimum of the old and the new sizes.
+
+   If *p* is *NULL*, the call is equivalent to ``PyObject_Malloc(n)``; else if *n*
+   is equal to zero, the memory block is resized but is not freed, and the
+   returned pointer is non-*NULL*.
+
+   Unless *p* is *NULL*, it must have been returned by a previous call to
+   :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`.
+
+   If the request fails, :c:func:`PyObject_Realloc` returns *NULL* and *p* remains
+   a valid pointer to the previous memory area.
+
+
+.. c:function:: void PyObject_Free(void *p)
+
+   Frees the memory block pointed to by *p*, which must have been returned by a
+   previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or
+   :c:func:`PyObject_Calloc`.  Otherwise, or if ``PyObject_Free(p)`` has been called
+   before, undefined behavior occurs.
+
+   If *p* is *NULL*, no operation is performed.
+
+
 Customize Memory Allocators
 ===========================
 
@@ -387,7 +450,7 @@ The pymalloc allocator
 
 Python has a *pymalloc* allocator optimized for small objects (smaller or equal
 to 512 bytes) with a short lifetime. It uses memory mappings called "arenas"
-with a fixed size of 256 KB. It falls back to :c:func:`PyMem_RawMalloc` and
+with a fixed size of 256 KiB. It falls back to :c:func:`PyMem_RawMalloc` and
 :c:func:`PyMem_RawRealloc` for allocations larger than 512 bytes.
 
 *pymalloc* is the default allocator of the :c:data:`PYMEM_DOMAIN_MEM` (ex:
@@ -429,6 +492,28 @@ Customize pymalloc Arena Allocator
    Set the arena allocator.
 
 
+tracemalloc C API
+=================
+
+.. versionadded:: 3.7
+
+.. c:function: int PyTraceMalloc_Track(unsigned int domain, uintptr_t ptr, size_t size)
+
+   Track an allocated memory block in the :mod:`tracemalloc` module.
+
+   Return 0 on success, return ``-1`` on error (failed to allocate memory to
+   store the trace). Return ``-2`` if tracemalloc is disabled.
+
+   If memory block is already tracked, update the existing trace.
+
+.. c:function: int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr)
+
+   Untrack an allocated memory block in the :mod:`tracemalloc` module.
+   Do nothing if the block was not tracked.
+
+   Return ``-2`` if tracemalloc is disabled, otherwise return ``0``.
+
+
 .. _memoryexamples:
 
 Examples

Doc/c-api/slice.rst

@@ -53,6 +53,22 @@ Slice Objects
 
    Returns ``0`` on success and ``-1`` on error with exception set.
 
+   .. note::
+      This function is considered not safe for resizable sequences.
+      Its invocation should be replaced by a combination of
+      :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices` where ::
+
+         if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) {
+             // return error
+         }
+
+      is replaced by ::
+
+         if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {
+             // return error
+         }
+         slicelength = PySlice_AdjustIndices(length, &start, &stop, step);
+
    .. versionchanged:: 3.2
       The parameter type for the *slice* parameter was ``PySliceObject*``
       before.
@@ -61,7 +77,7 @@ Slice Objects
       If ``Py_LIMITED_API`` is not set or set to the value between ``0x03050400``
       and ``0x03060000`` (not including) or ``0x03060100`` or higher
       :c:func:`!PySlice_GetIndicesEx` is implemented as a macro using
-      :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`.
+      :c:func:`!PySlice_Unpack` and :c:func:`!PySlice_AdjustIndices`.
       Arguments *start*, *stop* and *step* are evaluated more than once.
 
    .. deprecated:: 3.6.1

Doc/c-api/structures.rst

@@ -294,3 +294,43 @@ definition with the same method name.
    read-only access.  Using :c:macro:`T_STRING` for :attr:`type` implies
    :c:macro:`READONLY`.  Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
    members can be deleted.  (They are set to *NULL*).
+
+
+.. c:type:: PyGetSetDef
+
+   Structure to define property-like access for a type. See also description of
+   the :c:member:`PyTypeObject.tp_getset` slot.
+
+   +-------------+------------------+-----------------------------------+
+   | Field       | C Type           | Meaning                           |
+   +=============+==================+===================================+
+   | name        | const char \*    | attribute name                    |
+   +-------------+------------------+-----------------------------------+
+   | get         | getter           | C Function to get the attribute   |
+   +-------------+------------------+-----------------------------------+
+   | set         | setter           | optional C function to set or     |
+   |             |                  | delete the attribute, if omitted  |
+   |             |                  | the attribute is readonly         |
+   +-------------+------------------+-----------------------------------+
+   | doc         | const char \*    | optional docstring                |
+   +-------------+------------------+-----------------------------------+
+   | closure     | void \*          | optional function pointer,        |
+   |             |                  | providing additional data for     |
+   |             |                  | getter and setter                 |
+   +-------------+------------------+-----------------------------------+
+
+   The ``get`` function takes one :c:type:`PyObject\*` parameter (the
+   instance) and a function pointer (the associated ``closure``)::
+
+      typedef PyObject *(*getter)(PyObject *, void *);
+
+   It should return a new reference on success or *NULL* with a set exception
+   on failure.
+
+   ``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
+   the value to be set) and a function pointer (the associated ``closure``)::
+
+      typedef int (*setter)(PyObject *, PyObject *, void *);
+
+   In case the attribute should be deleted the second parameter is *NULL*.
+   Should return ``0`` on success or ``-1`` with a set exception on failure.

Doc/c-api/typeobj.rst

@@ -623,6 +623,22 @@ type objects) *must* have the :attr:`ob_size` field.
    | :const:`Py_GE` | ``>=``     |
    +----------------+------------+
 
+   The following macro is defined to ease writing rich comparison functions:
+
+   .. c:function:: PyObject *Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op)
+
+      Return ``Py_True`` or ``Py_False`` from the function, depending on the
+      result of a comparison.
+      VAL_A and VAL_B must be orderable by C comparison operators (for example,
+      they may be C ints or floats). The third argument specifies the requested
+      operation, as for :c:func:`PyObject_RichCompare`.
+
+      The return value's reference count is properly incremented.
+
+      On error, sets an exception and returns NULL from the function.
+
+      .. versionadded:: 3.7
+
 
 .. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset
 
@@ -719,21 +735,6 @@ type objects) *must* have the :attr:`ob_size` field.
    This field is not inherited by subtypes (computed attributes are inherited
    through a different mechanism).
 
-   .. XXX belongs elsewhere
-
-   Docs for PyGetSetDef::
-
-      typedef PyObject *(*getter)(PyObject *, void *);
-      typedef int (*setter)(PyObject *, PyObject *, void *);
-
-      typedef struct PyGetSetDef {
-          const char *name; /* attribute name */
-          getter get;       /* C function to get the attribute */
-          setter set;       /* C function to set or delete the attribute */
-          const char *doc;  /* optional doc string */
-          void *closure;    /* optional additional data for getter and setter */
-      } PyGetSetDef;
-
 
 .. c:member:: PyTypeObject* PyTypeObject.tp_base
 

Doc/c-api/unicode.rst

@@ -934,16 +934,22 @@ wchar_t Support
    Convert the Unicode object to a wide character string. The output string
    always ends with a null character. If *size* is not *NULL*, write the number
    of wide characters (excluding the trailing null termination character) into
-   *\*size*.
+   *\*size*. Note that the resulting :c:type:`wchar_t` string might contain
+   null characters, which would cause the string to be truncated when used with
+   most C functions. If *size* is *NULL* and the :c:type:`wchar_t*` string
+   contains null characters a :exc:`ValueError` is raised.
 
    Returns a buffer allocated by :c:func:`PyMem_Alloc` (use
-   :c:func:`PyMem_Free` to free it) on success. On error, returns *NULL*,
+   :c:func:`PyMem_Free` to free it) on success. On error, returns *NULL*
-   *\*size* is undefined and raises a :exc:`MemoryError`. Note that the
+   and *\*size* is undefined. Raises a :exc:`MemoryError` if memory allocation
-   resulting :c:type:`wchar_t` string might contain null characters, which
+   is failed.
-   would cause the string to be truncated when used with most C functions.
 
    .. versionadded:: 3.2
 
+   .. versionchanged:: 3.7
+      Raises a :exc:`ValueError` if *size* is *NULL* and the :c:type:`wchar_t*`
+      string contains null characters.
+
 
 .. _builtincodecs:
 

Doc/c-api/veryhigh.rst

@@ -141,7 +141,8 @@ the same library that the Python runtime is using.
    Read and execute statements from a file associated with an interactive device
    until EOF is reached.  The user will be prompted using ``sys.ps1`` and
    ``sys.ps2``.  *filename* is decoded from the filesystem encoding
-   (:func:`sys.getfilesystemencoding`).  Returns ``0`` at EOF.
+   (:func:`sys.getfilesystemencoding`).  Returns ``0`` at EOF or a negative
+   number upon failure.
 
 
 .. c:var:: int (*PyOS_InputHook)(void)

Doc/conf.py

@@ -38,7 +38,8 @@ highlight_language = 'python3'
 needs_sphinx = '1.2'
 
 # Ignore any .rst files in the venv/ directory.
-exclude_patterns = ['venv/*', 'README.rst']
+venvdir = os.getenv('VENVDIR', 'venv')
+exclude_patterns = [venvdir+'/*', 'README.rst']
 
 
 # Options for HTML output
@@ -90,13 +91,17 @@ html_split_index = True
 # ------------------------
 
 # Get LaTeX to handle Unicode correctly
-latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}', 'utf8extra': ''}
+latex_elements = {
+    'inputenc': r'\usepackage[utf8x]{inputenc}',
+    'utf8extra': '',
+    'fontenc': r'\usepackage[T1,T2A]{fontenc}',
+}
 
 # Additional stuff for the LaTeX preamble.
 latex_elements['preamble'] = r'''
 \authoraddress{
-  \strong{Python Software Foundation}\\
+  \sphinxstrong{Python Software Foundation}\\
-  Email: \email{docs@python.org}
+  Email: \sphinxemail{docs@python.org}
 }
 \let\Verbatim=\OriginalVerbatim
 \let\endVerbatim=\endOriginalVerbatim
@@ -106,7 +111,7 @@ latex_elements['preamble'] = r'''
 latex_elements['papersize'] = 'a4'
 
 # The font size ('10pt', '11pt' or '12pt').
-latex_elements['font_size'] = '10pt'
+latex_elements['pointsize'] = '10pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).

Doc/copyright.rst

@@ -4,7 +4,7 @@ Copyright
 
 Python and this documentation is:
 
-Copyright © 2001-2016 Python Software Foundation. All rights reserved.
+Copyright © 2001-2017 Python Software Foundation. All rights reserved.
 
 Copyright © 2000 BeOpen.com. All rights reserved.
 

Doc/distutils/apiref.rst

@@ -814,13 +814,13 @@ This module provides the :class:`UnixCCompiler` class, a subclass of
 .. module:: distutils.msvccompiler
    :synopsis: Microsoft Compiler
 
+.. XXX: This is *waaaaay* out of date!
 
 This module provides :class:`MSVCCompiler`, an implementation of the abstract
 :class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
 modules need to be compiled with the same compiler that was used to compile
 Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
-2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium
+2.4 and 2.5, the compiler is Visual Studio .NET 2003.
-binaries are created using the Platform SDK.
 
 :class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
 its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
@@ -1086,19 +1086,16 @@ other utility module.
 
    Return a string that identifies the current platform.  This is used mainly to
    distinguish platform-specific build directories and platform-specific built
-   distributions.  Typically includes the OS name and version and the architecture
+   distributions.  Typically includes the OS name and version and the
-   (as supplied by 'os.uname()'), although the exact information included depends
+   architecture (as supplied by 'os.uname()'), although the exact information
-   on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only
+   included depends on the OS; e.g., on Linux, the kernel version isn't
-   runs on SGI hardware), but for Linux the kernel version isn't particularly
+   particularly important.
-   important.
 
    Examples of returned values:
 
    * ``linux-i586``
    * ``linux-alpha``
    * ``solaris-2.6-sun4u``
-   * ``irix-5.3``
-   * ``irix64-6.2``
 
    For non-POSIX platforms, currently just returns ``sys.platform``.
 

Doc/distutils/builtdist.rst

@@ -351,8 +351,8 @@ installed, you can use a 32bit version of Windows to create 64bit extensions
 and vice-versa.
 
 To build for an alternate platform, specify the :option:`!--plat-name` option
-to the build command.  Valid values are currently 'win32', 'win-amd64' and
+to the build command.  Valid values are currently 'win32', and  'win-amd64'.
-'win-ia64'.  For example, on a 32bit version of Windows, you could execute::
+For example, on a 32bit version of Windows, you could execute::
 
    python setup.py build --plat-name=win-amd64
 
@@ -368,7 +368,7 @@ Python itself for the platform you are targeting - it is not possible from a
 binary installation of Python (as the .lib etc file for other platforms are
 not included.)  In practice, this means the user of a 32 bit operating
 system will need to use Visual Studio 2008 to open the
-:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the
+:file:`PCbuild/PCbuild.sln` solution in the Python source tree and build the
 "x64" configuration of the 'pythoncore' project before cross-compiling
 extensions is possible.
 

Doc/docutils.conf

@@ -0,0 +1,2 @@
+[restructuredtext parser]
+smartquotes-locales: ja: ""''

Doc/extending/newtypes.rst

@@ -177,16 +177,9 @@ the module.  We'll expand this example later to have more interesting behavior.
 For now, all we want to be able to do is to create new :class:`Noddy` objects.
 To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new` implementation.
 In this case, we can just use the default implementation provided by the API
-function :c:func:`PyType_GenericNew`.  We'd like to just assign this to the
+function :c:func:`PyType_GenericNew`. ::
-:c:member:`~PyTypeObject.tp_new` slot, but we can't, for portability sake, On some platforms or
-compilers, we can't statically initialize a structure member with a function
-defined in another C module, so, instead, we'll assign the :c:member:`~PyTypeObject.tp_new` slot
-in the module initialization function just before calling
-:c:func:`PyType_Ready`::
 
-   noddy_NoddyType.tp_new = PyType_GenericNew;
+   PyType_GenericNew,         /* tp_new */
-   if (PyType_Ready(&noddy_NoddyType) < 0)
-       return;
 
 All the other type methods are *NULL*, so we'll go over them later --- that's
 for a later section!
@@ -728,8 +721,9 @@ functions.  With :c:func:`Py_VISIT`, :c:func:`Noddy_traverse` can be simplified:
    uniformity across these boring implementations.
 
 We also need to provide a method for clearing any subobjects that can
-participate in cycles.  We implement the method and reimplement the deallocator
+participate in cycles.
-to use it::
+
+::
 
    static int
    Noddy_clear(Noddy *self)
@@ -747,13 +741,6 @@ to use it::
        return 0;
    }
 
-   static void
-   Noddy_dealloc(Noddy* self)
-   {
-       Noddy_clear(self);
-       Py_TYPE(self)->tp_free((PyObject*)self);
-   }
-
 Notice the use of a temporary variable in :c:func:`Noddy_clear`. We use the
 temporary variable so that we can set each member to *NULL* before decrementing
 its reference count.  We do this because, as was discussed earlier, if the
@@ -776,6 +763,23 @@ be simplified::
        return 0;
    }
 
+Note that :c:func:`Noddy_dealloc` may call arbitrary functions through
+``__del__`` method or weakref callback. It means circular GC can be
+triggered inside the function.  Since GC assumes reference count is not zero,
+we need to untrack the object from GC by calling :c:func:`PyObject_GC_UnTrack`
+before clearing members. Here is reimplemented deallocator which uses
+:c:func:`PyObject_GC_UnTrack` and :c:func:`Noddy_clear`.
+
+::
+
+   static void
+   Noddy_dealloc(Noddy* self)
+   {
+       PyObject_GC_UnTrack(self);
+       Noddy_clear(self);
+       Py_TYPE(self)->tp_free((PyObject*)self);
+   }
+
 Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
 
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */

Doc/faq/general.rst

@@ -167,7 +167,7 @@ several useful pieces of freely distributable software.  The source will compile
 and run out of the box on most UNIX platforms.
 
 Consult the `Getting Started section of the Python Developer's Guide
-<https://docs.python.org/devguide/setup.html>`__ for more
+<https://devguide.python.org/setup/>`__ for more
 information on getting the source code and compiling it.
 
 
@@ -223,7 +223,7 @@ newsgroups and on the Python home page at https://www.python.org/; an RSS feed o
 news is available.
 
 You can also access the development version of Python through Git.  See
-`The Python Developer's Guide <https://docs.python.org/devguide/>`_ for details.
+`The Python Developer's Guide <https://devguide.python.org/>`_ for details.
 
 
 How do I submit bug reports and patches for Python?
@@ -239,7 +239,7 @@ report bugs to Python, you can obtain your Roundup password through Roundup's
 `password reset procedure <https://bugs.python.org/user?@template=forgotten>`_.
 
 For more information on how Python is developed, consult `the Python Developer's
-Guide <https://docs.python.org/devguide/>`_.
+Guide <https://devguide.python.org/>`_.
 
 
 Are there any published articles about Python that I can reference?

Doc/faq/gui.rst

@@ -94,15 +94,6 @@ Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet
 powerful and mature cross-platform windowing system, are available from `the
 PyFLTK project <http://pyfltk.sourceforge.net>`_.
 
-
-FOX
-----
-
-A wrapper for `the FOX toolkit <http://www.fox-toolkit.org/>`_ called `FXpy
-<http://fxpy.sourceforge.net/>`_ is available.  FOX supports both Unix variants
-and Windows.
-
-
 OpenGL
 ------
 

Doc/faq/programming.rst

@@ -1638,7 +1638,7 @@ collected.
 
 Despite the cycle collector, it's still a good idea to define an explicit
 ``close()`` method on objects to be called whenever you're done with them.  The
-``close()`` method can then remove attributes that refer to subobjecs.  Don't
+``close()`` method can then remove attributes that refer to subobjects.  Don't
 call :meth:`__del__` directly -- :meth:`__del__` should call ``close()`` and
 ``close()`` should make sure that it can be called more than once for the same
 object.

Doc/glossary.rst

@@ -535,7 +535,10 @@ Glossary
       iterables include all sequence types (such as :class:`list`, :class:`str`,
       and :class:`tuple`) and some non-sequence types like :class:`dict`,
       :term:`file objects <file object>`, and objects of any classes you define
-      with an :meth:`__iter__` or :meth:`__getitem__` method.  Iterables can be
+      with an :meth:`__iter__` method or with a :meth:`__getitem__` method
+      that implements :term:`Sequence` semantics.
+
+      Iterables can be
       used in a :keyword:`for` loop and in many other places where a sequence is
       needed (:func:`zip`, :func:`map`, ...).  When an iterable object is passed
       as an argument to the built-in function :func:`iter`, it returns an

Doc/howto/curses.rst

@@ -65,7 +65,7 @@ and full support for mouse and keyboard input.
 The Python curses module
 ------------------------
 
-Thy Python module is a fairly simple wrapper over the C functions provided by
+The Python module is a fairly simple wrapper over the C functions provided by
 curses; if you're already familiar with curses programming in C, it's really
 easy to transfer that knowledge to Python.  The biggest difference is that the
 Python interface makes things simpler by merging different C functions such as
@@ -538,7 +538,7 @@ the Python interface.  Often this isn't because they're difficult to
 implement, but because no one has needed them yet.  Also, Python
 doesn't yet support the menu library associated with ncurses.
 Patches adding support for these would be welcome; see
-`the Python Developer's Guide <https://docs.python.org/devguide/>`_ to
+`the Python Developer's Guide <https://devguide.python.org/>`_ to
 learn more about submitting patches to Python.
 
 * `Writing Programs with NCURSES <http://invisible-island.net/ncurses/ncurses-intro.html>`_:

Doc/howto/descriptor.rst

@@ -180,7 +180,7 @@ descriptor is useful for monitoring just a few chosen attributes::
 
 The protocol is simple and offers exciting possibilities.  Several use cases are
 so common that they have been packaged into individual function calls.
-Properties, bound and unbound methods, static methods, and class methods are all
+Properties, bound methods, static methods, and class methods are all
 based on the descriptor protocol.
 
 
@@ -252,10 +252,10 @@ to wrap access to the value attribute in a property data descriptor::
 
     class Cell(object):
         . . .
-        def getvalue(self, obj):
+        def getvalue(self):
-            "Recalculate cell before returning value"
+            "Recalculate the cell before returning value"
             self.recalc()
-            return obj._value
+            return self._value
         value = property(getvalue)
 
 
@@ -266,22 +266,23 @@ Python's object oriented features are built upon a function based environment.
 Using non-data descriptors, the two are merged seamlessly.
 
 Class dictionaries store methods as functions.  In a class definition, methods
-are written using :keyword:`def` and :keyword:`lambda`, the usual tools for
+are written using :keyword:`def` or :keyword:`lambda`, the usual tools for
-creating functions.  The only difference from regular functions is that the
+creating functions.  Methods only differ from regular functions in that the
 first argument is reserved for the object instance.  By Python convention, the
 instance reference is called *self* but may be called *this* or any other
 variable name.
 
 To support method calls, functions include the :meth:`__get__` method for
 binding methods during attribute access.  This means that all functions are
-non-data descriptors which return bound or unbound methods depending whether
+non-data descriptors which return bound methods when they are invoked from an
-they are invoked from an object or a class.  In pure python, it works like
+object.  In pure python, it works like this::
-this::
 
     class Function(object):
         . . .
         def __get__(self, obj, objtype=None):
             "Simulate func_descr_get() in Objects/funcobject.c"
+            if obj is None:
+                return self
             return types.MethodType(self, obj)
 
 Running the interpreter shows how the function descriptor works in practice::
@@ -291,25 +292,34 @@ Running the interpreter shows how the function descriptor works in practice::
     ...         return x
     ...
     >>> d = D()
-    >>> D.__dict__['f']  # Stored internally as a function
+
-    <function f at 0x00C45070>
+    # Access through the class dictionary does not invoke __get__.
-    >>> D.f              # Get from a class becomes an unbound method
+    # It just returns the underlying function object.
-    <unbound method D.f>
+    >>> D.__dict__['f']
-    >>> d.f              # Get from an instance becomes a bound method
+    <function D.f at 0x00C45070>
+
+    # Dotted access from a class calls __get__() which just returns
+    # the underlying function unchanged.
+    >>> D.f
+    <function D.f at 0x00C45070>
+
+    # The function has a __qualname__ attribute to support introspection
+    >>> D.f.__qualname__
+    'D.f'
+
+    # Dotted access from an instance calls __get__() which returns the
+    # function wrapped in a bound method object
+    >>> d.f
     <bound method D.f of <__main__.D object at 0x00B18C90>>
 
-The output suggests that bound and unbound methods are two different types.
+    # Internally, the bound method stores the underlying function,
-While they could have been implemented that way, the actual C implementation of
+    # the bound instance, and the class of the bound instance.
-:c:type:`PyMethod_Type` in :source:`Objects/classobject.c` is a single object
+    >>> d.f.__func__
-with two different representations depending on whether the :attr:`im_self`
+    <function D.f at 0x1012e5ae8>
-field is set or is *NULL* (the C equivalent of ``None``).
+    >>> d.f.__self__
-
+    <__main__.D object at 0x1012e1f98>
-Likewise, the effects of calling a method object depend on the :attr:`im_self`
+    >>> d.f.__class__
-field. If set (meaning bound), the original function (stored in the
+    <class 'method'>
-:attr:`im_func` field) is called as expected with the first argument set to the
-instance.  If unbound, all of the arguments are passed unchanged to the original
-function. The actual C implementation of :func:`instancemethod_call()` is only
-slightly more complex in that it includes some type checking.
 
 
 Static Methods and Class Methods

Doc/howto/instrumentation.rst

@@ -312,6 +312,21 @@ Available static markers
    Fires when the Python interpreter finishes a garbage collection
    cycle. ``arg0`` is the number of collected objects.
 
+.. c:function:: import__find__load__start(str modulename)
+
+   Fires before :mod:`importlib` attempts to find and load the module.
+   ``arg0`` is the module name.
+
+   .. versionadded:: 3.7
+
+.. c:function:: import__find__load__done(str modulename, int found)
+
+   Fires after :mod:`importlib`'s find_and_load function is called.
+   ``arg0`` is the module name, ``arg1`` indicates if module was
+   successfully loaded.
+
+   .. versionadded:: 3.7
+
 
 SystemTap Tapsets
 -----------------

Doc/howto/logging-cookbook.rst

@@ -1055,7 +1055,7 @@ to indicate additional contextual information to be added to the log). So
 you cannot directly make logging calls using :meth:`str.format` or
 :class:`string.Template` syntax, because internally the logging package
 uses %-formatting to merge the format string and the variable arguments.
-There would no changing this while preserving backward compatibility, since
+There would be no changing this while preserving backward compatibility, since
 all logging calls which are out there in existing code will be using %-format
 strings.
 
@@ -1258,8 +1258,8 @@ socket is created separately and passed to the handler (as its 'queue')::
 
     class ZeroMQSocketHandler(QueueHandler):
         def enqueue(self, record):
-            data = json.dumps(record.__dict__)
+            self.queue.send_json(record.__dict__)
-            self.queue.send(data)
+
 
     handler = ZeroMQSocketHandler(sock)
 
@@ -1272,11 +1272,10 @@ data needed by the handler to create the socket::
             self.ctx = ctx or zmq.Context()
             socket = zmq.Socket(self.ctx, socktype)
             socket.bind(uri)
-            QueueHandler.__init__(self, socket)
+            super().__init__(socket)
 
         def enqueue(self, record):
-            data = json.dumps(record.__dict__)
+            self.queue.send_json(record.__dict__)
-            self.queue.send(data)
 
         def close(self):
             self.queue.close()
@@ -1292,12 +1291,13 @@ of queues, for example a ZeroMQ 'subscribe' socket. Here's an example::
         def __init__(self, uri, *handlers, **kwargs):
             self.ctx = kwargs.get('ctx') or zmq.Context()
             socket = zmq.Socket(self.ctx, zmq.SUB)
-            socket.setsockopt(zmq.SUBSCRIBE, '')  # subscribe to everything
+            socket.setsockopt_string(zmq.SUBSCRIBE, '')  # subscribe to everything
             socket.connect(uri)
+            super().__init__(socket, *handlers, **kwargs)
 
         def dequeue(self):
-            msg = self.queue.recv()
+            msg = self.queue.recv_json()
-            return logging.makeLogRecord(json.loads(msg))
+            return logging.makeLogRecord(msg)
 
 
 .. seealso::

Doc/howto/regex.rst

@@ -153,8 +153,8 @@ These sequences can be included inside a character class.  For example,
 ``','`` or ``'.'``.
 
 The final metacharacter in this section is ``.``.  It matches anything except a
-newline character, and there's an alternate mode (``re.DOTALL``) where it will
+newline character, and there's an alternate mode (:const:`re.DOTALL`) where it will
-match even a newline.  ``'.'`` is often used where you want to match "any
+match even a newline.  ``.`` is often used where you want to match "any
 character".
 
 
@@ -168,14 +168,11 @@ wouldn't be much of an advance. Another capability is that you can specify that
 portions of the RE must be repeated a certain number of times.
 
 The first metacharacter for repeating things that we'll look at is ``*``.  ``*``
-doesn't match the literal character ``*``; instead, it specifies that the
+doesn't match the literal character ``'*'``; instead, it specifies that the
 previous character can be matched zero or more times, instead of exactly once.
 
-For example, ``ca*t`` will match ``ct`` (0 ``a`` characters), ``cat`` (1 ``a``),
+For example, ``ca*t`` will match ``'ct'`` (0 ``'a'`` characters), ``'cat'`` (1 ``'a'``),
-``caaat`` (3 ``a`` characters), and so forth.  The RE engine has various
+``'caaat'`` (3 ``'a'`` characters), and so forth.
-internal limitations stemming from the size of C's ``int`` type that will
-prevent it from matching over 2 billion ``a`` characters; patterns
-are usually not written to match that much data.
 
 Repetitions such as ``*`` are :dfn:`greedy`; when repeating a RE, the matching
 engine will try to repeat it as many times as possible. If later portions of the
@@ -185,7 +182,7 @@ fewer repetitions.
 A step-by-step example will make this more obvious.  Let's consider the
 expression ``a[bcd]*b``.  This matches the letter ``'a'``, zero or more letters
 from the class ``[bcd]``, and finally ends with a ``'b'``.  Now imagine matching
-this RE against the string ``abcbd``.
+this RE against the string ``'abcbd'``.
 
 +------+-----------+---------------------------------+
 | Step | Matched   | Explanation                     |
@@ -218,7 +215,7 @@ this RE against the string ``abcbd``.
 |      |           | it succeeds.                    |
 +------+-----------+---------------------------------+
 
-The end of the RE has now been reached, and it has matched ``abcb``.  This
+The end of the RE has now been reached, and it has matched ``'abcb'``.  This
 demonstrates how the matching engine goes as far as it can at first, and if no
 match is found it will then progressively back up and retry the rest of the RE
 again and again.  It will back up until it has tried zero matches for
@@ -229,24 +226,23 @@ Another repeating metacharacter is ``+``, which matches one or more times.  Pay
 careful attention to the difference between ``*`` and ``+``; ``*`` matches
 *zero* or more times, so whatever's being repeated may not be present at all,
 while ``+`` requires at least *one* occurrence.  To use a similar example,
-``ca+t`` will match ``cat`` (1 ``a``), ``caaat`` (3 ``a``'s), but won't match
+``ca+t`` will match ``'cat'`` (1 ``'a'``), ``'caaat'`` (3 ``'a'``\ s), but won't
-``ct``.
+match ``'ct'``.
 
 There are two more repeating qualifiers.  The question mark character, ``?``,
 matches either once or zero times; you can think of it as marking something as
-being optional.  For example, ``home-?brew`` matches either ``homebrew`` or
+being optional.  For example, ``home-?brew`` matches either ``'homebrew'`` or
-``home-brew``.
+``'home-brew'``.
 
 The most complicated repeated qualifier is ``{m,n}``, where *m* and *n* are
 decimal integers.  This qualifier means there must be at least *m* repetitions,
-and at most *n*.  For example, ``a/{1,3}b`` will match ``a/b``, ``a//b``, and
+and at most *n*.  For example, ``a/{1,3}b`` will match ``'a/b'``, ``'a//b'``, and
-``a///b``.  It won't match ``ab``, which has no slashes, or ``a////b``, which
+``'a///b'``.  It won't match ``'ab'``, which has no slashes, or ``'a////b'``, which
 has four.
 
 You can omit either *m* or *n*; in that case, a reasonable value is assumed for
 the missing value.  Omitting *m* is interpreted as a lower limit of 0, while
-omitting *n* results in an upper bound of infinity --- actually, the upper bound
+omitting *n* results in an upper bound of infinity.
-is the 2-billion limit mentioned earlier, but that might as well be infinity.
 
 Readers of a reductionist bent may notice that the three other qualifiers can
 all be expressed using this notation.  ``{0,}`` is the same as ``*``, ``{1,}``
@@ -366,7 +362,7 @@ for a complete listing.
 |                  | returns them as an :term:`iterator`.          |
 +------------------+-----------------------------------------------+
 
-:meth:`~re.regex.match` and :meth:`~re.regex.search` return ``None`` if no match can be found.  If
+:meth:`~re.Pattern.match` and :meth:`~re.Pattern.search` return ``None`` if no match can be found.  If
 they're successful, a :ref:`match object <match-objects>` instance is returned,
 containing information about the match: where it starts and ends, the substring
 it matched, and more.
@@ -388,24 +384,24 @@ Python interpreter, import the :mod:`re` module, and compile a RE::
 
 Now, you can try matching various strings against the RE ``[a-z]+``.  An empty
 string shouldn't match at all, since ``+`` means 'one or more repetitions'.
-:meth:`match` should return ``None`` in this case, which will cause the
+:meth:`~re.Pattern.match` should return ``None`` in this case, which will cause the
 interpreter to print no output.  You can explicitly print the result of
-:meth:`match` to make this clear. ::
+:meth:`!match` to make this clear. ::
 
    >>> p.match("")
    >>> print(p.match(""))
    None
 
 Now, let's try it on a string that it should match, such as ``tempo``.  In this
-case, :meth:`match` will return a :ref:`match object <match-objects>`, so you
+case, :meth:`~re.Pattern.match` will return a :ref:`match object <match-objects>`, so you
 should store the result in a variable for later use. ::
 
    >>> m = p.match('tempo')
-   >>> m  #doctest: +ELLIPSIS
+   >>> m
-   <_sre.SRE_Match object; span=(0, 5), match='tempo'>
+   <re.Match object; span=(0, 5), match='tempo'>
 
 Now you can query the :ref:`match object <match-objects>` for information
-about the matching string.  :ref:`match object <match-objects>` instances
+about the matching string.  Match object instances
 also have several methods and attributes; the most important ones are:
 
 +------------------+--------------------------------------------+
@@ -430,18 +426,18 @@ Trying these methods will soon clarify their meaning::
    >>> m.span()
    (0, 5)
 
-:meth:`~re.match.group` returns the substring that was matched by the RE.  :meth:`~re.match.start`
+:meth:`~re.Match.group` returns the substring that was matched by the RE.  :meth:`~re.Match.start`
-and :meth:`~re.match.end` return the starting and ending index of the match. :meth:`~re.match.span`
+and :meth:`~re.Match.end` return the starting and ending index of the match. :meth:`~re.Match.span`
-returns both start and end indexes in a single tuple.  Since the :meth:`match`
+returns both start and end indexes in a single tuple.  Since the :meth:`~re.Pattern.match`
-method only checks if the RE matches at the start of a string, :meth:`start`
+method only checks if the RE matches at the start of a string, :meth:`!start`
-will always be zero.  However, the :meth:`search` method of patterns
+will always be zero.  However, the :meth:`~re.Pattern.search` method of patterns
 scans through the string, so  the match may not start at zero in that
 case. ::
 
    >>> print(p.match('::: message'))
    None
-   >>> m = p.search('::: message'); print(m)  #doctest: +ELLIPSIS
+   >>> m = p.search('::: message'); print(m)
-   <_sre.SRE_Match object; span=(4, 11), match='message'>
+   <re.Match object; span=(4, 11), match='message'>
    >>> m.group()
    'message'
    >>> m.span()
@@ -459,14 +455,14 @@ In actual programs, the most common style is to store the
        print('No match')
 
 Two pattern methods return all of the matches for a pattern.
-:meth:`~re.regex.findall` returns a list of matching strings::
+:meth:`~re.Pattern.findall` returns a list of matching strings::
 
    >>> p = re.compile('\d+')
    >>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')
    ['12', '11', '10']
 
-:meth:`findall` has to create the entire list before it can be returned as the
+:meth:`~re.Pattern.findall` has to create the entire list before it can be returned as the
-result.  The :meth:`~re.regex.finditer` method returns a sequence of
+result.  The :meth:`~re.Pattern.finditer` method returns a sequence of
 :ref:`match object <match-objects>` instances as an :term:`iterator`::
 
    >>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')
@@ -493,7 +489,7 @@ the RE string added as the first argument, and still return either ``None`` or a
    >>> print(re.match(r'From\s+', 'Fromage amk'))
    None
    >>> re.match(r'From\s+', 'From amk Thu May 14 19:12:10 1998')  #doctest: +ELLIPSIS
-   <_sre.SRE_Match object; span=(0, 5), match='From '>
+   <re.Match object; span=(0, 5), match='From '>
 
 Under the hood, these functions simply create a pattern object for you
 and call the appropriate method on it.  They also store the compiled
@@ -529,14 +525,14 @@ of each one.
 |                                 | characters with the respective property.   |
 +---------------------------------+--------------------------------------------+
 | :const:`DOTALL`, :const:`S`     | Make ``.`` match any character, including  |
-|                                 | newlines                                   |
+|                                 | newlines.                                  |
 +---------------------------------+--------------------------------------------+
-| :const:`IGNORECASE`, :const:`I` | Do case-insensitive matches                |
+| :const:`IGNORECASE`, :const:`I` | Do case-insensitive matches.               |
 +---------------------------------+--------------------------------------------+
-| :const:`LOCALE`, :const:`L`     | Do a locale-aware match                    |
+| :const:`LOCALE`, :const:`L`     | Do a locale-aware match.                   |
 +---------------------------------+--------------------------------------------+
 | :const:`MULTILINE`, :const:`M`  | Multi-line matching, affecting ``^`` and   |
-|                                 | ``$``                                      |
+|                                 | ``$``.                                     |
 +---------------------------------+--------------------------------------------+
 | :const:`VERBOSE`, :const:`X`    | Enable verbose REs, which can be organized |
 | (for 'extended')                | more cleanly and understandably.           |
@@ -549,27 +545,41 @@ of each one.
 
    Perform case-insensitive matching; character class and literal strings will
    match letters by ignoring case.  For example, ``[A-Z]`` will match lowercase
-   letters, too, and ``Spam`` will match ``Spam``, ``spam``, or ``spAM``. This
+   letters, too. Full Unicode matching also works unless the :const:`ASCII`
-   lowercasing doesn't take the current locale into account; it will if you also
+   flag is used to disable non-ASCII matches.  When the Unicode patterns
-   set the :const:`LOCALE` flag.
+   ``[a-z]`` or ``[A-Z]`` are used in combination with the :const:`IGNORECASE`
+   flag, they will match the 52 ASCII letters and 4 additional non-ASCII
+   letters: 'İ' (U+0130, Latin capital letter I with dot above), 'ı' (U+0131,
+   Latin small letter dotless i), 'ſ' (U+017F, Latin small letter long s) and
+   'K' (U+212A, Kelvin sign).  ``Spam`` will match ``'Spam'``, ``'spam'``,
+   ``'spAM'``, or ``'ſpam'`` (the latter is matched only in Unicode mode).
+   This lowercasing doesn't take the current locale into account;
+   it will if you also set the :const:`LOCALE` flag.
 
 
 .. data:: L
           LOCALE
    :noindex:
 
-   Make ``\w``, ``\W``, ``\b``, and ``\B``, dependent on the current locale
+   Make ``\w``, ``\W``, ``\b``, ``\B`` and case-insensitive matching dependent
-   instead of the Unicode database.
+   on the current locale instead of the Unicode database.
 
-   Locales are a feature of the C library intended to help in writing programs that
+   Locales are a feature of the C library intended to help in writing programs
-   take account of language differences.  For example, if you're processing French
+   that take account of language differences.  For example, if you're
-   text, you'd want to be able to write ``\w+`` to match words, but ``\w`` only
+   processing encoded French text, you'd want to be able to write ``\w+`` to
-   matches the character class ``[A-Za-z]``; it won't match ``'é'`` or ``'ç'``.  If
+   match words, but ``\w`` only matches the character class ``[A-Za-z]`` in
-   your system is configured properly and a French locale is selected, certain C
+   bytes patterns; it won't match bytes corresponding to ``é`` or ``ç``.
-   functions will tell the program that ``'é'`` should also be considered a letter.
+   If your system is configured properly and a French locale is selected,
+   certain C functions will tell the program that the byte corresponding to
+   ``é`` should also be considered a letter.
    Setting the :const:`LOCALE` flag when compiling a regular expression will cause
    the resulting compiled object to use these C functions for ``\w``; this is
    slower, but also enables ``\w+`` to match French words as you'd expect.
+   The use of this flag is discouraged in Python 3 as the locale mechanism
+   is very unreliable, it only handles one "culture" at a time, and it only
+   works with 8-bit locales.  Unicode matching is already enabled by default
+   in Python 3 for Unicode (str) patterns, and it is able to handle different
+   locales/languages.
 
 
 .. data:: M
@@ -667,11 +677,11 @@ zero-width assertions should never be repeated, because if they match once at a
 given location, they can obviously be matched an infinite number of times.
 
 ``|``
-   Alternation, or the "or" operator.   If A and B are regular expressions,
+   Alternation, or the "or" operator.   If *A* and *B* are regular expressions,
-   ``A|B`` will match any string that matches either ``A`` or ``B``. ``|`` has very
+   ``A|B`` will match any string that matches either *A* or *B*. ``|`` has very
    low precedence in order to make it work reasonably when you're alternating
-   multi-character strings. ``Crow|Servo`` will match either ``Crow`` or ``Servo``,
+   multi-character strings. ``Crow|Servo`` will match either ``'Crow'`` or ``'Servo'``,
-   not ``Cro``, a ``'w'`` or an ``'S'``, and ``ervo``.
+   not ``'Cro'``, a ``'w'`` or an ``'S'``, and ``'ervo'``.
 
    To match a literal ``'|'``, use ``\|``, or enclose it inside a character class,
    as in ``[|]``.
@@ -685,23 +695,22 @@ given location, they can obviously be matched an infinite number of times.
    line, the RE to use is ``^From``. ::
 
       >>> print(re.search('^From', 'From Here to Eternity'))  #doctest: +ELLIPSIS
-      <_sre.SRE_Match object; span=(0, 4), match='From'>
+      <re.Match object; span=(0, 4), match='From'>
       >>> print(re.search('^From', 'Reciting From Memory'))
       None
 
-   .. To match a literal \character{\^}, use \regexp{\e\^} or enclose it
+   To match a literal ``'^'``, use ``\^``.
-   .. inside a character class, as in \regexp{[{\e}\^]}.
 
 ``$``
    Matches at the end of a line, which is defined as either the end of the string,
    or any location followed by a newline character.     ::
 
       >>> print(re.search('}$', '{block}'))  #doctest: +ELLIPSIS
-      <_sre.SRE_Match object; span=(6, 7), match='}'>
+      <re.Match object; span=(6, 7), match='}'>
       >>> print(re.search('}$', '{block} '))
       None
       >>> print(re.search('}$', '{block}\n'))  #doctest: +ELLIPSIS
-      <_sre.SRE_Match object; span=(6, 7), match='}'>
+      <re.Match object; span=(6, 7), match='}'>
 
    To match a literal ``'$'``, use ``\$`` or enclose it inside a character class,
    as in  ``[$]``.
@@ -725,8 +734,8 @@ given location, they can obviously be matched an infinite number of times.
    match when it's contained inside another word. ::
 
       >>> p = re.compile(r'\bclass\b')
-      >>> print(p.search('no class at all'))  #doctest: +ELLIPSIS
+      >>> print(p.search('no class at all'))
-      <_sre.SRE_Match object; span=(3, 8), match='class'>
+      <re.Match object; span=(3, 8), match='class'>
       >>> print(p.search('the declassified algorithm'))
       None
       >>> print(p.search('one subclass is'))
@@ -743,8 +752,8 @@ given location, they can obviously be matched an infinite number of times.
       >>> p = re.compile('\bclass\b')
       >>> print(p.search('no class at all'))
       None
-      >>> print(p.search('\b' + 'class' + '\b'))  #doctest: +ELLIPSIS
+      >>> print(p.search('\b' + 'class' + '\b'))
-      <_sre.SRE_Match object; span=(0, 7), match='\x08class\x08'>
+      <re.Match object; span=(0, 7), match='\x08class\x08'>
 
    Second, inside a character class, where there's no use for this assertion,
    ``\b`` represents the backspace character, for compatibility with Python's
@@ -786,7 +795,8 @@ of a group with a repeating qualifier, such as ``*``, ``+``, ``?``, or
 
 Groups indicated with ``'('``, ``')'`` also capture the starting and ending
 index of the text that they match; this can be retrieved by passing an argument
-to :meth:`group`, :meth:`start`, :meth:`end`, and :meth:`span`.  Groups are
+to :meth:`~re.Match.group`, :meth:`~re.Match.start`, :meth:`~re.Match.end`, and
+:meth:`~re.Match.span`.  Groups are
 numbered starting with 0.  Group 0 is always present; it's the whole RE, so
 :ref:`match object <match-objects>` methods all have group 0 as their default
 argument.  Later we'll see how to express groups that don't capture the span
@@ -812,13 +822,13 @@ from left to right. ::
    >>> m.group(2)
    'b'
 
-:meth:`group` can be passed multiple group numbers at a time, in which case it
+:meth:`~re.Match.group` can be passed multiple group numbers at a time, in which case it
 will return a tuple containing the corresponding values for those groups. ::
 
    >>> m.group(2,1,2)
    ('b', 'abc', 'b')
 
-The :meth:`groups` method returns a tuple containing the strings for all the
+The :meth:`~re.Match.groups` method returns a tuple containing the strings for all the
 subgroups, from 1 up to however many there are. ::
 
    >>> m.groups()
@@ -1034,7 +1044,7 @@ using the following pattern methods:
 | ``sub()``        | Find all substrings where the RE matches, and |
 |                  | replace them with a different string          |
 +------------------+-----------------------------------------------+
-| ``subn()``       | Does the same thing as :meth:`sub`,  but      |
+| ``subn()``       | Does the same thing as :meth:`!sub`,  but     |
 |                  | returns the new string and the number of      |
 |                  | replacements                                  |
 +------------------+-----------------------------------------------+
@@ -1043,10 +1053,10 @@ using the following pattern methods:
 Splitting Strings
 -----------------
 
-The :meth:`split` method of a pattern splits a string apart
+The :meth:`~re.Pattern.split` method of a pattern splits a string apart
 wherever the RE matches, returning a list of the pieces. It's similar to the
-:meth:`split` method of strings but provides much more generality in the
+:meth:`~str.split` method of strings but provides much more generality in the
-delimiters that you can split by; string :meth:`split` only supports splitting by
+delimiters that you can split by; string :meth:`!split` only supports splitting by
 whitespace or by a fixed string.  As you'd expect, there's a module-level
 :func:`re.split` function, too.
 
@@ -1098,7 +1108,7 @@ Search and Replace
 ------------------
 
 Another common task is to find all the matches for a pattern, and replace them
-with a different string.  The :meth:`sub` method takes a replacement value,
+with a different string.  The :meth:`~re.Pattern.sub` method takes a replacement value,
 which can be either a string or a function, and the string to be processed.
 
 .. method:: .sub(replacement, string[, count=0])
@@ -1112,7 +1122,7 @@ which can be either a string or a function, and the string to be processed.
    replaced; *count* must be a non-negative integer.  The default value of 0 means
    to replace all occurrences.
 
-Here's a simple example of using the :meth:`sub` method.  It replaces colour
+Here's a simple example of using the :meth:`~re.Pattern.sub` method.  It replaces colour
 names with the word ``colour``::
 
    >>> p = re.compile('(blue|white|red)')
@@ -1121,7 +1131,7 @@ names with the word ``colour``::
    >>> p.sub('colour', 'blue socks and red shoes', count=1)
    'colour socks and red shoes'
 
-The :meth:`subn` method does the same work, but returns a 2-tuple containing the
+The :meth:`~re.Pattern.subn` method does the same work, but returns a 2-tuple containing the
 new string value and the number of replacements  that were performed::
 
    >>> p = re.compile('(blue|white|red)')
@@ -1206,24 +1216,24 @@ Use String Methods
 
 Sometimes using the :mod:`re` module is a mistake.  If you're matching a fixed
 string, or a single character class, and you're not using any :mod:`re` features
-such as the :const:`IGNORECASE` flag, then the full power of regular expressions
+such as the :const:`~re.IGNORECASE` flag, then the full power of regular expressions
 may not be required. Strings have several methods for performing operations with
 fixed strings and they're usually much faster, because the implementation is a
 single small C loop that's been optimized for the purpose, instead of the large,
 more generalized regular expression engine.
 
 One example might be replacing a single fixed string with another one; for
-example, you might replace ``word`` with ``deed``.  ``re.sub()`` seems like the
+example, you might replace ``word`` with ``deed``.  :func:`re.sub` seems like the
-function to use for this, but consider the :meth:`replace` method.  Note that
+function to use for this, but consider the :meth:`~str.replace` method.  Note that
-:func:`replace` will also replace ``word`` inside words, turning ``swordfish``
+:meth:`!replace` will also replace ``word`` inside words, turning ``swordfish``
 into ``sdeedfish``, but the  naive RE ``word`` would have done that, too.  (To
 avoid performing the substitution on parts of words, the pattern would have to
 be ``\bword\b``, in order to require that ``word`` have a word boundary on
-either side.  This takes the job beyond  :meth:`replace`'s abilities.)
+either side.  This takes the job beyond  :meth:`!replace`'s abilities.)
 
 Another common task is deleting every occurrence of a single character from a
 string or replacing it with another single character.  You might do this with
-something like ``re.sub('\n', ' ', S)``, but :meth:`translate` is capable of
+something like ``re.sub('\n', ' ', S)``, but :meth:`~str.translate` is capable of
 doing both tasks and will be faster than any regular expression operation can
 be.
 
@@ -1234,18 +1244,18 @@ can be solved with a faster and simpler string method.
 match() versus search()
 -----------------------
 
-The :func:`match` function only checks if the RE matches at the beginning of the
+The :func:`~re.match` function only checks if the RE matches at the beginning of the
-string while :func:`search` will scan forward through the string for a match.
+string while :func:`~re.search` will scan forward through the string for a match.
-It's important to keep this distinction in mind.  Remember,  :func:`match` will
+It's important to keep this distinction in mind.  Remember,  :func:`!match` will
 only report a successful match which will start at 0; if the match wouldn't
-start at zero,  :func:`match` will *not* report it. ::
+start at zero,  :func:`!match` will *not* report it. ::
 
    >>> print(re.match('super', 'superstition').span())
    (0, 5)
    >>> print(re.match('super', 'insuperable'))
    None
 
-On the other hand, :func:`search` will scan forward through the string,
+On the other hand, :func:`~re.search` will scan forward through the string,
 reporting the first match it finds. ::
 
    >>> print(re.search('super', 'superstition').span())
@@ -1284,12 +1294,12 @@ doesn't work because of the greedy nature of ``.*``. ::
    >>> print(re.match('<.*>', s).group())
    <html><head><title>Title</title>
 
-The RE matches the ``'<'`` in ``<html>``, and the ``.*`` consumes the rest of
+The RE matches the ``'<'`` in ``'<html>'``, and the ``.*`` consumes the rest of
 the string.  There's still more left in the RE, though, and the ``>`` can't
 match at the end of the string, so the regular expression engine has to
 backtrack character by character until it finds a match for the ``>``.   The
-final match extends from the ``'<'`` in ``<html>`` to the ``'>'`` in
+final match extends from the ``'<'`` in ``'<html>'`` to the ``'>'`` in
-``</title>``, which isn't what you want.
+``'</title>'``, which isn't what you want.
 
 In this case, the solution is to use the non-greedy qualifiers ``*?``, ``+?``,
 ``??``, or ``{m,n}?``, which match as *little* text as possible.  In the above
@@ -1315,7 +1325,7 @@ notation, but they're not terribly readable.  REs of moderate complexity can
 become lengthy collections of backslashes, parentheses, and metacharacters,
 making them difficult to read and understand.
 
-For such REs, specifying the ``re.VERBOSE`` flag when compiling the regular
+For such REs, specifying the :const:`re.VERBOSE` flag when compiling the regular
 expression can be helpful, because it allows you to format the regular
 expression more clearly.
 
@@ -1354,5 +1364,5 @@ Friedl's Mastering Regular Expressions, published by O'Reilly.  Unfortunately,
 it exclusively concentrates on Perl and Java's flavours of regular expressions,
 and doesn't contain any Python material at all, so it won't be useful as a
 reference for programming in Python.  (The first edition covered Python's
-now-removed :mod:`regex` module, which won't help you much.)  Consider checking
+now-removed :mod:`!regex` module, which won't help you much.)  Consider checking
 it out from your library.

Doc/includes/email-alternative.py

@@ -32,7 +32,7 @@ msg.add_alternative("""\
   <body>
     <p>Salut!</p>
     <p>Cela ressemble à un excellent
-        <a href="http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718>
+        <a href="http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718">
             recipie
         </a> déjeuner.
     </p>

Doc/includes/noddy.c

@@ -27,6 +27,23 @@ static PyTypeObject noddy_NoddyType = {
     0,                         /* tp_as_buffer */
     Py_TPFLAGS_DEFAULT,        /* tp_flags */
     "Noddy objects",           /* tp_doc */
+    0,                         /* tp_traverse */
+    0,                         /* tp_clear */
+    0,                         /* tp_richcompare */
+    0,                         /* tp_weaklistoffset */
+    0,                         /* tp_iter */
+    0,                         /* tp_iternext */
+    0,                         /* tp_methods */
+    0,                         /* tp_members */
+    0,                         /* tp_getset */
+    0,                         /* tp_base */
+    0,                         /* tp_dict */
+    0,                         /* tp_descr_get */
+    0,                         /* tp_descr_set */
+    0,                         /* tp_dictoffset */
+    0,                         /* tp_init */
+    0,                         /* tp_alloc */
+    PyType_GenericNew,         /* tp_new */
 };
 
 static PyModuleDef noddymodule = {
@@ -42,7 +59,6 @@ PyInit_noddy(void)
 {
     PyObject* m;
 
-    noddy_NoddyType.tp_new = PyType_GenericNew;
     if (PyType_Ready(&noddy_NoddyType) < 0)
         return NULL;
 

Doc/includes/noddy4.c

@@ -46,6 +46,7 @@ Noddy_clear(Noddy *self)
 static void
 Noddy_dealloc(Noddy* self)
 {
+    PyObject_GC_UnTrack(self);
     Noddy_clear(self);
     Py_TYPE(self)->tp_free((PyObject*)self);
 }

Doc/includes/sqlite3/load_extension.py

@@ -11,7 +11,7 @@ con.execute("select load_extension('./fts3.so')")
 # alternatively you can load the extension using an API call:
 # con.load_extension("./fts3.so")
 
-# disable extension laoding again
+# disable extension loading again
 con.enable_load_extension(False)
 
 # example from SQLite wiki

Doc/installing/index.rst

@@ -211,6 +211,17 @@ On such systems, it is often better to use a virtual environment or a
 per-user installation when installing packages with ``pip``.
 
 
+Pip not installed
+-----------------
+
+It is possible that ``pip`` does not get installed by default. One potential fix is::
+
+    python -m ensurepip --default-pip
+
+There are also additional resources for `installing pip.
+<https://packaging.python.org/tutorials/installing-packages/#install-pip-setuptools-and-wheel>`__
+
+
 Installing binary extensions
 ----------------------------
 

Doc/library/2to3.rst

@@ -288,7 +288,8 @@ and off individually.  They are described here in more detail.
 
    Fixes duplicate types in the second argument of :func:`isinstance`.  For
    example, ``isinstance(x, (int, int))`` is converted to ``isinstance(x,
-   (int))``.
+   int)`` and ``isinstance(x, (int, float, int))`` is converted to
+   ``isinstance(x, (int, float))``.
 
 .. 2to3fixer:: itertools_imports
 
@@ -344,20 +345,20 @@ and off individually.  They are described here in more detail.
 
    Converts calls to various functions in the :mod:`operator` module to other,
    but equivalent, function calls.  When needed, the appropriate ``import``
-   statements are added, e.g. ``import collections``.  The following mapping
+   statements are added, e.g. ``import collections.abc``.  The following mapping
    are made:
 
-   ==================================  ==========================================
+   ==================================  =============================================
    From                                To
-   ==================================  ==========================================
+   ==================================  =============================================
    ``operator.isCallable(obj)``        ``hasattr(obj, '__call__')``
    ``operator.sequenceIncludes(obj)``  ``operator.contains(obj)``
-   ``operator.isSequenceType(obj)``    ``isinstance(obj, collections.Sequence)``
+   ``operator.isSequenceType(obj)``    ``isinstance(obj, collections.abc.Sequence)``
-   ``operator.isMappingType(obj)``     ``isinstance(obj, collections.Mapping)``
+   ``operator.isMappingType(obj)``     ``isinstance(obj, collections.abc.Mapping)``
    ``operator.isNumberType(obj)``      ``isinstance(obj, numbers.Number)``
    ``operator.repeat(obj, n)``         ``operator.mul(obj, n)``
    ``operator.irepeat(obj, n)``        ``operator.imul(obj, n)``
-   ==================================  ==========================================
+   ==================================  =============================================
 
 .. 2to3fixer:: paren
 

Doc/library/_dummy_thread.rst

@@ -6,18 +6,15 @@
 
 **Source code:** :source:`Lib/_dummy_thread.py`
 
+.. deprecated:: 3.7
+   Python now always has threading enabled.  Please use :mod:`_thread`
+   (or, better, :mod:`threading`) instead.
+
 --------------
 
-This module provides a duplicate interface to the :mod:`_thread` module.  It is
+This module provides a duplicate interface to the :mod:`_thread` module.
-meant to be imported when the :mod:`_thread` module is not provided on a
+It was meant to be imported when the :mod:`_thread` module was not provided
-platform.
+on a platform.
-
-Suggested usage is::
-
-   try:
-       import _thread
-   except ImportError:
-       import _dummy_thread as _thread
 
 Be careful to not use this module where deadlock might occur from a thread being
 created that blocks waiting for another thread to be created.  This often occurs

Doc/library/_thread.rst

@@ -23,14 +23,10 @@ threading API built on top of this module.
    single: pthreads
    pair: threads; POSIX
 
-The module is optional.  It is supported on Windows, Linux, SGI IRIX, Solaris
+.. versionchanged:: 3.7
-2.x, as well as on systems that have a POSIX thread (a.k.a. "pthread")
+   This module used to be optional, it is now always available.
-implementation.  For systems lacking the :mod:`_thread` module, the
-:mod:`_dummy_thread` module is available. It duplicates this module's interface
-and can be used as a drop-in replacement.
-
-It defines the following constants and functions:
 
+This module defines the following constants and functions:
 
 .. exception:: error
 

Doc/library/abc.rst

@@ -24,7 +24,33 @@ a class or instance provides a particular interface, for example, is it
 hashable or a mapping.
 
 
-This module provides the following classes:
+This module provides the metaclass :class:`ABCMeta` for defining ABCs and
+a helper class :class:`ABC` to alternatively define ABCs through inheritance:
+
+.. class:: ABC
+
+   A helper class that has :class:`ABCMeta` as its metaclass.  With this class,
+   an abstract base class can be created by simply deriving from :class:`ABC`
+   avoiding sometimes confusing metaclass usage, for example::
+
+     from abc import ABC
+
+     class MyABC(ABC):
+         pass
+
+   Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore
+   inheriting from :class:`ABC` requires the usual precautions regarding
+   metaclass usage, as multiple inheritance may lead to metaclass conflicts.
+   One may also define an abstract base class by passing the metaclass
+   keyword and using :class:`ABCMeta` directly, for example::
+
+     from abc import ABCMeta
+
+     class MyABC(metaclass=ABCMeta):
+         pass
+
+   .. versionadded:: 3.4
+
 
 .. class:: ABCMeta
 
@@ -46,9 +72,9 @@ This module provides the following classes:
       Register *subclass* as a "virtual subclass" of this ABC. For
       example::
 
-        from abc import ABCMeta
+         from abc import ABC
 
-        class MyABC(metaclass=ABCMeta):
+         class MyABC(ABC):
              pass
 
          MyABC.register(tuple)
@@ -95,7 +121,7 @@ This module provides the following classes:
           def get_iterator(self):
               return iter(self)
 
-      class MyIterable(metaclass=ABCMeta):
+      class MyIterable(ABC):
 
           @abstractmethod
           def __iter__(self):
@@ -132,17 +158,6 @@ This module provides the following classes:
    available as a method of ``Foo``, so it is provided separately.
 
 
-.. class:: ABC
-
-   A helper class that has :class:`ABCMeta` as its metaclass.  With this class,
-   an abstract base class can be created by simply deriving from :class:`ABC`,
-   avoiding sometimes confusing metaclass usage.
-
-   Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore
-   inheriting from :class:`ABC` requires the usual precautions regarding metaclass
-   usage, as multiple inheritance may lead to metaclass conflicts.
-
-   .. versionadded:: 3.4
 
 
 The :mod:`abc` module also provides the following decorators:
@@ -168,7 +183,7 @@ The :mod:`abc` module also provides the following decorators:
    descriptors, it should be applied as the innermost decorator, as shown in
    the following usage examples::
 
-      class C(metaclass=ABCMeta):
+      class C(ABC):
           @abstractmethod
           def my_abstract_method(self, ...):
               ...
@@ -230,7 +245,7 @@ The :mod:`abc` module also provides the following decorators:
    is now correctly identified as abstract when applied to an abstract
    method::
 
-      class C(metaclass=ABCMeta):
+      class C(ABC):
           @classmethod
           @abstractmethod
           def my_abstract_classmethod(cls, ...):
@@ -251,7 +266,7 @@ The :mod:`abc` module also provides the following decorators:
    is now correctly identified as abstract when applied to an abstract
    method::
 
-      class C(metaclass=ABCMeta):
+      class C(ABC):
           @staticmethod
           @abstractmethod
           def my_abstract_staticmethod(...):
@@ -263,7 +278,7 @@ The :mod:`abc` module also provides the following decorators:
        :func:`abstractmethod`, making this decorator redundant.
 
 
-.. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None)
+.. decorator:: abstractproperty
 
    A subclass of the built-in :func:`property`, indicating an abstract
    property.
@@ -278,7 +293,7 @@ The :mod:`abc` module also provides the following decorators:
    is now correctly identified as abstract when applied to an abstract
    method::
 
-      class C(metaclass=ABCMeta):
+      class C(ABC):
           @property
           @abstractmethod
           def my_abstract_property(self):
@@ -288,7 +303,7 @@ The :mod:`abc` module also provides the following decorators:
    read-write abstract property by appropriately marking one or more of the
    underlying methods as abstract::
 
-      class C(metaclass=ABCMeta):
+      class C(ABC):
           @property
           def x(self):
               ...

Doc/library/aifc.rst

@@ -18,12 +18,6 @@ AIFF is Audio Interchange File Format, a format for storing digital audio
 samples in a file.  AIFF-C is a newer version of the format that includes the
 ability to compress the audio data.
 
-.. note::
-
-   Some operations may only work under IRIX; these will raise :exc:`ImportError`
-   when attempting to import the :mod:`cl` module, which is only available on
-   IRIX.
-
 Audio files have a number of parameters that describe the audio data. The
 sampling rate or frame rate is the number of times per second the sound is
 sampled.  The number of channels indicate if the audio is mono, stereo, or

Doc/library/argparse.rst

@@ -426,7 +426,9 @@ should not be line-wrapped::
     -h, --help  show this help message and exit
 
 :class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
-including argument descriptions.
+including argument descriptions. However, multiple new lines are replaced with
+one. If you wish to preserve multiple blank lines, add spaces between the
+newlines.
 
 :class:`ArgumentDefaultsHelpFormatter` automatically adds information about
 default values to each of the argument help messages::
@@ -898,6 +900,8 @@ values are:
      usage: PROG [-h] foo [foo ...]
      PROG: error: too few arguments
 
+.. _`argparse.REMAINDER`:
+
 * ``argparse.REMAINDER``.  All the remaining command-line arguments are gathered
   into a list.  This is commonly useful for command line utilities that dispatch
   to other command line utilities::
@@ -1324,8 +1328,11 @@ The parse_args() method
    created and how they are assigned. See the documentation for
    :meth:`add_argument` for details.
 
-   By default, the argument strings are taken from :data:`sys.argv`, and a new empty
+   * args_ - List of strings to parse.  The default is taken from
-   :class:`Namespace` object is created for the attributes.
+     :data:`sys.argv`.
+
+   * namespace_ - An object to take the attributes.  The default is a new empty
+     :class:`Namespace` object.
 
 
 Option value syntax
@@ -1467,6 +1474,7 @@ unambiguous (the prefix matches a unique option)::
 An error is produced for arguments that could produce more than one options.
 This feature can be disabled by setting :ref:`allow_abbrev` to ``False``.
 
+.. _args:
 
 Beyond ``sys.argv``
 ^^^^^^^^^^^^^^^^^^^
@@ -1488,6 +1496,7 @@ interactive prompt::
    >>> parser.parse_args(['1', '2', '3', '4', '--sum'])
    Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
 
+.. _namespace:
 
 The Namespace object
 ^^^^^^^^^^^^^^^^^^^^
@@ -1530,8 +1539,8 @@ Sub-commands
 
 .. method:: ArgumentParser.add_subparsers([title], [description], [prog], \
                                           [parser_class], [action], \
-                                          [option_string], [dest], [help], \
+                                          [option_string], [dest], [required] \
-                                          [metavar])
+                                          [help], [metavar])
 
    Many programs split up their functionality into a number of sub-commands,
    for example, the ``svn`` program can invoke sub-commands like ``svn
@@ -1567,6 +1576,9 @@ Sub-commands
    * dest_ - name of the attribute under which sub-command name will be
      stored; by default ``None`` and no value is stored
 
+   * required_ - Whether or not a subcommand must be provided, by default
+     ``True``.
+
    * help_ - help for sub-parser group in help output, by default ``None``
 
    * metavar_ - string presenting available sub-commands in help; by default it
@@ -1978,6 +1990,45 @@ Exiting methods
    This method prints a usage message including the *message* to the
    standard error and terminates the program with a status code of 2.
 
+
+Intermixed parsing
+^^^^^^^^^^^^^^^^^^
+
+.. method:: ArgumentParser.parse_intermixed_args(args=None, namespace=None)
+.. method:: ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)
+
+A number of Unix commands allow the user to intermix optional arguments with
+positional arguments.  The :meth:`~ArgumentParser.parse_intermixed_args`
+and :meth:`~ArgumentParser.parse_known_intermixed_args` methods
+support this parsing style.
+
+These parsers do not support all the argparse features, and will raise
+exceptions if unsupported features are used.  In particular, subparsers,
+``argparse.REMAINDER``, and mutually exclusive groups that include both
+optionals and positionals are not supported.
+
+The following example shows the difference between
+:meth:`~ArgumentParser.parse_known_args` and
+:meth:`~ArgumentParser.parse_intermixed_args`: the former returns ``['2',
+'3']`` as unparsed arguments, while the latter collects all the positionals
+into ``rest``.  ::
+
+   >>> parser = argparse.ArgumentParser()
+   >>> parser.add_argument('--foo')
+   >>> parser.add_argument('cmd')
+   >>> parser.add_argument('rest', nargs='*', type=int)
+   >>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
+   (Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
+   >>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
+   Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])
+
+:meth:`~ArgumentParser.parse_known_intermixed_args` returns a two item tuple
+containing the populated namespace and the list of remaining argument strings.
+:meth:`~ArgumentParser.parse_intermixed_args` raises an error if there are any
+remaining unparsed argument strings.
+
+.. versionadded:: 3.7
+
 .. _upgrading-optparse-code:
 
 Upgrading optparse code
@@ -2008,7 +2059,11 @@ A partial upgrade path from :mod:`optparse` to :mod:`argparse`:
 * Replace ``(options, args) = parser.parse_args()`` with ``args =
   parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
   calls for the positional arguments. Keep in mind that what was previously
-  called ``options``, now in :mod:`argparse` context is called ``args``.
+  called ``options``, now in the :mod:`argparse` context is called ``args``.
+
+* Replace :meth:`optparse.OptionParser.disable_interspersed_args`
+  by using :meth:`~ArgumentParser.parse_intermixed_args` instead of
+  :meth:`~ArgumentParser.parse_args`.
 
 * Replace callback actions and the ``callback_*`` keyword arguments with
   ``type`` or ``action`` arguments.

Doc/library/asyncio-dev.rst

@@ -21,7 +21,9 @@ enable *debug mode*.
 To enable all debug checks for an application:
 
 * Enable the asyncio debug mode globally by setting the environment variable
-  :envvar:`PYTHONASYNCIODEBUG` to ``1``, or by calling :meth:`AbstractEventLoop.set_debug`.
+  :envvar:`PYTHONASYNCIODEBUG` to ``1``, using ``-X dev`` command line option
+  (see the :option:`-X` option), or by calling
+  :meth:`AbstractEventLoop.set_debug`.
 * Set the log level of the :ref:`asyncio logger <asyncio-logger>` to
   :py:data:`logging.DEBUG`. For example, call
   ``logging.basicConfig(level=logging.DEBUG)`` at startup.
@@ -42,6 +44,11 @@ Examples debug checks:
 * :exc:`ResourceWarning` warnings are emitted when transports and event loops
   are :ref:`not closed explicitly <asyncio-close-transports>`.
 
+.. versionchanged:: 3.7
+
+   The new ``-X dev`` command line option can now also be used to enable
+   the debug mode.
+
 .. seealso::
 
    The :meth:`AbstractEventLoop.set_debug` method and the :ref:`asyncio logger
@@ -52,7 +59,7 @@ Cancellation
 ------------
 
 Cancellation of tasks is not common in classic programming. In asynchronous
-programming, not only it is something common, but you have to prepare your
+programming, not only is it something common, but you have to prepare your
 code to handle it.
 
 Futures and tasks can be cancelled explicitly with their :meth:`Future.cancel`

Doc/library/asyncio-eventloop.rst

@@ -5,6 +5,8 @@
 Base Event Loop
 ===============
 
+**Source code:** :source:`Lib/asyncio/events.py`
+
 The event loop is the central execution device provided by :mod:`asyncio`.
 It provides multiple facilities, including:
 
@@ -339,9 +341,10 @@ Creating connections
 
 .. coroutinemethod:: AbstractEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)
 
-   Create datagram connection: socket family :py:data:`~socket.AF_INET` or
+   Create datagram connection: socket family :py:data:`~socket.AF_INET`,
-   :py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
+   :py:data:`~socket.AF_INET6` or :py:data:`~socket.AF_UNIX` depending on
-   socket type :py:data:`~socket.SOCK_DGRAM`. *protocol_factory* must be a
+   *host* (or *family* if specified), socket type
+   :py:data:`~socket.SOCK_DGRAM`. *protocol_factory* must be a
    callable returning a :ref:`protocol <asyncio-protocol>` instance.
 
    This method is a :ref:`coroutine <coroutine>` which will try to
@@ -552,6 +555,21 @@ Low-level socket operations
 
    This method is a :ref:`coroutine <coroutine>`.
 
+.. coroutinemethod:: AbstractEventLoop.sock_recv_into(sock, buf)
+
+   Receive data from the socket.  Modeled after blocking
+   :meth:`socket.socket.recv_into` method.
+
+   The received data is written into *buf* (a writable buffer).
+   The return value is the number of bytes written.
+
+   With :class:`SelectorEventLoop` event loop, the socket *sock* must be
+   non-blocking.
+
+   This method is a :ref:`coroutine <coroutine>`.
+
+   .. versionadded:: 3.7
+
 .. coroutinemethod:: AbstractEventLoop.sock_sendall(sock, data)
 
    Send data to the socket.  Modeled after blocking
@@ -849,6 +867,12 @@ Handle
       Cancel the call.  If the callback is already canceled or executed,
       this method has no effect.
 
+   .. method:: cancelled()
+
+      Return ``True`` if the call was cancelled.
+
+      .. versionadded:: 3.7
+
 
 Event loop examples
 -------------------

Doc/library/asyncio-eventloops.rst

@@ -3,6 +3,8 @@
 Event loops
 ===========
 
+**Source code:** :source:`Lib/asyncio/events.py`
+
 Event loop functions
 --------------------
 
@@ -146,10 +148,9 @@ process based on the calling context. A policy is an object implementing the
 :class:`AbstractEventLoopPolicy` interface.
 
 For most users of :mod:`asyncio`, policies never have to be dealt with
-explicitly, since the default global policy is sufficient.
+explicitly, since the default global policy is sufficient (see below).
 
-The default policy defines context as the current thread, and manages an event
+The module-level functions
-loop per thread that interacts with :mod:`asyncio`. The module-level functions
 :func:`get_event_loop` and :func:`set_event_loop` provide convenient access to
 event loops managed by the default policy.
 
@@ -187,6 +188,13 @@ An event loop policy must implement the following interface:
       context, :meth:`set_event_loop` must be called explicitly.
 
 
+The default policy defines context as the current thread, and manages an event
+loop per thread that interacts with :mod:`asyncio`.  If the current thread
+doesn't already have an event loop associated with it, the default policy's
+:meth:`~AbstractEventLoopPolicy.get_event_loop` method creates one when
+called from the main thread, but raises :exc:`RuntimeError` otherwise.
+
+
 Access to the global loop policy
 --------------------------------
 
@@ -198,3 +206,24 @@ Access to the global loop policy
 
    Set the current event loop policy. If *policy* is ``None``, the default
    policy is restored.
+
+
+Customizing the event loop policy
+---------------------------------
+
+To implement a new event loop policy, it is recommended you subclass the
+concrete default event loop policy :class:`DefaultEventLoopPolicy`
+and override the methods for which you want to change behavior, for example::
+
+    class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
+
+        def get_event_loop(self):
+            """Get the event loop.
+
+            This may be None or an instance of EventLoop.
+            """
+            loop = super().get_event_loop()
+            # Do something with loop ...
+            return loop
+
+    asyncio.set_event_loop_policy(MyEventLoopPolicy())

Doc/library/asyncio-protocol.rst

@@ -1,8 +1,12 @@
 .. currentmodule:: asyncio
 
-++++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++
 Transports and protocols (callback based API)
-++++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++
+
+**Source code:** :source:`Lib/asyncio/transports.py`
+
+**Source code:** :source:`Lib/asyncio/protocols.py`
 
 .. _asyncio-transport:
 
@@ -163,11 +167,17 @@ WriteTransport
 
       Set the *high*- and *low*-water limits for write flow control.
 
-      These two values control when call the protocol's
+      These two values (measured in number of
+      bytes) control when the protocol's
       :meth:`pause_writing` and :meth:`resume_writing` methods are called.
       If specified, the low-water limit must be less than or equal to the
       high-water limit.  Neither *high* nor *low* can be negative.
 
+      :meth:`pause_writing` is called when the buffer size becomes greater
+      than or equal to the *high* value. If writing has been paused,
+      :meth:`resume_writing` is called when the buffer size becomes less
+      than or equal to the *low* value.
+
       The defaults are implementation-specific.  If only the
       high-water limit is given, the low-water limit defaults to an
       implementation-specific value less than or equal to the

Doc/library/asyncio-queue.rst

@@ -3,6 +3,8 @@
 Queues
 ======
 
+**Source code:** :source:`Lib/asyncio/queues.py`
+
 Queues:
 
 * :class:`Queue`

Doc/library/asyncio-stream.rst

@@ -6,6 +6,8 @@
 Streams (coroutine based API)
 +++++++++++++++++++++++++++++
 
+**Source code:** :source:`Lib/asyncio/streams.py`
+
 Stream functions
 ================
 

Doc/library/asyncio-subprocess.rst

@@ -5,6 +5,8 @@
 Subprocess
 ==========
 
+**Source code:** :source:`Lib/asyncio/subprocess.py`
+
 Windows event loop
 ------------------
 

Doc/library/asyncio-sync.rst

@@ -4,6 +4,8 @@
 Synchronization primitives
 ==========================
 
+**Source code:** :source:`Lib/asyncio/locks.py`
+
 Locks:
 
 * :class:`Lock`

Doc/library/asyncio-task.rst

@@ -3,6 +3,10 @@
 Tasks and coroutines
 ====================
 
+**Source code:** :source:`Lib/asyncio/tasks.py`
+
+**Source code:** :source:`Lib/asyncio/coroutines.py`
+
 .. _coroutine:
 
 Coroutines
@@ -212,7 +216,7 @@ Future
      raise an exception when the future isn't done yet.
 
    - Callbacks registered with :meth:`add_done_callback` are always called
-     via the event loop's :meth:`~AbstractEventLoop.call_soon_threadsafe`.
+     via the event loop's :meth:`~AbstractEventLoop.call_soon`.
 
    - This class is not compatible with the :func:`~concurrent.futures.wait` and
      :func:`~concurrent.futures.as_completed` functions in the
@@ -370,7 +374,7 @@ Task
    running in different threads. While a task waits for the completion of a
    future, the event loop executes a new task.
 
-   The cancellation of a task is different from the cancelation of a
+   The cancellation of a task is different from the cancellation of a
    future. Calling :meth:`cancel` will throw a
    :exc:`~concurrent.futures.CancelledError` to the wrapped
    coroutine. :meth:`~Future.cancelled` only returns ``True`` if the

Doc/library/atexit.rst

@@ -21,7 +21,7 @@ program is killed by a signal not handled by Python, when a Python fatal
 internal error is detected, or when :func:`os._exit` is called.
 
 
-.. function:: register(func, *args, **kargs)
+.. function:: register(func, *args, **kwargs)
 
    Register *func* as a function to be executed at termination.  Any optional
    arguments that are to be passed to *func* must be passed as arguments to

Doc/library/calendar.rst

@@ -19,11 +19,13 @@ the week to Sunday (6) or to any other weekday.  Parameters that specify dates
 are given as integers. For related
 functionality, see also the :mod:`datetime` and :mod:`time` modules.
 
-Most of these functions and classes rely on the :mod:`datetime` module which
+The functions and classes defined in this module
-uses an idealized calendar, the current Gregorian calendar extended
+use an idealized calendar, the current Gregorian calendar extended indefinitely
 in both directions.  This matches the definition of the "proleptic Gregorian"
 calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
-it's the base calendar for all computations.
+it's the base calendar for all computations.  Zero and negative years are
+interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
+2 BC, and so on.
 
 
 .. class:: Calendar(firstweekday=0)
@@ -53,17 +55,40 @@ it's the base calendar for all computations.
       month that are required to get a complete week.
 
 
-   .. method:: itermonthdays2(year, month)
-
-      Return an iterator for the month *month* in the year *year* similar to
-      :meth:`itermonthdates`. Days returned will be tuples consisting of a day
-      number and a week day number.
-
-
    .. method:: itermonthdays(year, month)
 
       Return an iterator for the month *month* in the year *year* similar to
-      :meth:`itermonthdates`. Days returned will simply be day numbers.
+      :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+      range. Days returned will simply be day of the month numbers.  For the
+      days outside of the specified month, the day number is ``0``.
+
+
+   .. method:: itermonthdays2(year, month)
+
+      Return an iterator for the month *month* in the year *year* similar to
+      :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+      range. Days returned will be tuples consisting of a day of the month
+      number and a week day number.
+
+
+   .. method:: itermonthdays3(year, month)
+
+      Return an iterator for the month *month* in the year *year* similar to
+      :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+      range. Days returned will be tuples consisting of a year, a month and a day
+      of the month numbers.
+
+      .. versionadded:: 3.7
+
+
+   .. method:: itermonthdays4(year, month)
+
+      Return an iterator for the month *month* in the year *year* similar to
+      :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+      range. Days returned will be tuples consisting of a year, a month, a day
+      of the month, and a day of the week numbers.
+
+      .. versionadded:: 3.7
 
 
    .. method:: monthdatescalendar(year, month)

Doc/library/codecs.rst

@@ -554,16 +554,16 @@ define in order to be compatible with the Python codec registry.
       if necessary, to reset the encoder and to get the output.
 
 
-.. method:: IncrementalEncoder.getstate()
+   .. method:: getstate()
 
       Return the current state of the encoder which must be an integer. The
-   implementation should make sure that ``0`` is the most common state. (States
+      implementation should make sure that ``0`` is the most common
-   that are more complicated than integers can be converted into an integer by
+      state. (States that are more complicated than integers can be converted
-   marshaling/pickling the state and encoding the bytes of the resulting string
+      into an integer by marshaling/pickling the state and encoding the bytes
-   into an integer).
+      of the resulting string into an integer).
 
 
-.. method:: IncrementalEncoder.setstate(state)
+   .. method:: setstate(state)
 
       Set the state of the encoder to *state*. *state* must be an encoder state
       returned by :meth:`getstate`.
@@ -802,7 +802,7 @@ The design is such that one can use the factory functions returned by the
 :func:`lookup` function to construct the instance.
 
 
-.. class:: StreamReaderWriter(stream, Reader, Writer, errors)
+.. class:: StreamReaderWriter(stream, Reader, Writer, errors='strict')
 
    Creates a :class:`StreamReaderWriter` instance. *stream* must be a file-like
    object. *Reader* and *Writer* must be factory functions or classes providing the
@@ -826,7 +826,7 @@ The design is such that one can use the factory functions returned by the
 :func:`lookup` function to construct the instance.
 
 
-.. class:: StreamRecoder(stream, encode, decode, Reader, Writer, errors)
+.. class:: StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')
 
    Creates a :class:`StreamRecoder` instance which implements a two-way conversion:
    *encode* and *decode* work on the frontend — the data visible to

Doc/library/collections.abc.rst

@@ -107,7 +107,12 @@ ABC                        Inherits from          Abstract Methods        Mixin
 .. class:: Iterable
 
    ABC for classes that provide the :meth:`__iter__` method.
-   See also the definition of :term:`iterable`.
+
+   Checking ``isinstance(obj, Iterable)`` detects classes that are registered
+   as :class:`Iterable` or that have an :meth:`__iter__` method, but it does
+   not detect classes that iterate with the :meth:`__getitem__` method.
+   The only reliable way to determine whether an object is :term:`iterable`
+   is to call ``iter(obj)``.
 
 .. class:: Collection
 

Doc/library/collections.rst

@@ -763,7 +763,7 @@ Named tuples assign meaning to each position in a tuple and allow for more reada
 self-documenting code.  They can be used wherever regular tuples are used, and
 they add the ability to access fields by name instead of position index.
 
-.. function:: namedtuple(typename, field_names, *, verbose=False, rename=False, module=None)
+.. function:: namedtuple(typename, field_names, *, rename=False, module=None)
 
     Returns a new tuple subclass named *typename*.  The new subclass is used to
     create tuple-like objects that have fields accessible by attribute lookup as
@@ -786,10 +786,6 @@ they add the ability to access fields by name instead of position index.
     converted to ``['abc', '_1', 'ghi', '_3']``, eliminating the keyword
     ``def`` and the duplicate fieldname ``abc``.
 
-    If *verbose* is true, the class definition is printed after it is
-    built.  This option is outdated; instead, it is simpler to print the
-    :attr:`_source` attribute.
-
     If *module* is defined, the ``__module__`` attribute of the named tuple is
     set to that value.
 
@@ -806,6 +802,9 @@ they add the ability to access fields by name instead of position index.
     .. versionchanged:: 3.6
        Added the *module* parameter.
 
+    .. versionchanged:: 3.7
+       Remove the *verbose* parameter and the :attr:`_source` attribute.
+
 .. doctest::
     :options: +NORMALIZE_WHITESPACE
 
@@ -878,15 +877,6 @@ field names, the method and attribute names start with an underscore.
         >>> for partnum, record in inventory.items():
         ...     inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())
 
-.. attribute:: somenamedtuple._source
-
-    A string with the pure Python source code used to create the named
-    tuple class.  The source makes the named tuple self-documenting.
-    It can be printed, executed using :func:`exec`, or saved to a file
-    and imported.
-
-    .. versionadded:: 3.3
-
 .. attribute:: somenamedtuple._fields
 
     Tuple of strings listing the field names.  Useful for introspection

Doc/library/concurrency.rst

@@ -26,6 +26,6 @@ The following are support modules for some of the above services:
 
 .. toctree::
 
-   dummy_threading.rst
    _thread.rst
    _dummy_thread.rst
+   dummy_threading.rst

Doc/library/concurrent.futures.rst

@@ -124,11 +124,17 @@ And::
    executor.submit(wait_on_future)
 
 
-.. class:: ThreadPoolExecutor(max_workers=None, thread_name_prefix='')
+.. class:: ThreadPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())
 
    An :class:`Executor` subclass that uses a pool of at most *max_workers*
    threads to execute calls asynchronously.
 
+   *initializer* is an optional callable that is called at the start of
+   each worker thread; *initargs* is a tuple of arguments passed to the
+   initializer.  Should *initializer* raise an exception, all currently
+   pending jobs will raise a :exc:`~concurrent.futures.thread.BrokenThreadPool`,
+   as well any attempt to submit more jobs to the pool.
+
    .. versionchanged:: 3.5
       If *max_workers* is ``None`` or
       not given, it will default to the number of processors on the machine,
@@ -142,6 +148,10 @@ And::
       control the threading.Thread names for worker threads created by
       the pool for easier debugging.
 
+   .. versionchanged:: 3.7
+      Added the *initializer* and *initargs* arguments.
+
+
 .. _threadpoolexecutor-example:
 
 ThreadPoolExecutor Example
@@ -191,13 +201,22 @@ that :class:`ProcessPoolExecutor` will not work in the interactive interpreter.
 Calling :class:`Executor` or :class:`Future` methods from a callable submitted
 to a :class:`ProcessPoolExecutor` will result in deadlock.
 
-.. class:: ProcessPoolExecutor(max_workers=None)
+.. class:: ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=())
 
    An :class:`Executor` subclass that executes calls asynchronously using a pool
    of at most *max_workers* processes.  If *max_workers* is ``None`` or not
    given, it will default to the number of processors on the machine.
    If *max_workers* is lower or equal to ``0``, then a :exc:`ValueError`
    will be raised.
+   *mp_context* can be a multiprocessing context or None. It will be used to
+   launch the workers. If *mp_context* is ``None`` or not given, the default
+   multiprocessing context is used.
+
+   *initializer* is an optional callable that is called at the start of
+   each worker process; *initargs* is a tuple of arguments passed to the
+   initializer.  Should *initializer* raise an exception, all currently
+   pending jobs will raise a :exc:`~concurrent.futures.thread.BrokenThreadPool`,
+   as well any attempt to submit more jobs to the pool.
 
    .. versionchanged:: 3.3
       When one of the worker processes terminates abruptly, a
@@ -205,6 +224,12 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
       was undefined but operations on the executor or its futures would often
       freeze or deadlock.
 
+   .. versionchanged:: 3.7
+      The *mp_context* argument was added to allow users to control the
+      start_method for worker processes created by the pool.
+
+      Added the *initializer* and *initargs* arguments.
+
 
 .. _processpoolexecutor-example:
 
@@ -425,13 +450,31 @@ Exception classes
 
    Raised when a future operation exceeds the given timeout.
 
+.. exception:: BrokenExecutor
+
+   Derived from :exc:`RuntimeError`, this exception class is raised
+   when an executor is broken for some reason, and cannot be used
+   to submit or execute new tasks.
+
+   .. versionadded:: 3.7
+
+.. currentmodule:: concurrent.futures.thread
+
+.. exception:: BrokenThreadPool
+
+   Derived from :exc:`~concurrent.futures.BrokenExecutor`, this exception
+   class is raised when one of the workers of a :class:`ThreadPoolExecutor`
+   has failed initializing.
+
+   .. versionadded:: 3.7
+
 .. currentmodule:: concurrent.futures.process
 
 .. exception:: BrokenProcessPool
 
-   Derived from :exc:`RuntimeError`, this exception class is raised when
+   Derived from :exc:`~concurrent.futures.BrokenExecutor` (formerly
-   one of the workers of a :class:`ProcessPoolExecutor` has terminated
+   :exc:`RuntimeError`), this exception class is raised when one of the
-   in a non-clean fashion (for example, if it was killed from the outside).
+   workers of a :class:`ProcessPoolExecutor` has terminated in a non-clean
+   fashion (for example, if it was killed from the outside).
 
    .. versionadded:: 3.3
-

Doc/library/configparser.rst

@@ -944,6 +944,11 @@ ConfigParser Objects
    .. versionchanged:: 3.5
       The *converters* argument was added.
 
+   .. versionchanged:: 3.7
+      The *defaults* argument is read with :meth:`read_dict()`,
+      providing consistent behavior across the parser: non-string
+      keys and values are implicitly converted to strings.
+
 
    .. method:: defaults()
 
@@ -990,7 +995,8 @@ ConfigParser Objects
       Attempt to read and parse a list of filenames, returning a list of
       filenames which were successfully parsed.
 
-      If *filenames* is a string or :term:`path-like object`, it is treated as
+      If *filenames* is a string, a :class:`bytes` object or a
+      :term:`path-like object`, it is treated as
       a single filename.  If a file named in *filenames* cannot be opened, that
       file will be ignored.  This is designed so that you can specify a list of
       potential configuration file locations (for example, the current
@@ -1017,6 +1023,9 @@ ConfigParser Objects
       .. versionadded:: 3.6.1
          The *filenames* parameter accepts a :term:`path-like object`.
 
+      .. versionadded:: 3.7
+         The *filenames* parameter accepts a :class:`bytes` object.
+
 
    .. method:: read_file(f, source=None)
 
@@ -1208,8 +1217,10 @@ RawConfigParser Objects
                            default_section=configparser.DEFAULTSECT[, \
                            interpolation])
 
-   Legacy variant of the :class:`ConfigParser` with interpolation disabled
+   Legacy variant of the :class:`ConfigParser`.  It has interpolation
-   by default and unsafe ``add_section`` and ``set`` methods.
+   disabled by default and allows for non-string section names, option
+   names, and values via its unsafe ``add_section`` and ``set`` methods,
+   as well as the legacy ``defaults=`` keyword argument handling.
 
    .. note::
       Consider using :class:`ConfigParser` instead which checks types of
@@ -1325,4 +1336,3 @@ Exceptions
 .. [1] Config parsers allow for heavy customization.  If you are interested in
        changing the behaviour outlined by the footnote reference, consult the
        `Customizing Parser Behaviour`_ section.
-

Doc/library/crypt.rst

@@ -41,17 +41,24 @@ are available on all platforms):
 .. data:: METHOD_SHA512
 
    A Modular Crypt Format method with 16 character salt and 86 character
-   hash.  This is the strongest method.
+   hash based on the SHA-512 hash function.  This is the strongest method.
 
 .. data:: METHOD_SHA256
 
    Another Modular Crypt Format method with 16 character salt and 43
-   character hash.
+   character hash based on the SHA-256 hash function.
+
+.. data:: METHOD_BLOWFISH
+
+   Another Modular Crypt Format method with 22 character salt and 31
+   character hash based on the Blowfish cipher.
+
+   .. versionadded:: 3.7
 
 .. data:: METHOD_MD5
 
    Another Modular Crypt Format method with 8 character salt and 22
-   character hash.
+   character hash based on the MD5 hash function.
 
 .. data:: METHOD_CRYPT
 
@@ -109,19 +116,29 @@ The :mod:`crypt` module defines the following functions:
       Accept ``crypt.METHOD_*`` values in addition to strings for *salt*.
 
 
-.. function:: mksalt(method=None)
+.. function:: mksalt(method=None, *, rounds=None)
 
    Return a randomly generated salt of the specified method.  If no
    *method* is given, the strongest method available as returned by
    :func:`methods` is used.
 
-   The return value is a string either of 2 characters in length for
+   The return value is a string suitable for passing as the *salt* argument
-   ``crypt.METHOD_CRYPT``, or 19 characters starting with ``$digit$`` and
+   to :func:`crypt`.
-   16 random characters from the set ``[./a-zA-Z0-9]``, suitable for
+
-   passing as the *salt* argument to :func:`crypt`.
+   *rounds* specifies the number of rounds for ``METHOD_SHA256``,
+   ``METHOD_SHA512`` and ``METHOD_BLOWFISH``.
+   For ``METHOD_SHA256`` and ``METHOD_SHA512`` it must be an integer between
+   ``1000`` and ``999_999_999``, the default is ``5000``.  For
+   ``METHOD_BLOWFISH`` it must be a power of two between ``16`` (2\ :sup:`4`)
+   and ``2_147_483_648`` (2\ :sup:`31`), the default is ``4096``
+   (2\ :sup:`12`).
 
    .. versionadded:: 3.3
 
+   .. versionchanged:: 3.7
+      Added the *rounds* parameter.
+
+
 Examples
 --------
 

Doc/library/csv.rst

@@ -172,7 +172,7 @@ The :mod:`csv` module defines the following classes:
    A short usage example::
 
        >>> import csv
-       >>> with open('names.csv') as csvfile:
+       >>> with open('names.csv', newline='') as csvfile:
        ...     reader = csv.DictReader(csvfile)
        ...     for row in reader:
        ...         print(row['first_name'], row['last_name'])
@@ -211,7 +211,7 @@ The :mod:`csv` module defines the following classes:
 
        import csv
 
-       with open('names.csv', 'w') as csvfile:
+       with open('names.csv', 'w', newline='') as csvfile:
            fieldnames = ['first_name', 'last_name']
            writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
 
@@ -270,7 +270,7 @@ The :mod:`csv` module defines the following classes:
 
 An example for :class:`Sniffer` use::
 
-   with open('example.csv') as csvfile:
+   with open('example.csv', newline='') as csvfile:
        dialect = csv.Sniffer().sniff(csvfile.read(1024))
        csvfile.seek(0)
        reader = csv.reader(csvfile, dialect)

Doc/library/curses.ascii.rst

@@ -176,14 +176,12 @@ C library:
 
    Checks for a non-ASCII character (ordinal values 0x80 and above).
 
-These functions accept either integers or strings; when the argument is a
+These functions accept either integers or single-character strings; when the argument is a
 string, it is first converted using the built-in function :func:`ord`.
 
-Note that all these functions check ordinal bit values derived from the  first
+Note that all these functions check ordinal bit values derived from the
 character of the string you pass in; they do not actually know anything about
-the host machine's character encoding.  For functions  that know about the
+the host machine's character encoding.
-character encoding (and handle internationalization properly) see the
-:mod:`string` module.
 
 The following two functions take either a single-character string or integer
 byte value; they return a value of the same type.

Doc/library/curses.panel.rst

@@ -74,7 +74,7 @@ Panel objects have the following methods:
 
 .. method:: Panel.hidden()
 
-   Returns true if the panel is hidden (not visible), false otherwise.
+   Returns ``True`` if the panel is hidden (not visible), ``False`` otherwise.
 
 
 .. method:: Panel.hide()

Doc/library/curses.rst

@@ -19,6 +19,14 @@ for Windows, DOS, and possibly other systems as well.  This extension module is
 designed to match the API of ncurses, an open-source curses library hosted on
 Linux and the BSD variants of Unix.
 
+.. note::
+
+   Whenever the documentation mentions a *character* it can be specified
+   as an integer, a one-character Unicode string or a one-byte byte string.
+
+   Whenever the documentation mentions a *character string* it can be specified
+   as a Unicode string or a byte string.
+
 .. note::
 
    Since version 5.4, the ncurses library decides how to interpret non-ASCII data
@@ -104,8 +112,8 @@ The module :mod:`curses` defines the following functions:
 .. function:: color_content(color_number)
 
    Return the intensity of the red, green, and blue (RGB) components in the color
-   *color_number*, which must be between ``0`` and :const:`COLORS`.  A 3-tuple is
+   *color_number*, which must be between ``0`` and :const:`COLORS`.  Return a 3-tuple,
-   returned, containing the R,G,B values for the given color, which will be between
+   containing the R,G,B values for the given color, which will be between
    ``0`` (no component) and ``1000`` (maximum amount of component).
 
 
@@ -119,9 +127,9 @@ The module :mod:`curses` defines the following functions:
 
 .. function:: curs_set(visibility)
 
-   Set the cursor state.  *visibility* can be set to 0, 1, or 2, for invisible,
+   Set the cursor state.  *visibility* can be set to ``0``, ``1``, or ``2``, for invisible,
-   normal, or very visible.  If the terminal supports the visibility requested, the
+   normal, or very visible.  If the terminal supports the visibility requested, return the
-   previous cursor state is returned; otherwise, an exception is raised.  On many
+   previous cursor state; otherwise raise an exception.  On many
    terminals, the "visible" mode is an underline cursor and the "very visible" mode
    is a block cursor.
 
@@ -154,12 +162,12 @@ The module :mod:`curses` defines the following functions:
    representing the desired next state.  The :func:`doupdate` ground updates the
    physical screen to match the virtual screen.
 
-   The virtual screen may be updated by a :meth:`noutrefresh` call after write
+   The virtual screen may be updated by a :meth:`~window.noutrefresh` call after write
-   operations such as :meth:`addstr` have been performed on a window.  The normal
+   operations such as :meth:`~window.addstr` have been performed on a window.  The normal
-   :meth:`refresh` call is simply :meth:`noutrefresh` followed by :func:`doupdate`;
+   :meth:`~window.refresh` call is simply :meth:`!noutrefresh` followed by :func:`!doupdate`;
    if you have to update multiple windows, you can speed performance and perhaps
-   reduce screen flicker by issuing :meth:`noutrefresh` calls on all windows,
+   reduce screen flicker by issuing :meth:`!noutrefresh` calls on all windows,
-   followed by a single :func:`doupdate`.
+   followed by a single :func:`!doupdate`.
 
 
 .. function:: echo()
@@ -175,7 +183,7 @@ The module :mod:`curses` defines the following functions:
 
 .. function:: erasechar()
 
-   Return the user's current erase character.  Under Unix operating systems this
+   Return the user's current erase character as a one-byte bytes object.  Under Unix operating systems this
    is a property of the controlling tty of the curses program, and is not set by
    the curses library itself.
 
@@ -183,9 +191,9 @@ The module :mod:`curses` defines the following functions:
 .. function:: filter()
 
    The :func:`.filter` routine, if used, must be called before :func:`initscr` is
-   called.  The effect is that, during those calls, :envvar:`LINES` is set to 1; the
+   called.  The effect is that, during those calls, :envvar:`LINES` is set to ``1``; the
-   capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home
+   capabilities ``clear``, ``cup``, ``cud``, ``cud1``, ``cuu1``, ``cuu``, ``vpa`` are disabled; and the ``home``
-   string is set to the value of cr. The effect is that the cursor is confined to
+   string is set to the value of ``cr``. The effect is that the cursor is confined to
    the current line, and so are screen updates.  This may be used for enabling
    character-at-a-time  line editing without touching the rest of the screen.
 
@@ -205,7 +213,7 @@ The module :mod:`curses` defines the following functions:
 
 .. function:: getmouse()
 
-   After :meth:`getch` returns :const:`KEY_MOUSE` to signal a mouse event, this
+   After :meth:`~window.getch` returns :const:`KEY_MOUSE` to signal a mouse event, this
    method should be call to retrieve the queued mouse event, represented as a
    5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used to distinguish
    multiple devices, and *x*, *y*, *z* are the event's coordinates.  (*z* is
@@ -219,8 +227,8 @@ The module :mod:`curses` defines the following functions:
 
 .. function:: getsyx()
 
-   Return the current coordinates of the virtual screen cursor in y and x.  If
+   Return the current coordinates of the virtual screen cursor as a tuple
-   leaveok is currently true, then -1,-1 is returned.
+   ``(y, x)``.  If :meth:`leaveok <window.leaveok>` is currently ``True``, then return ``(-1, -1)``.
 
 
 .. function:: getwin(file)
@@ -260,7 +268,7 @@ The module :mod:`curses` defines the following functions:
 
    Used for half-delay mode, which is similar to cbreak mode in that characters
    typed by the user are immediately available to the program. However, after
-   blocking for *tenths* tenths of seconds, an exception is raised if nothing has
+   blocking for *tenths* tenths of seconds, raise an exception if nothing has
    been typed.  The value of *tenths* must be a number between ``1`` and ``255``.  Use
    :func:`nocbreak` to leave half-delay mode.
 
@@ -273,7 +281,7 @@ The module :mod:`curses` defines the following functions:
    :const:`COLORS`.  Each of *r*, *g*, *b*, must be a value between ``0`` and
    ``1000``.  When :func:`init_color` is used, all occurrences of that color on the
    screen immediately change to the new definition.  This function is a no-op on
-   most terminals; it is active only if :func:`can_change_color` returns ``1``.
+   most terminals; it is active only if :func:`can_change_color` returns ``True``.
 
 
 .. function:: init_pair(pair_number, fg, bg)
@@ -313,32 +321,32 @@ The module :mod:`curses` defines the following functions:
 
 .. function:: keyname(k)
 
-   Return the name of the key numbered *k*.  The name of a key generating printable
+   Return the name of the key numbered *k* as a bytes object.  The name of a key generating printable
    ASCII character is the key's character.  The name of a control-key combination
-   is a two-character string consisting of a caret followed by the corresponding
+   is a two-byte bytes object consisting of a caret (``b'^'``) followed by the corresponding
    printable ASCII character.  The name of an alt-key combination (128--255) is a
-   string consisting of the prefix 'M-' followed by the name of the corresponding
+   bytes object consisting of the prefix ``b'M-'`` followed by the name of the corresponding
    ASCII character.
 
 
 .. function:: killchar()
 
-   Return the user's current line kill character. Under Unix operating systems
+   Return the user's current line kill character as a one-byte bytes object. Under Unix operating systems
    this is a property of the controlling tty of the curses program, and is not set
    by the curses library itself.
 
 
 .. function:: longname()
 
-   Return a string containing the terminfo long name field describing the current
+   Return a bytes object containing the terminfo long name field describing the current
    terminal.  The maximum length of a verbose description is 128 characters.  It is
    defined only after the call to :func:`initscr`.
 
 
-.. function:: meta(yes)
+.. function:: meta(flag)
 
-   If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0,  allow only
+   If *flag* is ``True``, allow 8-bit characters to be input.  If
-   7-bit chars.
+   *flag* is ``False``,  allow only 7-bit chars.
 
 
 .. function:: mouseinterval(interval)
@@ -352,7 +360,7 @@ The module :mod:`curses` defines the following functions:
 
    Set the mouse events to be reported, and return a tuple ``(availmask,
    oldmask)``.   *availmask* indicates which of the specified mouse events can be
-   reported; on complete failure it returns 0.  *oldmask* is the previous value of
+   reported; on complete failure it returns ``0``.  *oldmask* is the previous value of
    the given window's mouse event mask.  If this function is never called, no mouse
    events are ever reported.
 
@@ -365,13 +373,13 @@ The module :mod:`curses` defines the following functions:
 .. function:: newpad(nlines, ncols)
 
    Create and return a pointer to a new pad data structure with the given number
-   of lines and columns.  A pad is returned as a window object.
+   of lines and columns.  Return a pad as a window object.
 
    A pad is like a window, except that it is not restricted by the screen size, and
    is not necessarily associated with a particular part of the screen.  Pads can be
    used when a large window is needed, and only a part of the window will be on the
    screen at one time.  Automatic refreshes of pads (such as from scrolling or
-   echoing of input) do not occur.  The :meth:`refresh` and :meth:`noutrefresh`
+   echoing of input) do not occur.  The :meth:`~window.refresh` and :meth:`~window.noutrefresh`
    methods of a pad require 6 arguments to specify the part of the pad to be
    displayed and the location on the screen to be used for the display. The
    arguments are *pminrow*, *pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol*; the *p*
@@ -419,9 +427,9 @@ The module :mod:`curses` defines the following functions:
 
 .. function:: noqiflush()
 
-   When the :func:`noqiflush` routine is used, normal flush of input and output queues
+   When the :func:`!noqiflush` routine is used, normal flush of input and output queues
-   associated with the INTR, QUIT and SUSP characters will not be done.  You may
+   associated with the ``INTR``, ``QUIT`` and ``SUSP`` characters will not be done.  You may
-   want to call :func:`noqiflush` in a signal handler if you want output to
+   want to call :func:`!noqiflush` in a signal handler if you want output to
    continue as though the interrupt had not occurred, after the handler exits.
 
 
@@ -442,14 +450,14 @@ The module :mod:`curses` defines the following functions:
    :func:`color_pair` is the counterpart to this function.
 
 
-.. function:: putp(string)
+.. function:: putp(str)
 
    Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified
    terminfo capability for the current terminal.  Note that the output of :func:`putp`
    always goes to standard output.
 
 
-.. function:: qiflush( [flag] )
+.. function:: qiflush([flag])
 
    If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. If
    *flag* is ``True``, or no argument is provided, the queues will be flushed when
@@ -486,7 +494,7 @@ The module :mod:`curses` defines the following functions:
    Backend function used by :func:`resizeterm`, performing most of the work;
    when resizing the windows, :func:`resize_term` blank-fills the areas that are
    extended.  The calling application should fill in these areas with
-   appropriate data.  The :func:`resize_term` function attempts to resize all
+   appropriate data.  The :func:`!resize_term` function attempts to resize all
    windows.  However, due to the calling convention of pads, it is not possible
    to resize these without additional interaction with the application.
 
@@ -506,16 +514,17 @@ The module :mod:`curses` defines the following functions:
 
 .. function:: setsyx(y, x)
 
-   Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then
+   Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both ``-1``, then
-   leaveok is set.
+   :meth:`leaveok <window.leaveok>` is set ``True``.
 
 
-.. function:: setupterm([termstr, fd])
+.. function:: setupterm(term=None, fd=-1)
 
-   Initialize the terminal.  *termstr* is a string giving the terminal name; if
+   Initialize the terminal.  *term* is a string giving
-   omitted, the value of the :envvar:`TERM` environment variable will be used.  *fd* is the
+   the terminal name, or ``None``; if omitted or ``None``, the value of the
+   :envvar:`TERM` environment variable will be used.  *fd* is the
    file descriptor to which any initialization sequences will be sent; if not
-   supplied, the file descriptor for ``sys.stdout`` will be used.
+   supplied or ``-1``, the file descriptor for ``sys.stdout`` will be used.
 
 
 .. function:: start_color()
@@ -540,13 +549,14 @@ The module :mod:`curses` defines the following functions:
 
 .. function:: termname()
 
-   Return the value of the environment variable :envvar:`TERM`, truncated to 14 characters.
+   Return the value of the environment variable :envvar:`TERM`, as a bytes object,
+   truncated to 14 characters.
 
 
 .. function:: tigetflag(capname)
 
    Return the value of the Boolean capability corresponding to the terminfo
-   capability name *capname*.  The value ``-1`` is returned if *capname* is not a
+   capability name *capname* as an integer.  Return the value ``-1`` if *capname* is not a
    Boolean capability, or ``0`` if it is canceled or absent from the terminal
    description.
 
@@ -554,7 +564,7 @@ The module :mod:`curses` defines the following functions:
 .. function:: tigetnum(capname)
 
    Return the value of the numeric capability corresponding to the terminfo
-   capability name *capname*.  The value ``-2`` is returned if *capname* is not a
+   capability name *capname* as an integer.  Return the value ``-2`` if *capname* is not a
    numeric capability, or ``-1`` if it is canceled or absent from the terminal
    description.
 
@@ -562,13 +572,14 @@ The module :mod:`curses` defines the following functions:
 .. function:: tigetstr(capname)
 
    Return the value of the string capability corresponding to the terminfo
-   capability name *capname*.  ``None`` is returned if *capname* is not a string
+   capability name *capname* as a bytes object.  Return ``None`` if *capname*
-   capability, or is canceled or absent from the terminal description.
+   is not a terminfo "string capability", or is canceled or absent from the
+   terminal description.
 
 
 .. function:: tparm(str[, ...])
 
-   Instantiate the string *str* with the supplied parameters, where *str* should
+   Instantiate the bytes object *str* with the supplied parameters, where *str* should
    be a parameterized string obtained from the terminfo database.  E.g.
    ``tparm(tigetstr("cup"), 5, 3)`` could result in ``b'\033[6;4H'``, the exact
    result depending on terminal type.
@@ -588,18 +599,18 @@ The module :mod:`curses` defines the following functions:
 
 .. function:: unctrl(ch)
 
-   Return a string which is a printable representation of the character *ch*.
+   Return a bytes object which is a printable representation of the character *ch*.
-   Control characters are displayed as a caret followed by the character, for
+   Control characters are represented as a caret followed by the character, for
-   example as ``^C``. Printing characters are left as they are.
+   example as ``b'^C'``. Printing characters are left as they are.
 
 
 .. function:: ungetch(ch)
 
-   Push *ch* so the next :meth:`getch` will return it.
+   Push *ch* so the next :meth:`~window.getch` will return it.
 
    .. note::
 
-      Only one *ch* can be pushed before :meth:`getch` is called.
+      Only one *ch* can be pushed before :meth:`!getch` is called.
 
 
 .. function:: update_lines_cols()
@@ -611,11 +622,11 @@ The module :mod:`curses` defines the following functions:
 
 .. function:: unget_wch(ch)
 
-   Push *ch* so the next :meth:`get_wch` will return it.
+   Push *ch* so the next :meth:`~window.get_wch` will return it.
 
    .. note::
 
-      Only one *ch* can be pushed before :meth:`get_wch` is called.
+      Only one *ch* can be pushed before :meth:`!get_wch` is called.
 
    .. versionadded:: 3.3
 
@@ -640,7 +651,7 @@ The module :mod:`curses` defines the following functions:
 
    Allow use of default values for colors on terminals supporting this feature. Use
    this to support transparency in your application.  The default color is assigned
-   to the color number -1. After calling this function,  ``init_pair(x,
+   to the color number ``-1``. After calling this function,  ``init_pair(x,
    curses.COLOR_RED, -1)`` initializes, for instance, color pair *x* to a red
    foreground color on the default background.
 
@@ -652,7 +663,7 @@ The module :mod:`curses` defines the following functions:
    this function will restore the terminal to a sane state before re-raising the
    exception and generating a traceback.  The callable object *func* is then passed
    the main window 'stdscr' as its first argument, followed by any other arguments
-   passed to :func:`wrapper`.  Before calling *func*, :func:`wrapper` turns on
+   passed to :func:`!wrapper`.  Before calling *func*, :func:`!wrapper` turns on
    cbreak mode, turns off echo, enables the terminal keypad, and initializes colors
    if the terminal has color support.  On exit (whether normally or by exception)
    it restores cooked mode, turns on echo, and disables the terminal keypad.
@@ -670,13 +681,6 @@ the following methods and attributes:
 .. method:: window.addch(ch[, attr])
             window.addch(y, x, ch[, attr])
 
-   .. note::
-
-      A *character* means a C character (an ASCII code), rather than a Python
-      character (a string of length 1). (This note is true whenever the
-      documentation mentions a character.) The built-in :func:`ord` is handy for
-      conveying strings to codes.
-
    Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any
    character previously painter at that location.  By default, the character
    position and attributes are the current settings for the window object.
@@ -685,15 +689,16 @@ the following methods and attributes:
 .. method:: window.addnstr(str, n[, attr])
             window.addnstr(y, x, str, n[, attr])
 
-   Paint at most *n* characters of the  string *str* at ``(y, x)`` with attributes
+   Paint at most *n* characters of the character string *str* at
+   ``(y, x)`` with attributes
    *attr*, overwriting anything previously on the display.
 
 
 .. method:: window.addstr(str[, attr])
             window.addstr(y, x, str[, attr])
 
-   Paint the string *str* at ``(y, x)`` with attributes *attr*, overwriting
+   Paint the character string *str* at ``(y, x)`` with attributes
-   anything previously on the display.
+   *attr*, overwriting anything previously on the display.
 
 
 .. method:: window.attroff(attr)
@@ -710,8 +715,8 @@ the following methods and attributes:
 
 .. method:: window.attrset(attr)
 
-   Set the "background" set of attributes to *attr*.  This set is initially 0 (no
+   Set the "background" set of attributes to *attr*.  This set is initially
-   attributes).
+   ``0`` (no attributes).
 
 
 .. method:: window.bkgd(ch[, attr])
@@ -741,8 +746,7 @@ the following methods and attributes:
 
    Draw a border around the edges of the window. Each parameter specifies  the
    character to use for a specific part of the border; see the table below for more
-   details.  The characters can be specified as integers or as one-character
+   details.
-   strings.
 
    .. note::
 
@@ -783,11 +787,11 @@ the following methods and attributes:
             window.chgat(y, x, num, attr)
 
    Set the attributes of *num* characters at the current cursor position, or at
-   position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,
+   position ``(y, x)`` if supplied. If *num* is not given or is ``-1``,
    the attribute will be set on all the characters to the end of the line.  This
-   function does not move the cursor. The changed line will be touched using the
+   function moves cursor to position ``(y, x)`` if supplied. The changed line
-   :meth:`touchline` method so that the contents will be redisplayed by the next
+   will be touched using the :meth:`touchline` method so that the contents will
-   window refresh.
+   be redisplayed by the next window refresh.
 
 
 .. method:: window.clear()
@@ -796,9 +800,9 @@ the following methods and attributes:
    call to :meth:`refresh`.
 
 
-.. method:: window.clearok(yes)
+.. method:: window.clearok(flag)
 
-   If *yes* is 1, the next call to :meth:`refresh` will clear the window
+   If *flag* is ``True``, the next call to :meth:`refresh` will clear the window
    completely.
 
 
@@ -880,15 +884,16 @@ the following methods and attributes:
 .. method:: window.getch([y, x])
 
    Get a character. Note that the integer returned does *not* have to be in ASCII
-   range: function keys, keypad keys and so on return numbers higher than 256. In
+   range: function keys, keypad keys and so on are represented by numbers higher
-   no-delay mode, -1 is returned if there is no input, else :func:`getch` waits
+   than 255.  In no-delay mode, return ``-1`` if there is no input, otherwise
-   until a key is pressed.
+   wait until a key is pressed.
 
 
 .. method:: window.get_wch([y, x])
 
    Get a wide character. Return a character for most keys, or an integer for
    function keys, keypad keys, and other special keys.
+   In no-delay mode, raise an exception if there is no input.
 
    .. versionadded:: 3.3
 
@@ -897,7 +902,7 @@ the following methods and attributes:
 
    Get a character, returning a string instead of an integer, as :meth:`getch`
    does. Function keys, keypad keys and other special keys return a multibyte
-   string containing the key name.  In no-delay mode, an exception is raised if
+   string containing the key name.  In no-delay mode, raise an exception if
    there is no input.
 
 
@@ -909,13 +914,16 @@ the following methods and attributes:
 .. method:: window.getparyx()
 
    Return the beginning coordinates of this window relative to its parent window
-   into two integer variables y and x.  Return ``-1, -1`` if this window has no
+   as a tuple ``(y, x)``.  Return ``(-1, -1)`` if this window has no
    parent.
 
 
-.. method:: window.getstr([y, x])
+.. method:: window.getstr()
+            window.getstr(n)
+            window.getstr(y, x)
+            window.getstr(y, x, n)
 
-   Read a string from the user, with primitive line editing capacity.
+   Read a bytes object from the user, with primitive line editing capacity.
 
 
 .. method:: window.getyx()
@@ -939,9 +947,9 @@ the following methods and attributes:
    insert/delete is enabled by default.
 
 
-.. method:: window.idlok(yes)
+.. method:: window.idlok(flag)
 
-   If called with *yes* equal to 1, :mod:`curses` will try and use hardware line
+   If *flag* is ``True``, :mod:`curses` will try and use hardware line
    editing facilities. Otherwise, line insertion/deletion are disabled.
 
 
@@ -1003,7 +1011,7 @@ the following methods and attributes:
 .. method:: window.instr([n])
             window.instr(y, x[, n])
 
-   Return a string of characters, extracted from the window starting at the
+   Return a bytes object of characters, extracted from the window starting at the
    current cursor position, or at *y*, *x* if specified. Attributes are stripped
    from the characters.  If *n* is specified, :meth:`instr` returns a string
    at most *n* characters long (exclusive of the trailing NUL).
@@ -1022,20 +1030,20 @@ the following methods and attributes:
    :meth:`refresh`; otherwise return ``False``.
 
 
-.. method:: window.keypad(yes)
+.. method:: window.keypad(flag)
 
-   If *yes* is 1, escape sequences generated by some keys (keypad,  function keys)
+   If *flag* is ``True``, escape sequences generated by some keys (keypad,  function keys)
-   will be interpreted by :mod:`curses`. If *yes* is 0, escape sequences will be
+   will be interpreted by :mod:`curses`. If *flag* is ``False``, escape sequences will be
    left as is in the input stream.
 
 
-.. method:: window.leaveok(yes)
+.. method:: window.leaveok(flag)
 
-   If *yes* is 1, cursor is left where it is on update, instead of being at "cursor
+   If *flag* is ``True``, cursor is left where it is on update, instead of being at "cursor
    position."  This reduces cursor movement where possible. If possible the cursor
    will be made invisible.
 
-   If *yes* is 0, cursor will always be at "cursor position" after an update.
+   If *flag* is ``False``, cursor will always be at "cursor position" after an update.
 
 
 .. method:: window.move(new_y, new_x)
@@ -1055,16 +1063,16 @@ the following methods and attributes:
    Move the window so its upper-left corner is at ``(new_y, new_x)``.
 
 
-.. method:: window.nodelay(yes)
+.. method:: window.nodelay(flag)
 
-   If *yes* is ``1``, :meth:`getch` will be non-blocking.
+   If *flag* is ``True``, :meth:`getch` will be non-blocking.
 
 
-.. method:: window.notimeout(yes)
+.. method:: window.notimeout(flag)
 
-   If *yes* is ``1``, escape sequences will not be timed out.
+   If *flag* is ``True``, escape sequences will not be timed out.
 
-   If *yes* is ``0``, after a few milliseconds, an escape sequence will not be
+   If *flag* is ``False``, after a few milliseconds, an escape sequence will not be
    interpreted, and will be left in the input stream as is.
 
 
@@ -1153,8 +1161,8 @@ the following methods and attributes:
 
    Control what happens when the cursor of a window is moved off the edge of the
    window or scrolling region, either as a result of a newline action on the bottom
-   line, or typing the last character of the last line.  If *flag* is false, the
+   line, or typing the last character of the last line.  If *flag* is ``False``, the
-   cursor is left on the bottom line.  If *flag* is true, the window is scrolled up
+   cursor is left on the bottom line.  If *flag* is ``True``, the window is scrolled up
    one line.  Note that in order to get the physical scrolling effect on the
    terminal, it is also necessary to call :meth:`idlok`.
 
@@ -1202,7 +1210,7 @@ the following methods and attributes:
 
 .. method:: window.syncok(flag)
 
-   If called with *flag* set to ``True``, then :meth:`syncup` is called automatically
+   If *flag* is ``True``, then :meth:`syncup` is called automatically
    whenever there is a change in the window.
 
 
@@ -1216,9 +1224,9 @@ the following methods and attributes:
 
    Set blocking or non-blocking read behavior for the window.  If *delay* is
    negative, blocking read is used (which will wait indefinitely for input).  If
-   *delay* is zero, then non-blocking read is used, and -1 will be returned by
+   *delay* is zero, then non-blocking read is used, and :meth:`getch` will
-   :meth:`getch` if no input is waiting.  If *delay* is positive, then
+   return ``-1`` if no input is waiting.  If *delay* is positive, then
-   :meth:`getch` will block for *delay* milliseconds, and return -1 if there is
+   :meth:`getch` will block for *delay* milliseconds, and return ``-1`` if there is
    still no input at the end of that time.
 
 
@@ -1226,7 +1234,7 @@ the following methods and attributes:
 
    Pretend *count* lines have been changed, starting with line *start*.  If
    *changed* is supplied, it specifies whether the affected lines are marked as
-   having been changed (*changed*\ =1) or unchanged (*changed*\ =0).
+   having been changed (*changed*\ ``=True``) or unchanged (*changed*\ ``=False``).
 
 
 .. method:: window.touchwin()
@@ -1268,7 +1276,7 @@ The :mod:`curses` module defines the following data members:
 
 .. data:: version
 
-   A string representing the current version of the module.  Also available as
+   A bytes object representing the current version of the module.  Also available as
    :const:`__version__`.
 
 Some constants are available to specify character cell attributes.

Doc/library/datetime.rst

@@ -287,11 +287,12 @@ Supported operations:
 |                                | ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D  |
 |                                | is negative for negative ``t``. (5)           |
 +--------------------------------+-----------------------------------------------+
-| ``repr(t)``                    | Returns a string in the form                  |
+| ``repr(t)``                    | Returns a string representation of the        |
-|                                | ``datetime.timedelta(D[, S[, U]])``, where D  |
+|                                | :class:`timedelta` object as a constructor    |
-|                                | is negative for negative ``t``. (5)           |
+|                                | call with canonical attribute values.         |
 +--------------------------------+-----------------------------------------------+
 
+
 Notes:
 
 (1)
@@ -312,7 +313,7 @@ Notes:
   unusual results for negative timedeltas.  For example:
 
   >>> timedelta(hours=-5)
-  datetime.timedelta(-1, 68400)
+  datetime.timedelta(days=-1, seconds=68400)
   >>> print(_)
   -1 day, 19:00:00
 
@@ -364,13 +365,13 @@ Example usage:
     True
     >>> ten_years = 10 * year
     >>> ten_years, ten_years.days // 365
-    (datetime.timedelta(3650), 10)
+    (datetime.timedelta(days=3650), 10)
     >>> nine_years = ten_years - year
     >>> nine_years, nine_years.days // 365
-    (datetime.timedelta(3285), 9)
+    (datetime.timedelta(days=3285), 9)
     >>> three_years = nine_years // 3
     >>> three_years, three_years.days // 365
-    (datetime.timedelta(1095), 3)
+    (datetime.timedelta(days=1095), 3)
     >>> abs(three_years - ten_years) == 2 * three_years + year
     True
 
@@ -1070,16 +1071,20 @@ Instance methods:
 
    If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
    ``self.tzinfo.utcoffset(self)``, and raises an exception if the latter doesn't
-   return ``None``, or a :class:`timedelta` object representing a whole number of
+   return ``None`` or a :class:`timedelta` object with magnitude less than one day.
-   minutes with magnitude less than one day.
+
+   .. versionchanged:: 3.7
+      The UTC offset is not restricted to a whole number of minutes.
 
 
 .. method:: datetime.dst()
 
    If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
    ``self.tzinfo.dst(self)``, and raises an exception if the latter doesn't return
-   ``None``, or a :class:`timedelta` object representing a whole number of minutes
+   ``None`` or a :class:`timedelta` object with magnitude less than one day.
-   with magnitude less than one day.
+
+   .. versionchanged:: 3.7
+      The DST offset is not restricted to a whole number of minutes.
 
 
 .. method:: datetime.tzname()
@@ -1349,12 +1354,12 @@ Using datetime with tzinfo:
     >>> dt1.dst()
     datetime.timedelta(0)
     >>> dt1.utcoffset()
-    datetime.timedelta(0, 3600)
+    datetime.timedelta(seconds=3600)
     >>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
     >>> dt2.dst()
-    datetime.timedelta(0, 3600)
+    datetime.timedelta(seconds=3600)
     >>> dt2.utcoffset()
-    datetime.timedelta(0, 7200)
+    datetime.timedelta(seconds=7200)
     >>> # Convert datetime to another time zone
     >>> dt3 = dt2.astimezone(GMT2())
     >>> dt3     # doctest: +ELLIPSIS
@@ -1561,17 +1566,20 @@ Instance methods:
 
    If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
    ``self.tzinfo.utcoffset(None)``, and raises an exception if the latter doesn't
-   return ``None`` or a :class:`timedelta` object representing a whole number of
+   return ``None`` or a :class:`timedelta` object with magnitude less than one day.
-   minutes with magnitude less than one day.
+
+   .. versionchanged:: 3.7
+      The UTC offset is not restricted to a whole number of minutes.
 
 
 .. method:: time.dst()
 
    If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
    ``self.tzinfo.dst(None)``, and raises an exception if the latter doesn't return
-   ``None``, or a :class:`timedelta` object representing a whole number of minutes
+   ``None``, or a :class:`timedelta` object with magnitude less than one day.
-   with magnitude less than one day.
 
+   .. versionchanged:: 3.7
+      The DST offset is not restricted to a whole number of minutes.
 
 .. method:: time.tzname()
 
@@ -1640,13 +1648,14 @@ Example:
 
 .. method:: tzinfo.utcoffset(dt)
 
-   Return offset of local time from UTC, in minutes east of UTC.  If local time is
+   Return offset of local time from UTC, as a :class:`timedelta` object that is
+   positive east of UTC.  If local time is
    west of UTC, this should be negative.  Note that this is intended to be the
    total offset from UTC; for example, if a :class:`tzinfo` object represents both
    time zone and DST adjustments, :meth:`utcoffset` should return their sum.  If
    the UTC offset isn't known, return ``None``.  Else the value returned must be a
-   :class:`timedelta` object specifying a whole number of minutes in the range
+   :class:`timedelta` object strictly between ``-timedelta(hours=24)`` and
-   -1439 to 1439 inclusive (1440 = 24\*60; the magnitude of the offset must be less
+   ``timedelta(hours=24)`` (the magnitude of the offset must be less
    than one day).  Most implementations of :meth:`utcoffset` will probably look
    like one of these two::
 
@@ -1659,10 +1668,14 @@ Example:
    The default implementation of :meth:`utcoffset` raises
    :exc:`NotImplementedError`.
 
+   .. versionchanged:: 3.7
+      The UTC offset is not restricted to a whole number of minutes.
+
 
 .. method:: tzinfo.dst(dt)
 
-   Return the daylight saving time (DST) adjustment, in minutes east of UTC, or
+   Return the daylight saving time (DST) adjustment, as a :class:`timedelta`
+   object or
    ``None`` if DST information isn't known.  Return ``timedelta(0)`` if DST is not
    in effect. If DST is in effect, return the offset as a :class:`timedelta` object
    (see :meth:`utcoffset` for details). Note that DST offset, if applicable, has
@@ -1707,6 +1720,9 @@ Example:
 
    The default implementation of :meth:`dst` raises :exc:`NotImplementedError`.
 
+   .. versionchanged:: 3.7
+      The DST offset is not restricted to a whole number of minutes.
+
 
 .. method:: tzinfo.tzname(dt)
 
@@ -1886,14 +1902,17 @@ made to civil time.
   The *offset* argument must be specified as a :class:`timedelta`
   object representing the difference between the local time and UTC.  It must
   be strictly between ``-timedelta(hours=24)`` and
-  ``timedelta(hours=24)`` and represent a whole number of minutes,
+  ``timedelta(hours=24)``, otherwise :exc:`ValueError` is raised.
-  otherwise :exc:`ValueError` is raised.
 
   The *name* argument is optional.  If specified it must be a string that
   will be used as the value returned by the :meth:`datetime.tzname` method.
 
   .. versionadded:: 3.2
 
+  .. versionchanged:: 3.7
+     The UTC offset is not restricted to a whole number of minutes.
+
+
 .. method:: timezone.utcoffset(dt)
 
   Return the fixed value specified when the :class:`timezone` instance is
@@ -1901,6 +1920,9 @@ made to civil time.
   :class:`timedelta` instance equal to the difference between the
   local time and UTC.
 
+  .. versionchanged:: 3.7
+     The UTC offset is not restricted to a whole number of minutes.
+
 .. method:: timezone.tzname(dt)
 
   Return the fixed value specified when the :class:`timezone` instance
@@ -2024,8 +2046,8 @@ format codes.
 |           | number, zero-padded on the     | 999999                 |       |
 |           | left.                          |                        |       |
 +-----------+--------------------------------+------------------------+-------+
-| ``%z``    | UTC offset in the form +HHMM   | (empty), +0000, -0400, | \(6)  |
+| ``%z``    | UTC offset in the form         | (empty), +0000, -0400, | \(6)  |
-|           | or -HHMM (empty string if the  | +1030                  |       |
+|           | ±HHMM[SS] (empty string if the | +1030                  |       |
 |           | object is naive).              |                        |       |
 +-----------+--------------------------------+------------------------+-------+
 | ``%Z``    | Time zone name (empty string   | (empty), UTC, EST, CST |       |
@@ -2138,12 +2160,26 @@ Notes:
    For an aware object:
 
    ``%z``
-      :meth:`utcoffset` is transformed into a 5-character string of the form
+      :meth:`utcoffset` is transformed into a string of the form
-      +HHMM or -HHMM, where HH is a 2-digit string giving the number of UTC
+      ±HHMM[SS[.uuuuuu]], where HH is a 2-digit string giving the number of UTC
       offset hours, and MM is a 2-digit string giving the number of UTC offset
-      minutes.  For example, if :meth:`utcoffset` returns
+      minutes, SS is a 2-digit string string giving the number of UTC offset
-      ``timedelta(hours=-3, minutes=-30)``, ``%z`` is replaced with the string
+      seconds and uuuuuu is a 2-digit string string giving the number of UTC
-      ``'-0330'``.
+      offset microseconds.  The uuuuuu part is omitted when the offset is a
+      whole number of minutes and both the uuuuuu and the SS parts are omitted
+      when the offset is a whole number of minutes.  For example, if
+      :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
+      replaced with the string ``'-0330'``.
+
+   .. versionchanged:: 3.7
+      The UTC offset is not restricted to a whole number of minutes.
+
+   .. versionchanged:: 3.7
+      When the ``%z`` directive is provided to the  :meth:`strptime` method,
+      the UTC offsets can have a colon as a separator between hours, minutes
+      and seconds.
+      For example, ``'+01:00:00'`` will be parsed as an offset of one hour.
+      In addition, providing ``'Z'`` is identical to ``'+00:00'``.
 
    ``%Z``
       If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty

Doc/library/dis.rst

@@ -53,8 +53,9 @@ code.
 .. class:: Bytecode(x, *, first_line=None, current_offset=None)
 
 
-   Analyse the bytecode corresponding to a function, generator, method, string
+   Analyse the bytecode corresponding to a function, generator, asynchronous
-   of source code, or a code object (as returned by :func:`compile`).
+   generator, coroutine, method, string of source code, or a code object (as
+   returned by :func:`compile`).
 
    This is a convenience wrapper around many of the functions listed below, most
    notably :func:`get_instructions`, as iterating over a :class:`Bytecode`
@@ -92,6 +93,9 @@ code.
       Return a formatted multi-line string with detailed information about the
       code object, like :func:`code_info`.
 
+   .. versionchanged:: 3.7
+      This can now handle coroutine and asynchronous generator objects.
+
 Example::
 
     >>> bytecode = dis.Bytecode(myfunc)
@@ -114,7 +118,8 @@ operation is being performed, so the intermediate analysis object isn't useful:
 .. function:: code_info(x)
 
    Return a formatted multi-line string with detailed code object information
-   for the supplied function, generator, method, source code string or code object.
+   for the supplied function, generator, asynchronous generator, coroutine,
+   method, source code string or code object.
 
    Note that the exact contents of code info strings are highly implementation
    dependent and they may change arbitrarily across Python VMs or Python
@@ -122,6 +127,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
 
    .. versionadded:: 3.2
 
+   .. versionchanged:: 3.7
+      This can now handle coroutine and asynchronous generator objects.
+
 
 .. function:: show_code(x, *, file=None)
 
@@ -141,12 +149,13 @@ operation is being performed, so the intermediate analysis object isn't useful:
 .. function:: dis(x=None, *, file=None, depth=None)
 
    Disassemble the *x* object.  *x* can denote either a module, a class, a
-   method, a function, a generator, a code object, a string of source code or
+   method, a function, a generator, an asynchronous generator, a couroutine,
-   a byte sequence of raw bytecode.  For a module, it disassembles all functions.
+   a code object, a string of source code or a byte sequence of raw bytecode.
-   For a class, it disassembles all methods (including class and static methods).
+   For a module, it disassembles all functions. For a class, it disassembles
-   For a code object or sequence of raw bytecode, it prints one line per bytecode
+   all methods (including class and static methods). For a code object or
-   instruction.  It also recursively disassembles nested code objects (the code
+   sequence of raw bytecode, it prints one line per bytecode instruction.
-   of comprehensions, generator expressions and nested functions, and the code
+   It also recursively disassembles nested code objects (the code of
+   comprehensions, generator expressions and nested functions, and the code
    used for building nested classes).
    Strings are first compiled to code objects with the :func:`compile`
    built-in function before being disassembled.  If no object is provided, this
@@ -164,6 +173,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
    .. versionchanged:: 3.7
       Implemented recursive disassembling and added *depth* parameter.
 
+   .. versionchanged:: 3.7
+      This can now handle coroutine and asynchronous generator objects.
+
 
 .. function:: distb(tb=None, *, file=None)
 
@@ -546,8 +558,11 @@ the original TOS1.
 
 .. opcode:: GET_AITER
 
-   Implements ``TOS = get_awaitable(TOS.__aiter__())``.  See ``GET_AWAITABLE``
+   Implements ``TOS = TOS.__aiter__()``.
-   for details about ``get_awaitable``
+
+   .. versionchanged:: 3.7
+      Returning awaitable objects from ``__aiter__`` is no longer
+      supported.
 
 
 .. opcode:: GET_ANEXT
@@ -1062,7 +1077,7 @@ All of the following opcodes use their arguments.
    Pops all function arguments, and the function itself off the stack, and
    pushes the return value. Note that this opcode pops at most three items
    from the stack. Var-positional and var-keyword arguments are packed
-   by :opcode:`BUILD_MAP_UNPACK_WITH_CALL` and
+   by :opcode:`BUILD_TUPLE_UNPACK_WITH_CALL` and
    :opcode:`BUILD_MAP_UNPACK_WITH_CALL`.
 
    .. versionadded:: 3.6

Doc/library/dummy_threading.rst

@@ -6,20 +6,15 @@
 
 **Source code:** :source:`Lib/dummy_threading.py`
 
+.. deprecated:: 3.7
+   Python now always has threading enabled.  Please use :mod:`threading` instead.
+
 --------------
 
-This module provides a duplicate interface to the :mod:`threading` module.  It
+This module provides a duplicate interface to the :mod:`threading` module.
-is meant to be imported when the :mod:`_thread` module is not provided on a
+It was meant to be imported when the :mod:`_thread` module was not provided
-platform.
+on a platform.
-
-Suggested usage is::
-
-   try:
-       import threading
-   except ImportError:
-       import dummy_threading as threading
 
 Be careful to not use this module where deadlock might occur from a thread being
 created that blocks waiting for another thread to be created.  This often occurs
 with blocking I/O.
-

Doc/library/ensurepip.rst

@@ -78,6 +78,9 @@ options:
 
 Providing both of the script selection options will trigger an exception.
 
+.. versionchanged:: 3.7.0
+   The exit status is non-zero if the command fails.
+
 
 Module API
 ----------

Doc/library/fnmatch.rst

@@ -86,7 +86,7 @@ patterns.
       '(?s:.*\\.txt)\\Z'
       >>> reobj = re.compile(regex)
       >>> reobj.match('foobar.txt')
-      <_sre.SRE_Match object; span=(0, 10), match='foobar.txt'>
+      <re.Match object; span=(0, 10), match='foobar.txt'>
 
 
 .. seealso::

Doc/library/functions.rst

@@ -7,15 +7,16 @@ Built-in Functions
 The Python interpreter has a number of functions and types built into it that
 are always available.  They are listed here in alphabetical order.
 
-===================  =================  ==================  ================  ====================
+===================  =================  ==================  ==================  ====================
 ..                   ..                 Built-in Functions  ..                  ..
-===================  =================  ==================  ================  ====================
+===================  =================  ==================  ==================  ====================
-:func:`abs`          |func-dict|_       :func:`help`        :func:`min`       :func:`setattr`
+:func:`abs`          :func:`delattr`    :func:`hash`        |func-memoryview|_  |func-set|_
-:func:`all`          :func:`dir`        :func:`hex`         :func:`next`      :func:`slice`
+:func:`all`          |func-dict|_       :func:`help`        :func:`min`         :func:`setattr`
-:func:`any`          :func:`divmod`     :func:`id`          :func:`object`    :func:`sorted`
+:func:`any`          :func:`dir`        :func:`hex`         :func:`next`        :func:`slice`
-:func:`ascii`        :func:`enumerate`  :func:`input`       :func:`oct`       :func:`staticmethod`
+:func:`ascii`        :func:`divmod`     :func:`id`          :func:`object`      :func:`sorted`
-:func:`bin`          :func:`eval`       :func:`int`         :func:`open`      |func-str|_
+:func:`bin`          :func:`enumerate`  :func:`input`       :func:`oct`         :func:`staticmethod`
-:func:`bool`         :func:`exec`       :func:`isinstance`  :func:`ord`       :func:`sum`
+:func:`bool`         :func:`eval`       :func:`int`         :func:`open`        |func-str|_
+:func:`breakpoint`   :func:`exec`       :func:`isinstance`  :func:`ord`         :func:`sum`
 |func-bytearray|_    :func:`filter`     :func:`issubclass`  :func:`pow`         :func:`super`
 |func-bytes|_        :func:`float`      :func:`iter`        :func:`print`       |func-tuple|_
 :func:`callable`     :func:`format`     :func:`len`         :func:`property`    :func:`type`
@@ -23,8 +24,7 @@ are always available.  They are listed here in alphabetical order.
 :func:`classmethod`  :func:`getattr`    :func:`locals`      :func:`repr`        :func:`zip`
 :func:`compile`      :func:`globals`    :func:`map`         :func:`reversed`    :func:`__import__`
 :func:`complex`      :func:`hasattr`    :func:`max`         :func:`round`
-:func:`delattr`      :func:`hash`       |func-memoryview|_  |func-set|_
+===================  =================  ==================  ==================  ====================
-===================  =================  ==================  ================  ====================
 
 .. using :func:`dict` would create a link to another page, so local targets are
    used, with replacement texts to make the output in the table consistent
@@ -81,9 +81,24 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: bin(x)
 
-   Convert an integer number to a binary string. The result is a valid Python
+   Convert an integer number to a binary string prefixed with "0b". The result
-   expression.  If *x* is not a Python :class:`int` object, it has to define an
+   is a valid Python expression. If *x* is not a Python :class:`int` object, it
-   :meth:`__index__` method that returns an integer.
+   has to define an :meth:`__index__` method that returns an integer. Some
+   examples:
+
+      >>> bin(3)
+      '0b11'
+      >>> bin(-10)
+      '-0b1010'
+
+   If prefix "0b" is desired or not, you can use either of the following ways.
+
+      >>> format(14, '#b'), format(14, 'b')
+      ('0b1110', '1110')
+      >>> f'{14:#b}', f'{14:b}'
+      ('0b1110', '1110')
+
+  See also :func:`format` for more information.
 
 
 .. class:: bool([x])
@@ -98,6 +113,20 @@ are always available.  They are listed here in alphabetical order.
    .. index:: pair: Boolean; type
 
 
+.. function:: breakpoint(*args, **kws)
+
+   This function drops you into the debugger at the call site.  Specifically,
+   it calls :func:`sys.breakpointhook`, passing ``args`` and ``kws`` straight
+   through.  By default, ``sys.breakpointhook()`` calls
+   :func:`pdb.set_trace()` expecting no arguments.  In this case, it is
+   purely a convenience function so you don't have to explicitly import
+   :mod:`pdb` or type as much code to enter the debugger.  However,
+   :func:`sys.breakpointhook` can be set to some other function and
+   :func:`breakpoint` will automatically call that, allowing you to drop into
+   the debugger of choice.
+
+   .. versionadded:: 3.7
+
 .. _func-bytearray:
 .. class:: bytearray([source[, encoding[, errors]]])
    :noindex:
@@ -167,9 +196,9 @@ are always available.  They are listed here in alphabetical order.
    base 16).  :exc:`ValueError` will be raised if *i* is outside that range.
 
 
-.. function:: classmethod(function)
+.. decorator:: classmethod
 
-   Return a class method for *function*.
+   Transform a method into a class method.
 
    A class method receives the class as implicit first argument, just like an
    instance method receives the instance. To declare a class method, use this
@@ -635,16 +664,26 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: hex(x)
 
-   Convert an integer number to a lowercase hexadecimal string
+   Convert an integer number to a lowercase hexadecimal string prefixed with
-   prefixed with "0x", for example:
+   "0x". If x is not a Python :class:`int` object, it has to define an
+   __index__() method that returns an integer. Some examples:
 
       >>> hex(255)
       '0xff'
       >>> hex(-42)
       '-0x2a'
 
-   If x is not a Python :class:`int` object, it has to define an __index__()
+   If you want to convert an integer number to an uppercase or lower hexadecimal
-   method that returns an integer.
+   string with prefix or not, you can use either of the following ways:
+
+     >>> '%#x' % 255, '%x' % 255, '%X' % 255
+     ('0xff', 'ff', 'FF')
+     >>> format(255, '#x'), format(255, 'x'), format(255, 'X')
+     ('0xff', 'ff', 'FF')
+     >>> f'{255:#x}', f'{255:x}', f'{255:X}'
+     ('0xff', 'ff', 'FF')
+
+   See also :func:`format` for more information.
 
    See also :func:`int` for converting a hexadecimal string to an
    integer using a base of 16.
@@ -878,10 +917,27 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: oct(x)
 
-   Convert an integer number to an octal string.  The result is a valid Python
+  Convert an integer number to an octal string prefixed with "0o".  The result
-   expression.  If *x* is not a Python :class:`int` object, it has to define an
+  is a valid Python expression. If *x* is not a Python :class:`int` object, it
-   :meth:`__index__` method that returns an integer.
+  has to define an :meth:`__index__` method that returns an integer. For
+  example:
 
+      >>> oct(8)
+      '0o10'
+      >>> oct(-56)
+      '-0o70'
+
+  If you want to convert an integer number to octal string either with prefix
+  "0o" or not, you can use either of the following ways.
+
+      >>> '%#o' % 10, '%o' % 10
+      ('0o12', '12')
+      >>> format(10, '#o'), format(10, 'o')
+      ('0o12', '12')
+      >>> f'{10:#o}', f'{10:o}'
+      ('0o12', '12')
+
+  See also :func:`format` for more information.
 
    .. index::
       single: file object; open() built-in function
@@ -1319,7 +1375,7 @@ are always available.  They are listed here in alphabetical order.
    :func:`itertools.islice` for an alternate version that returns an iterator.
 
 
-.. function:: sorted(iterable[, key][, reverse])
+.. function:: sorted(iterable, *, key=None, reverse=False)
 
    Return a new sorted list from the items in *iterable*.
 
@@ -1342,9 +1398,9 @@ are always available.  They are listed here in alphabetical order.
 
    For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
 
-.. function:: staticmethod(function)
+.. decorator:: staticmethod
 
-   Return a static method for *function*.
+   Transform a method into a static method.
 
    A static method does not receive an implicit first argument. To declare a static
    method, use this idiom::
@@ -1363,12 +1419,21 @@ are always available.  They are listed here in alphabetical order.
    :func:`classmethod` for a variant that is useful for creating alternate class
    constructors.
 
+   Like all decorators, it is also possible to call ``staticmethod`` as
+   a regular function and do something with its result.  This is needed
+   in some cases where you need a reference to a function from a class
+   body and you want to avoid the automatic transformation to instance
+   method.  For these cases, use this idiom:
+
+      class C:
+          builtin_open = staticmethod(open)
+
    For more information on static methods, consult the documentation on the
    standard type hierarchy in :ref:`types`.
 
-   .. index::
-      single: string; str() (built-in function)
 
+.. index::
+   single: string; str() (built-in function)
 
 .. _func-str:
 .. class:: str(object='')

Doc/library/functools.rst

@@ -264,9 +264,9 @@ The :mod:`functools` module defines the following functions:
           return value
 
 
-.. decorator:: singledispatch(default)
+.. decorator:: singledispatch
 
-   Transforms a function into a :term:`single-dispatch <single
+   Transform a function into a :term:`single-dispatch <single
    dispatch>` :term:`generic function`.
 
    To define a generic function, decorate it with the ``@singledispatch``

Doc/library/gc.rst

@@ -174,6 +174,33 @@ The :mod:`gc` module provides the following functions:
    .. versionadded:: 3.1
 
 
+.. function:: freeze()
+
+   Freeze all the objects tracked by gc - move them to a permanent generation
+   and ignore all the future collections. This can be used before a POSIX
+   fork() call to make the gc copy-on-write friendly or to speed up collection.
+   Also collection before a POSIX fork() call may free pages for future
+   allocation which can cause copy-on-write too so it's advised to disable gc
+   in master process and freeze before fork and enable gc in child process.
+
+   .. versionadded:: 3.7
+
+
+.. function:: unfreeze()
+
+   Unfreeze the objects in the permanent generation, put them back into the
+   oldest generation.
+
+   .. versionadded:: 3.7
+
+
+.. function:: get_freeze_count()
+
+   Return the number of objects in the permanent generation.
+
+   .. versionadded:: 3.7
+
+
 The following variables are provided for read-only access (you can mutate the
 values but should not rebind them):
 

Doc/library/gettext.rst

@@ -48,9 +48,10 @@ class-based API instead.
 
 .. function:: bind_textdomain_codeset(domain, codeset=None)
 
-   Bind the *domain* to *codeset*, changing the encoding of strings returned by the
+   Bind the *domain* to *codeset*, changing the encoding of byte strings
-   :func:`gettext` family of functions. If *codeset* is omitted, then the current
+   returned by the :func:`lgettext`, :func:`ldgettext`, :func:`lngettext`
-   binding is returned.
+   and :func:`ldngettext` functions.
+   If *codeset* is omitted, then the current binding is returned.
 
 
 .. function:: textdomain(domain=None)
@@ -67,28 +68,14 @@ class-based API instead.
    :func:`_` in the local namespace (see examples below).
 
 
-.. function:: lgettext(message)
-
-   Equivalent to :func:`gettext`, but the translation is returned in the
-   preferred system encoding, if no other encoding was explicitly set with
-   :func:`bind_textdomain_codeset`.
-
-
 .. function:: dgettext(domain, message)
 
-   Like :func:`gettext`, but look the message up in the specified *domain*.
+   Like :func:`.gettext`, but look the message up in the specified *domain*.
-
-
-.. function:: ldgettext(domain, message)
-
-   Equivalent to :func:`dgettext`, but the translation is returned in the
-   preferred system encoding, if no other encoding was explicitly set with
-   :func:`bind_textdomain_codeset`.
 
 
 .. function:: ngettext(singular, plural, n)
 
-   Like :func:`gettext`, but consider plural forms. If a translation is found,
+   Like :func:`.gettext`, but consider plural forms. If a translation is found,
    apply the plural formula to *n*, and return the resulting message (some
    languages have more than two plural forms). If no translation is found, return
    *singular* if *n* is 1; return *plural* otherwise.
@@ -101,24 +88,33 @@ class-based API instead.
    formulas for a variety of languages.
 
 
-.. function:: lngettext(singular, plural, n)
-
-   Equivalent to :func:`ngettext`, but the translation is returned in the
-   preferred system encoding, if no other encoding was explicitly set with
-   :func:`bind_textdomain_codeset`.
-
-
 .. function:: dngettext(domain, singular, plural, n)
 
    Like :func:`ngettext`, but look the message up in the specified *domain*.
 
 
+.. function:: lgettext(message)
+.. function:: ldgettext(domain, message)
+.. function:: lngettext(singular, plural, n)
 .. function:: ldngettext(domain, singular, plural, n)
 
-   Equivalent to :func:`dngettext`, but the translation is returned in the
+   Equivalent to the corresponding functions without the ``l`` prefix
-   preferred system encoding, if no other encoding was explicitly set with
+   (:func:`.gettext`, :func:`dgettext`, :func:`ngettext` and :func:`dngettext`),
+   but the translation is returned as a byte string encoded in the preferred
+   system encoding if no other encoding was explicitly set with
    :func:`bind_textdomain_codeset`.
 
+   .. warning::
+
+      These functions should be avoided in Python 3, because they return
+      encoded bytes.  It's much better to use alternatives which return
+      Unicode strings instead, since most Python applications will want to
+      manipulate human readable text as strings instead of bytes.  Further,
+      it's possible that you may get unexpected Unicode-related exceptions
+      if there are encoding problems with the translated strings.  It is
+      possible that the ``l*()`` functions will be deprecated in future Python
+      versions due to their inherent problems and limitations.
+
 
 Note that GNU :program:`gettext` also defines a :func:`dcgettext` method, but
 this was deemed not useful and so it is currently unimplemented.
@@ -138,7 +134,7 @@ Class-based API
 
 The class-based API of the :mod:`gettext` module gives you more flexibility and
 greater convenience than the GNU :program:`gettext` API.  It is the recommended
-way of localizing your Python applications and modules.  :mod:`gettext` defines
+way of localizing your Python applications and modules.  :mod:`!gettext` defines
 a "translations" class which implements the parsing of GNU :file:`.mo` format
 files, and has methods for returning strings. Instances of this "translations"
 class can also install themselves in the built-in namespace as the function
@@ -179,8 +175,9 @@ class can also install themselves in the built-in namespace as the function
    names are cached.  The actual class instantiated is either *class_* if
    provided, otherwise :class:`GNUTranslations`.  The class's constructor must
    take a single :term:`file object` argument.  If provided, *codeset* will change
-   the charset used to encode translated strings in the :meth:`lgettext` and
+   the charset used to encode translated strings in the
-   :meth:`lngettext` methods.
+   :meth:`~NullTranslations.lgettext` and :meth:`~NullTranslations.lngettext`
+   methods.
 
    If multiple files are found, later files are used as fallbacks for earlier ones.
    To allow setting the fallback, :func:`copy.copy` is used to clone each
@@ -222,7 +219,7 @@ Translation classes are what actually implement the translation of original
 source file message strings to translated message strings. The base class used
 by all translation classes is :class:`NullTranslations`; this provides the basic
 interface you can use to write your own specialized translation classes.  Here
-are the methods of :class:`NullTranslations`:
+are the methods of :class:`!NullTranslations`:
 
 
 .. class:: NullTranslations(fp=None)
@@ -250,26 +247,29 @@ are the methods of :class:`NullTranslations`:
 
    .. method:: gettext(message)
 
-      If a fallback has been set, forward :meth:`gettext` to the fallback.
+      If a fallback has been set, forward :meth:`!gettext` to the fallback.
-      Otherwise, return the translated message.  Overridden in derived classes.
+      Otherwise, return *message*.  Overridden in derived classes.
-
-
-   .. method:: lgettext(message)
-
-      If a fallback has been set, forward :meth:`lgettext` to the fallback.
-      Otherwise, return the translated message.  Overridden in derived classes.
 
 
    .. method:: ngettext(singular, plural, n)
 
-      If a fallback has been set, forward :meth:`ngettext` to the fallback.
+      If a fallback has been set, forward :meth:`!ngettext` to the fallback.
-      Otherwise, return the translated message.  Overridden in derived classes.
+      Otherwise, return *singular* if *n* is 1; return *plural* otherwise.
+      Overridden in derived classes.
 
 
+   .. method:: lgettext(message)
    .. method:: lngettext(singular, plural, n)
 
-      If a fallback has been set, forward :meth:`lngettext` to the fallback.
+      Equivalent to :meth:`.gettext` and :meth:`.ngettext`, but the translation
-      Otherwise, return the translated message.  Overridden in derived classes.
+      is returned as a byte string encoded in the preferred system encoding
+      if no encoding was explicitly set with :meth:`set_output_charset`.
+      Overridden in derived classes.
+
+      .. warning::
+
+         These methods should be avoided in Python 3.  See the warning for the
+         :func:`lgettext` function.
 
 
    .. method:: info()
@@ -279,32 +279,28 @@ are the methods of :class:`NullTranslations`:
 
    .. method:: charset()
 
-      Return the "protected" :attr:`_charset` variable, which is the encoding of
+      Return the encoding of the message catalog file.
-      the message catalog file.
 
 
    .. method:: output_charset()
 
-      Return the "protected" :attr:`_output_charset` variable, which defines the
+      Return the encoding used to return translated messages in :meth:`.lgettext`
-      encoding used to return translated messages in :meth:`lgettext` and
+      and :meth:`.lngettext`.
-      :meth:`lngettext`.
 
 
    .. method:: set_output_charset(charset)
 
-      Change the "protected" :attr:`_output_charset` variable, which defines the
+      Change the encoding used to return translated messages.
-      encoding used to return translated messages.
 
 
    .. method:: install(names=None)
 
-      This method installs :meth:`self.gettext` into the built-in namespace,
+      This method installs :meth:`.gettext` into the built-in namespace,
       binding it to ``_``.
 
       If the *names* parameter is given, it must be a sequence containing the
       names of functions you want to install in the builtins namespace in
-      addition to :func:`_`.  Supported names are ``'gettext'`` (bound to
+      addition to :func:`_`.  Supported names are ``'gettext'``, ``'ngettext'``,
-      :meth:`self.gettext`), ``'ngettext'`` (bound to :meth:`self.ngettext`),
       ``'lgettext'`` and ``'lngettext'``.
 
       Note that this is only one way, albeit the most convenient way, to make
@@ -349,33 +345,29 @@ If the :file:`.mo` file's magic number is invalid, the major version number is
 unexpected, or if other problems occur while reading the file, instantiating a
 :class:`GNUTranslations` class can raise :exc:`OSError`.
 
-The following methods are overridden from the base class implementation:
+.. class:: GNUTranslations
 
+   The following methods are overridden from the base class implementation:
 
-.. method:: GNUTranslations.gettext(message)
+   .. method:: gettext(message)
 
       Look up the *message* id in the catalog and return the corresponding message
       string, as a Unicode string.  If there is no entry in the catalog for the
       *message* id, and a fallback has been set, the look up is forwarded to the
-   fallback's :meth:`gettext` method.  Otherwise, the *message* id is returned.
+      fallback's :meth:`~NullTranslations.gettext` method.  Otherwise, the
+      *message* id is returned.
 
 
-.. method:: GNUTranslations.lgettext(message)
+   .. method:: ngettext(singular, plural, n)
-
-   Equivalent to :meth:`gettext`, but the translation is returned as a
-   bytestring encoded in the selected output charset, or in the preferred system
-   encoding if no encoding was explicitly set with :meth:`set_output_charset`.
-
-
-.. method:: GNUTranslations.ngettext(singular, plural, n)
 
       Do a plural-forms lookup of a message id.  *singular* is used as the message id
       for purposes of lookup in the catalog, while *n* is used to determine which
       plural form to use.  The returned message string is a Unicode string.
 
-   If the message id is not found in the catalog, and a fallback is specified, the
+      If the message id is not found in the catalog, and a fallback is specified,
-   request is forwarded to the fallback's :meth:`ngettext` method.  Otherwise, when
+      the request is forwarded to the fallback's :meth:`~NullTranslations.ngettext`
-   *n* is 1 *singular* is returned, and *plural* is returned in all other cases.
+      method.  Otherwise, when *n* is 1 *singular* is returned, and *plural* is
+      returned in all other cases.
 
       Here is an example::
 
@@ -387,11 +379,18 @@ The following methods are overridden from the base class implementation:
              n) % {'num': n}
 
 
-.. method:: GNUTranslations.lngettext(singular, plural, n)
+   .. method:: lgettext(message)
+   .. method:: lngettext(singular, plural, n)
 
-   Equivalent to :meth:`gettext`, but the translation is returned as a
+      Equivalent to :meth:`.gettext` and :meth:`.ngettext`, but the translation
-   bytestring encoded in the selected output charset, or in the preferred system
+      is returned as a byte string encoded in the preferred system encoding
-   encoding if no encoding was explicitly set with :meth:`set_output_charset`.
+      if no encoding  was explicitly set with
+      :meth:`~NullTranslations.set_output_charset`.
+
+      .. warning::
+
+         These methods should be avoided in Python 3.  See the warning for the
+         :func:`lgettext` function.
 
 
 Solaris message catalog support
@@ -509,7 +508,7 @@ module::
 
    import gettext
    t = gettext.translation('spam', '/usr/share/locale')
-   _ = t.lgettext
+   _ = t.gettext
 
 
 Localizing your application

Doc/library/hashlib.rst

@@ -267,7 +267,7 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
    should be about 16 or more bytes from a proper source, e.g. :func:`os.urandom`.
 
    *n* is the CPU/Memory cost factor, *r* the block size, *p* parallelization
-   factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MB).
+   factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MiB).
    *dklen* is the length of the derived key.
 
    Availability: OpenSSL 1.1+
@@ -506,18 +506,23 @@ to users and later verify them to make sure they weren't tampered with::
     >>> AUTH_SIZE = 16
     >>>
     >>> def sign(cookie):
-    ...     h = blake2b(data=cookie, digest_size=AUTH_SIZE, key=SECRET_KEY)
+    ...     h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)
-    ...     return h.hexdigest()
+    ...     h.update(cookie)
+    ...     return h.hexdigest().encode('utf-8')
     >>>
-    >>> cookie = b'user:vatrogasac'
+    >>> def verify(cookie, sig):
+    ...     good_sig = sign(cookie)
+    ...     return compare_digest(good_sig, sig)
+    >>>
+    >>> cookie = b'user-alice'
     >>> sig = sign(cookie)
     >>> print("{0},{1}".format(cookie.decode('utf-8'), sig))
-    user:vatrogasac,349cf904533767ed2d755279a8df84d0
+    user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'
-    >>> compare_digest(cookie, sig)
+    >>> verify(cookie, sig)
     True
-    >>> compare_digest(b'user:policajac', sig)
+    >>> verify(b'user-bob', sig)
     False
-    >>> compare_digesty(cookie, '0102030405060708090a0b0c0d0e0f00')
+    >>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')
     False
 
 Even though there's a native keyed hashing mode, BLAKE2 can, of course, be used

Doc/library/http.client.rst

@@ -31,7 +31,8 @@ HTTPS protocols.  It is normally not used directly --- the module
 The module provides the following classes:
 
 
-.. class:: HTTPConnection(host, port=None[, timeout], source_address=None)
+.. class:: HTTPConnection(host, port=None[, timeout], source_address=None, \
+                          blocksize=8192)
 
    An :class:`HTTPConnection` instance represents one transaction with an HTTP
    server.  It should be instantiated passing it a host and optional port
@@ -42,6 +43,8 @@ The module provides the following classes:
    (if it is not given, the global default timeout setting is used).
    The optional *source_address* parameter may be a tuple of a (host, port)
    to use as the source address the HTTP connection is made from.
+   The optional *blocksize* parameter sets the buffer size in bytes for
+   sending a file-like message body.
 
    For example, the following calls all create instances that connect to the server
    at the same host and port::
@@ -58,11 +61,14 @@ The module provides the following classes:
       The  *strict* parameter was removed. HTTP 0.9-style "Simple Responses" are
       not longer supported.
 
+   .. versionchanged:: 3.7
+      *blocksize* parameter was added.
+
 
 .. class:: HTTPSConnection(host, port=None, key_file=None, \
                            cert_file=None[, timeout], \
                            source_address=None, *, context=None, \
-                           check_hostname=None)
+                           check_hostname=None, blocksize=8192)
 
    A subclass of :class:`HTTPConnection` that uses SSL for communication with
    secure servers.  Default port is ``443``.  If *context* is specified, it
@@ -338,6 +344,14 @@ HTTPConnection Objects
 
    Close the connection to the server.
 
+
+.. attribute:: HTTPConnection.blocksize
+
+   Buffer size in bytes for sending a file-like message body.
+
+   .. versionadded:: 3.7
+
+
 As an alternative to using the :meth:`request` method described above, you can
 also send your request step by step, by using the four functions below.
 

Doc/library/http.rst

@@ -98,6 +98,7 @@ Code    Enum Name                           Details
 ``415`` ``UNSUPPORTED_MEDIA_TYPE``          HTTP/1.1 :rfc:`7231`, Section 6.5.13
 ``416`` ``REQUEST_RANGE_NOT_SATISFIABLE``   HTTP/1.1 Range Requests :rfc:`7233`, Section 4.4
 ``417`` ``EXPECTATION_FAILED``              HTTP/1.1 :rfc:`7231`, Section 6.5.14
+``421`` ``MISDIRECTED_REQUEST``             HTTP/2 :rfc:`7540`, Section 9.1.2
 ``422`` ``UNPROCESSABLE_ENTITY``            WebDAV :rfc:`4918`, Section 11.2
 ``423`` ``LOCKED``                          WebDAV :rfc:`4918`, Section 11.3
 ``424`` ``FAILED_DEPENDENCY``               WebDAV :rfc:`4918`, Section 11.4
@@ -122,3 +123,6 @@ In order to preserve backwards compatibility, enum values are also present
 in the :mod:`http.client` module in the form of constants. The enum name is
 equal to the constant name (i.e. ``http.HTTPStatus.OK`` is also available as
 ``http.client.OK``).
+
+.. versionchanged:: 3.7
+   Added ``421 MISDIRECTED_REQUEST`` status code.

Doc/library/idle.rst

@@ -190,7 +190,9 @@ Format Paragraph
    paragraph will be formatted to less than N columns, where N defaults to 72.
 
 Strip trailing whitespace
-   Remove any space characters after the last non-space character of a line.
+   Remove trailing space and other whitespace characters after the last
+   non-whitespace character of a line by applying str.rstrip to each line,
+   including lines within multiline strings.
 
 .. index::
    single: Run script
@@ -599,15 +601,15 @@ starting from a console (``python -m idlelib)`` and see if a message appears.
 IDLE-console differences
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-As much as possible, the result of executing Python code with IDLE is the
+With rare exceptions, the result of executing Python code with IDLE is
-same as executing the same code in a console window.  However, the different
+intended to be the same as executing the same code in a console window.
-interface and operation occasionally affect visible results.  For instance,
+However, the different interface and operation occasionally affect
-``sys.modules`` starts with more entries.
+visible results.  For instance, ``sys.modules`` starts with more entries.
 
 IDLE also replaces ``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` with
 objects that get input from and send output to the Shell window.
-When this window has the focus, it controls the keyboard and screen.
+When Shell has the focus, it controls the keyboard and screen.  This is
-This is normally transparent, but functions that directly access the keyboard
+normally transparent, but functions that directly access the keyboard
 and screen will not work.  If ``sys`` is reset with ``importlib.reload(sys)``,
 IDLE's changes are lost and things like ``input``, ``raw_input``, and
 ``print`` will not work correctly.
@@ -617,6 +619,29 @@ Some consoles only work with a single physical line at a time.  IDLE uses
 ``exec`` to run each statement.  As a result, ``'__builtins__'`` is always
 defined for each statement.
 
+Developing tkinter applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+IDLE is intentionally different from standard Python in order to
+facilitate development of tkinter programs.  Enter ``import tkinter as tk;
+root = tk.Tk()`` in standard Python and nothing appears.  Enter the same
+in IDLE and a tk window appears.  In standard Python, one must also enter
+``root.update()`` to see the window.  IDLE does the equivalent in the
+background, about 20 times a second, which is about every 50 milleseconds.
+Next enter ``b = tk.Button(root, text='button'); b.pack()``.  Again,
+nothing visibly changes in standard Python until one enters ``root.update()``.
+
+Most tkinter programs run ``root.mainloop()``, which usually does not
+return until the tk app is destroyed.  If the program is run with
+``python -i`` or from an IDLE editor, a ``>>>`` shell prompt does not
+appear until ``mainloop()`` returns, at which time there is nothing left
+to interact with.
+
+When running a tkinter program from an IDLE editor, one can comment out
+the mainloop call.  One then gets a shell prompt immediately and can
+interact with the live application.  One just has to remember to
+re-enable the mainloop call when running in standard Python.
+
 Running without a subprocess
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -671,24 +696,7 @@ Extensions
 ^^^^^^^^^^
 
 IDLE contains an extension facility.  Preferences for extensions can be
-changed with Configure Extensions. See the beginning of config-extensions.def
+changed with the Extensions tab of the preferences dialog. See the
-in the idlelib directory for further information.  The default extensions
+beginning of config-extensions.def in the idlelib directory for further
-are currently:
+information.  The only current default extension is zzdummy, an example
-
+also used for testing.
-* FormatParagraph
-
-* AutoExpand
-
-* ZoomHeight
-
-* ScriptBinding
-
-* CallTips
-
-* ParenMatch
-
-* AutoComplete
-
-* CodeContext
-
-* RstripExtension

Doc/library/importlib.rst

@@ -32,7 +32,7 @@ generically as an :term:`importer`) to participate in the import process.
     :ref:`import`
         The language reference for the :keyword:`import` statement.
 
-    `Packages specification <http://legacy.python.org/doc/essays/packages.html>`__
+    `Packages specification <https://www.python.org/doc/essays/packages/>`__
         Original specification of packages. Some semantics have changed since
         the writing of this document (e.g. redirecting based on ``None``
         in :data:`sys.modules`).
@@ -1048,7 +1048,15 @@ find and load modules.
 
 .. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
 
-   A specification for a module's import-system-related state.
+   A specification for a module's import-system-related state.  This is
+   typically exposed as the module's ``__spec__`` attribute.  In the
+   descriptions below, the names in parentheses give the corresponding
+   attribute available directly on the module object.
+   E.g. ``module.__spec__.origin == module.__file__``.  Note however that
+   while the *values* are usually equivalent, they can differ since there is
+   no synchronization between the two objects.  Thus it is possible to update
+   the module's ``__path__`` at runtime, and this will not be automatically
+   reflected in ``__spec__.submodule_search_locations``.
 
    .. versionadded:: 3.4
 

Doc/library/ipaddress.rst

@@ -543,6 +543,28 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
          >>> ip_network('192.0.2.0/24').supernet(new_prefix=20)
          IPv4Network('192.0.0.0/20')
 
+   .. method:: subnet_of(other)
+
+      Returns *True* if this network is a subnet of *other*.
+
+        >>> a = ip_network('192.168.1.0/24')
+        >>> b = ip_network('192.168.1.128/30')
+        >>> b.subnet_of(a)
+        True
+
+      .. versionadded:: 3.7
+
+   .. method:: supernet_of(other)
+
+      Returns *True* if this network is a supernet of *other*.
+
+        >>> a = ip_network('192.168.1.0/24')
+        >>> b = ip_network('192.168.1.128/30')
+        >>> a.supernet_of(b)
+        True
+
+      .. versionadded:: 3.7
+
    .. method:: compare_networks(other)
 
       Compare this network to *other*.  In this comparison only the network
@@ -621,6 +643,8 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
    .. method:: address_exclude(network)
    .. method:: subnets(prefixlen_diff=1, new_prefix=None)
    .. method:: supernet(prefixlen_diff=1, new_prefix=None)
+   .. method:: subnet_of(other)
+   .. method:: supernet_of(other)
    .. method:: compare_networks(other)
 
       Refer to the corresponding attribute documentation in

Doc/library/itertools.rst

@@ -53,7 +53,7 @@ Iterator                        Arguments                       Results
 :func:`compress`                data, selectors                 (d[0] if s[0]), (d[1] if s[1]), ...                 ``compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F``
 :func:`dropwhile`               pred, seq                       seq[n], seq[n+1], starting when pred fails          ``dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1``
 :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[, keyfunc]             sub-iterators grouped by value of keyfunc(v)
+: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:`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``
@@ -401,13 +401,14 @@ loops that truncate the stream.
           def __iter__(self):
               return self
           def __next__(self):
+              self.id = object()
               while self.currkey == self.tgtkey:
                   self.currvalue = next(self.it)    # Exit on StopIteration
                   self.currkey = self.keyfunc(self.currvalue)
               self.tgtkey = self.currkey
-              return (self.currkey, self._grouper(self.tgtkey))
+              return (self.currkey, self._grouper(self.tgtkey, self.id))
-          def _grouper(self, tgtkey):
+          def _grouper(self, tgtkey, id):
-              while self.currkey == tgtkey:
+              while self.id is id and self.currkey == tgtkey:
                   yield self.currvalue
                   try:
                       self.currvalue = next(self.it)
@@ -630,26 +631,25 @@ loops that truncate the stream.
    iterables are of uneven length, missing values are filled-in with *fillvalue*.
    Iteration continues until the longest iterable is exhausted.  Roughly equivalent to::
 
-      class ZipExhausted(Exception):
+      def zip_longest(*args, fillvalue=None):
-          pass
-
-      def zip_longest(*args, **kwds):
           # zip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-
-          fillvalue = kwds.get('fillvalue')
+          iterators = [iter(it) for it in args]
-          counter = len(args) - 1
+          num_active = len(iterators)
-          def sentinel():
+          if not num_active:
-              nonlocal counter
+              return
-              if not counter:
+          while True:
-                  raise ZipExhausted
+              values = []
-              counter -= 1
+              for i, it in enumerate(iterators):
-              yield fillvalue
-          fillers = repeat(fillvalue)
-          iterators = [chain(it, sentinel(), fillers) for it in args]
                   try:
-              while iterators:
+                      value = next(it)
-                  yield tuple(map(next, iterators))
+                  except StopIteration:
-          except ZipExhausted:
+                      num_active -= 1
-              pass
+                      if not num_active:
+                          return
+                      iterators[i] = repeat(fillvalue)
+                      value = fillvalue
+                  values.append(value)
+              yield tuple(values)
 
    If one of the iterables is potentially infinite, then the :func:`zip_longest`
    function should be wrapped with something that limits the number of calls

Doc/library/json.rst

@@ -43,7 +43,7 @@ Encoding basic Python object hierarchies::
 Compact encoding::
 
     >>> import json
-    >>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',', ':'))
+    >>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))
     '[1,2,3,{"4":5,"6":7}]'
 
 Pretty printing::

Doc/library/locale.rst

@@ -373,7 +373,7 @@ The :mod:`locale` module defines the following exception and functions:
 
    Please note that this function works like :meth:`format_string` but will
    only work for exactly one ``%char`` specifier.  For example, ``'%f'`` and
-   ``'%.0f'`` are both valid specifiers, but ``'%f kB'`` is not.
+   ``'%.0f'`` are both valid specifiers, but ``'%f KiB'`` is not.
 
    For whole format strings, use :func:`format_string`.
 
@@ -551,17 +551,23 @@ library.
 Access to message catalogs
 --------------------------
 
+.. function:: gettext(msg)
+.. function:: dgettext(domain, msg)
+.. function:: dcgettext(domain, msg, category)
+.. function:: textdomain(domain)
+.. function:: bindtextdomain(domain, dir)
+
 The locale module exposes the C library's gettext interface on systems that
-provide this interface.  It consists of the functions :func:`gettext`,
+provide this interface.  It consists of the functions :func:`!gettext`,
-:func:`dgettext`, :func:`dcgettext`, :func:`textdomain`, :func:`bindtextdomain`,
+:func:`!dgettext`, :func:`!dcgettext`, :func:`!textdomain`, :func:`!bindtextdomain`,
-and :func:`bind_textdomain_codeset`.  These are similar to the same functions in
+and :func:`!bind_textdomain_codeset`.  These are similar to the same functions in
 the :mod:`gettext` module, but use the C library's binary format for message
 catalogs, and the C library's search algorithms for locating message catalogs.
 
 Python applications should normally find no need to invoke these functions, and
 should use :mod:`gettext` instead.  A known exception to this rule are
 applications that link with additional C libraries which internally invoke
-:c:func:`gettext` or :func:`dcgettext`.  For these applications, it may be
+:c:func:`gettext` or :c:func:`dcgettext`.  For these applications, it may be
 necessary to bind the text domain, so that the libraries can properly locate
 their message catalogs.
 

Doc/library/logging.config.rst

@@ -715,7 +715,12 @@ a corresponding section in the configuration file.
 The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging``
 package's namespace, is the list of arguments to the constructor for the handler
 class. Refer to the constructors for the relevant handlers, or to the examples
-below, to see how typical entries are constructed.
+below, to see how typical entries are constructed. If not provided, it defaults
+to ``()``.
+
+The optional ``kwargs`` entry, when :func:`eval`\ uated in the context of the
+``logging`` package's namespace, is the keyword argument dict to the constructor
+for the handler class. If not provided, it defaults to ``{}``.
 
 .. code-block:: ini
 
@@ -754,6 +759,7 @@ below, to see how typical entries are constructed.
    level=WARN
    formatter=form07
    args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
+   kwargs={'timeout': 10.0}
 
    [handler_hand08]
    class=handlers.MemoryHandler
@@ -767,6 +773,7 @@ below, to see how typical entries are constructed.
    level=NOTSET
    formatter=form09
    args=('localhost:9022', '/log', 'GET')
+   kwargs={'secure': True}
 
 Sections which specify formatter configuration are typified by the following.
 

Doc/library/logging.handlers.rst

@@ -59,6 +59,18 @@ and :meth:`flush` methods).
       :meth:`close` method is inherited from :class:`~logging.Handler` and so
       does no output, so an explicit :meth:`flush` call may be needed at times.
 
+   .. method:: setStream(stream)
+
+      Sets the instance's stream to the specified value, if it is different.
+      The old stream is flushed before the new stream is set.
+
+      :param stream: The stream that the handler should use.
+
+      :return: the old stream, if the stream was changed, or *None* if it wasn't.
+
+   .. versionadded:: 3.7
+
+
 .. versionchanged:: 3.2
    The ``StreamHandler`` class now has a ``terminator`` attribute, default
    value ``'\n'``, which is used as the terminator when writing a formatted
@@ -66,6 +78,7 @@ and :meth:`flush` methods).
    set the handler instance's ``terminator`` attribute to the empty string.
    In earlier versions, the terminator was hardcoded as ``'\n'``.
 
+
 .. _file-handler:
 
 FileHandler

Doc/library/logging.rst

@@ -94,10 +94,14 @@ is the module's name in the Python package namespace.
    .. method:: Logger.setLevel(lvl)
 
       Sets the threshold for this logger to *lvl*. Logging messages which are less
-      severe than *lvl* will be ignored. When a logger is created, the level is set to
+      severe than *lvl* will be ignored; logging messages which have severity *lvl*
-      :const:`NOTSET` (which causes all messages to be processed when the logger is
+      or higher will be emitted by whichever handler or handlers service this logger,
-      the root logger, or delegation to the parent when the logger is a non-root
+      unless a handler's level has been set to a higher severity level than *lvl*.
-      logger). Note that the root logger is created with level :const:`WARNING`.
+
+      When a logger is created, the level is set to :const:`NOTSET` (which causes
+      all messages to be processed when the logger is the root logger, or delegation
+      to the parent when the logger is a non-root logger). Note that the root logger
+      is created with level :const:`WARNING`.
 
       The term 'delegation to the parent' means that if a logger has a level of
       NOTSET, its chain of ancestor loggers is traversed until either an ancestor with
@@ -775,15 +779,15 @@ the options available to you.
 | lineno         | ``%(lineno)d``          | Source line number where the logging call was |
 |                |                         | issued (if available).                        |
 +----------------+-------------------------+-----------------------------------------------+
+| message        | ``%(message)s``         | The logged message, computed as ``msg %       |
+|                |                         | args``. This is set when                      |
+|                |                         | :meth:`Formatter.format` is invoked.          |
++----------------+-------------------------+-----------------------------------------------+
 | module         | ``%(module)s``          | Module (name portion of ``filename``).        |
 +----------------+-------------------------+-----------------------------------------------+
 | msecs          | ``%(msecs)d``           | Millisecond portion of the time when the      |
 |                |                         | :class:`LogRecord` was created.               |
 +----------------+-------------------------+-----------------------------------------------+
-| message        | ``%(message)s``         | The logged message, computed as ``msg %       |
-|                |                         | args``. This is set when                      |
-|                |                         | :meth:`Formatter.format` is invoked.          |
-+----------------+-------------------------+-----------------------------------------------+
 | msg            | You shouldn't need to   | The format string passed in the original      |
 |                | format this yourself.   | logging call. Merged with ``args`` to         |
 |                |                         | produce ``message``, or an arbitrary object   |

Doc/library/mmap.rst

@@ -29,16 +29,20 @@ still needs to be closed when done).
    mapping.
 
 For both the Unix and Windows versions of the constructor, *access* may be
-specified as an optional keyword parameter. *access* accepts one of three
+specified as an optional keyword parameter. *access* accepts one of four
-values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY`
+values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to
-to specify read-only, write-through or copy-on-write memory respectively.
+specify read-only, write-through or copy-on-write memory respectively, or
-*access* can be used on both Unix and Windows.  If *access* is not specified,
+:const:`ACCESS_DEFAULT` to defer to *prot*.  *access* can be used on both Unix
-Windows mmap returns a write-through mapping.  The initial memory values for
+and Windows.  If *access* is not specified, Windows mmap returns a
-all three access types are taken from the specified file.  Assignment to an
+write-through mapping.  The initial memory values for all three access types
-:const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception.
+are taken from the specified file.  Assignment to an :const:`ACCESS_READ`
-Assignment to an :const:`ACCESS_WRITE` memory map affects both memory and the
+memory map raises a :exc:`TypeError` exception.  Assignment to an
-underlying file.  Assignment to an :const:`ACCESS_COPY` memory map affects
+:const:`ACCESS_WRITE` memory map affects both memory and the underlying file.
-memory but does not update the underlying file.
+Assignment to an :const:`ACCESS_COPY` memory map affects memory but does not
+update the underlying file.
+
+.. versionchanged:: 3.7
+   Added :const:`ACCESS_DEFAULT` constant.
 
 To map anonymous memory, -1 should be passed as the fileno along with the length.
 

Doc/library/msilib.rst

@@ -124,9 +124,9 @@ structures.
 
 .. seealso::
 
-   `FCICreateFile <https://msdn.microsoft.com/library?url=/library/en-us/devnotes/winprog/fcicreate.asp>`_
+   `FCICreate <https://msdn.microsoft.com/en-us/library/bb432265.aspx>`_
-   `UuidCreate <https://msdn.microsoft.com/library?url=/library/en-us/rpc/rpc/uuidcreate.asp>`_
+   `UuidCreate <https://msdn.microsoft.com/en-us/library/windows/desktop/aa379205.aspx>`_
-   `UuidToString <https://msdn.microsoft.com/library?url=/library/en-us/rpc/rpc/uuidtostring.asp>`_
+   `UuidToString <https://msdn.microsoft.com/en-us/library/windows/desktop/aa379352.aspx>`_
 
 .. _database-objects:
 
@@ -152,12 +152,18 @@ Database Objects
    :c:func:`MsiGetSummaryInformation`.  *count* is the maximum number of updated
    values.
 
+.. method:: Database.Close()
+
+   Close the database object, through :c:func:`MsiCloseHandle`.
+
+   .. versionadded:: 3.7
 
 .. seealso::
 
-   `MSIDatabaseOpenView <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msidatabaseopenview.asp>`_
+   `MSIDatabaseOpenView <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370082.aspx>`_
-   `MSIDatabaseCommit <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msidatabasecommit.asp>`_
+   `MSIDatabaseCommit <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370075.aspx>`_
-   `MSIGetSummaryInformation <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msigetsummaryinformation.asp>`_
+   `MSIGetSummaryInformation <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370301.aspx>`_
+   `MsiCloseHandle <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370067.aspx>`_
 
 .. _view-objects:
 
@@ -203,11 +209,11 @@ View Objects
 
 .. seealso::
 
-   `MsiViewExecute <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewexecute.asp>`_
+   `MsiViewExecute <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370513.aspx>`_
-   `MSIViewGetColumnInfo <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp>`_
+   `MSIViewGetColumnInfo <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370516.aspx>`_
-   `MsiViewFetch <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewfetch.asp>`_
+   `MsiViewFetch <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370514.aspx>`_
-   `MsiViewModify <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewmodify.asp>`_
+   `MsiViewModify <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370519.aspx>`_
-   `MsiViewClose <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewclose.asp>`_
+   `MsiViewClose <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370510.aspx>`_
 
 .. _summary-objects:
 
@@ -247,10 +253,10 @@ Summary Information Objects
 
 .. seealso::
 
-   `MsiSummaryInfoGetProperty <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp>`_
+   `MsiSummaryInfoGetProperty <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370409.aspx>`_
-   `MsiSummaryInfoGetPropertyCount <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfogetpropertycount.asp>`_
+   `MsiSummaryInfoGetPropertyCount <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370488.aspx>`_
-   `MsiSummaryInfoSetProperty <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfosetproperty.asp>`_
+   `MsiSummaryInfoSetProperty <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370491.aspx>`_
-   `MsiSummaryInfoPersist <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfopersist.asp>`_
+   `MsiSummaryInfoPersist <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370490.aspx>`_
 
 .. _record-objects:
 
@@ -301,18 +307,18 @@ Record Objects
 
 .. seealso::
 
-   `MsiRecordGetFieldCount <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp>`_
+   `MsiRecordGetFieldCount <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370366.aspx>`_
-   `MsiRecordSetString <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetstring.asp>`_
+   `MsiRecordSetString <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370373.aspx>`_
-   `MsiRecordSetStream <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetstream.asp>`_
+   `MsiRecordSetStream <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370372.aspx>`_
-   `MsiRecordSetInteger <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetinteger.asp>`_
+   `MsiRecordSetInteger <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370371.aspx>`_
-   `MsiRecordClear <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordclear.asp>`_
+   `MsiRecordClearData <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370364.aspx>`_
 
 .. _msi-errors:
 
 Errors
 ------
 
-All wrappers around MSI functions raise :exc:`MsiError`; the string inside the
+All wrappers around MSI functions raise :exc:`MSIError`; the string inside the
 exception will contain more detail.
 
 
@@ -392,15 +398,15 @@ Directory Objects
 
    .. method:: remove_pyc()
 
-      Remove ``.pyc``/``.pyo`` files on uninstall.
+      Remove ``.pyc`` files on uninstall.
 
 
 .. seealso::
 
-   `Directory Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/directory_table.asp>`_
+   `Directory Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368295.aspx>`_
-   `File Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/file_table.asp>`_
+   `File Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368596.aspx>`_
-   `Component Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/component_table.asp>`_
+   `Component Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368007.aspx>`_
-   `FeatureComponents Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/featurecomponents_table.asp>`_
+   `FeatureComponents Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368579.aspx>`_
 
 .. _features:
 
@@ -425,7 +431,7 @@ Features
 
 .. seealso::
 
-   `Feature Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/feature_table.asp>`_
+   `Feature Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368585.aspx>`_
 
 .. _msi-gui:
 
@@ -520,13 +526,13 @@ for installing Python packages.
 
 .. seealso::
 
-   `Dialog Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/dialog_table.asp>`_
+   `Dialog Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368286.aspx>`_
-   `Control Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/control_table.asp>`_
+   `Control Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368044.aspx>`_
-   `Control Types <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controls.asp>`_
+   `Control Types <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368039.aspx>`_
-   `ControlCondition Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controlcondition_table.asp>`_
+   `ControlCondition Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368035.aspx>`_
-   `ControlEvent Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controlevent_table.asp>`_
+   `ControlEvent Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368037.aspx>`_
-   `EventMapping Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/eventmapping_table.asp>`_
+   `EventMapping Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368559.aspx>`_
-   `RadioButton Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/radiobutton_table.asp>`_
+   `RadioButton Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370962.aspx>`_
 
 .. _msi-tables:
 

Doc/library/multiprocessing.rst

@@ -598,6 +598,22 @@ The :mod:`multiprocessing` package mostly replicates the API of the
          acquired a lock or semaphore etc. then terminating it is liable to
          cause other processes to deadlock.
 
+   .. method:: kill()
+
+      Same as :meth:`terminate()` but using the ``SIGKILL`` signal on Unix.
+
+      .. versionadded:: 3.7
+
+   .. method:: close()
+
+      Close the :class:`Process` object, releasing all resources associated
+      with it.  :exc:`ValueError` is raised if the underlying process
+      is still running.  Once :meth:`close` returns successfully, most
+      other methods and attributes of the :class:`Process` object will
+      raise :exc:`ValueError`.
+
+      .. versionadded:: 3.7
+
    Note that the :meth:`start`, :meth:`join`, :meth:`is_alive`,
    :meth:`terminate` and :attr:`exitcode` methods should only be called by
    the process that created the process object.
@@ -1018,13 +1034,13 @@ Connection objects are usually created using :func:`Pipe` -- see also
       Send an object to the other end of the connection which should be read
       using :meth:`recv`.
 
-      The object must be picklable.  Very large pickles (approximately 32 MB+,
+      The object must be picklable.  Very large pickles (approximately 32 MiB+,
       though it depends on the OS) may raise a :exc:`ValueError` exception.
 
    .. method:: recv()
 
       Return an object sent from the other end of the connection using
-      :meth:`send`.  Blocks until there its something to receive.  Raises
+      :meth:`send`.  Blocks until there is something to receive.  Raises
       :exc:`EOFError` if there is nothing left to receive
       and the other end was closed.
 
@@ -1055,7 +1071,7 @@ Connection objects are usually created using :func:`Pipe` -- see also
 
       If *offset* is given then data is read from that position in *buffer*.  If
       *size* is given then that many bytes will be read from buffer.  Very large
-      buffers (approximately 32 MB+, though it depends on the OS) may raise a
+      buffers (approximately 32 MiB+, though it depends on the OS) may raise a
       :exc:`ValueError` exception
 
    .. method:: recv_bytes([maxlength])
@@ -2165,7 +2181,7 @@ with the :class:`Pool` class.
 
       .. versionadded:: 3.3
 
-   .. method:: starmap_async(func, iterable[, chunksize[, callback[, error_back]]])
+   .. method:: starmap_async(func, iterable[, chunksize[, callback[, error_callback]]])
 
       A combination of :meth:`starmap` and :meth:`map_async` that iterates over
       *iterable* of iterables and calls *func* with the iterables unpacked.
@@ -2280,7 +2296,7 @@ multiple connections at the same time.
    If a welcome message is not received, then
    :exc:`~multiprocessing.AuthenticationError` is raised.
 
-.. function:: Client(address[, family[, authenticate[, authkey]]])
+.. function:: Client(address[, family[, authkey]])
 
    Attempt to set up a connection to the listener which is using address
    *address*, returning a :class:`~multiprocessing.Connection`.
@@ -2289,14 +2305,13 @@ multiple connections at the same time.
    generally be omitted since it can usually be inferred from the format of
    *address*. (See :ref:`multiprocessing-address-formats`)
 
-   If *authenticate* is ``True`` or *authkey* is a byte string then digest
+   If *authkey* is given and not None, it should be a byte string and will be
-   authentication is used.  The key used for authentication will be either
+   used as the secret key for an HMAC-based authentication challenge. No
-   *authkey* or ``current_process().authkey`` if *authkey* is ``None``.
+   authentication is done if *authkey* is None.
-   If authentication fails then
+   :exc:`~multiprocessing.AuthenticationError` is raised if authentication fails.
-   :exc:`~multiprocessing.AuthenticationError` is raised.  See
+   See :ref:`multiprocessing-auth-keys`.
-   :ref:`multiprocessing-auth-keys`.
 
-.. class:: Listener([address[, family[, backlog[, authenticate[, authkey]]]]])
+.. class:: Listener([address[, family[, backlog[, authkey]]]])
 
    A wrapper for a bound socket or Windows named pipe which is 'listening' for
    connections.
@@ -2325,17 +2340,10 @@ multiple connections at the same time.
    to the :meth:`~socket.socket.listen` method of the socket once it has been
    bound.
 
-   If *authenticate* is ``True`` (``False`` by default) or *authkey* is not
+   If *authkey* is given and not None, it should be a byte string and will be
-   ``None`` then digest authentication is used.
+   used as the secret key for an HMAC-based authentication challenge. No
-
+   authentication is done if *authkey* is None.
-   If *authkey* is a byte string then it will be used as the
+   :exc:`~multiprocessing.AuthenticationError` is raised if authentication fails.
-   authentication key; otherwise it must be ``None``.
-
-   If *authkey* is ``None`` and *authenticate* is ``True`` then
-   ``current_process().authkey`` is used as the authentication key.  If
-   *authkey* is ``None`` and *authenticate* is ``False`` then no
-   authentication is done.  If authentication fails then
-   :exc:`~multiprocessing.AuthenticationError` is raised.
    See :ref:`multiprocessing-auth-keys`.
 
    .. method:: accept()

Doc/library/operator.rst

@@ -17,9 +17,10 @@
 
 The :mod:`operator` module exports a set of efficient functions corresponding to
 the intrinsic operators of Python.  For example, ``operator.add(x, y)`` is
-equivalent to the expression ``x+y``.  The function names are those used for
+equivalent to the expression ``x+y``. Many function names are those used for
-special class methods; variants without leading and trailing ``__`` are also
+special methods, without the double underscores.  For backward compatibility,
-provided for convenience.
+many of these have a variant with the double underscores kept. The variants
+without the double underscores are preferred for clarity.
 
 The functions fall into categories that perform object comparisons, logical
 operations, mathematical operations and sequence operations.
@@ -321,6 +322,9 @@ expect a function argument.
       >>> itemgetter(slice(2,None))('ABCDEFG')
       'CDEFG'
 
+      >>> soldier = dict(rank='captain', name='dotterbart')
+      >>> itemgetter('rank')(soldier)
+      'captain'
 
    Example of using :func:`itemgetter` to retrieve specific fields from a
    tuple record:

Doc/library/os.path.rst

@@ -192,23 +192,17 @@ the :mod:`glob` module.)
 
 .. function:: getatime(path)
 
-   Return the time of last access of *path*.  The return value is a number giving
+   Return the time of last access of *path*.  The return value is a floating point number giving
    the number of seconds since the epoch (see the  :mod:`time` module).  Raise
    :exc:`OSError` if the file does not exist or is inaccessible.
 
-   If :func:`os.stat_float_times` returns ``True``, the result is a floating point
-   number.
-
 
 .. function:: getmtime(path)
 
-   Return the time of last modification of *path*.  The return value is a number
+   Return the time of last modification of *path*.  The return value is a floating point number
    giving the number of seconds since the epoch (see the  :mod:`time` module).
    Raise :exc:`OSError` if the file does not exist or is inaccessible.
 
-   If :func:`os.stat_float_times` returns ``True``, the result is a floating point
-   number.
-
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 

Doc/library/os.rst

@@ -2335,8 +2335,6 @@ features:
       * the time of creation on Windows, expressed in nanoseconds as an
         integer.
 
-   See also the :func:`stat_float_times` function.
-
    .. note::
 
       The exact meaning and resolution of the :attr:`st_atime`,
@@ -2431,33 +2429,6 @@ features:
       Added the :attr:`st_file_attributes` member on Windows.
 
 
-.. function:: stat_float_times([newvalue])
-
-   Determine whether :class:`stat_result` represents time stamps as float objects.
-   If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
-   ``False``, future calls return ints. If *newvalue* is omitted, return the
-   current setting.
-
-   For compatibility with older Python versions, accessing :class:`stat_result` as
-   a tuple always returns integers.
-
-   Python now returns float values by default. Applications which do not work
-   correctly with floating point time stamps can use this function to restore the
-   old behaviour.
-
-   The resolution of the timestamps (that is the smallest possible fraction)
-   depends on the system. Some systems only support second resolution; on these
-   systems, the fraction will always be zero.
-
-   It is recommended that this setting is only changed at program startup time in
-   the *__main__* module; libraries should never change this setting. If an
-   application uses a library that works incorrectly if floating point time stamps
-   are processed, this application should turn the feature off until the library
-   has been corrected.
-
-   .. deprecated:: 3.3
-
-
 .. function:: statvfs(path)
 
    Perform a :c:func:`statvfs` system call on the given path.  The return value is

Doc/library/pathlib.rst

@@ -761,6 +761,18 @@ call fails (for example because the path doesn't exist):
    other errors (such as permission errors) are propagated.
 
 
+.. method:: Path.is_mount()
+
+   Return ``True`` if the path is a :dfn:`mount point`: a point in a
+   file system where a different file system has been mounted.  On POSIX, the
+   function checks whether *path*'s parent, :file:`path/..`, is on a different
+   device than *path*, or whether :file:`path/..` and *path* point to the same
+   i-node on the same device --- this should detect mount points for all Unix
+   and POSIX variants.  Not implemented on Windows.
+
+   .. versionadded:: 3.7
+
+
 .. method:: Path.is_symlink()
 
    Return ``True`` if the path points to a symbolic link, ``False`` otherwise.