Merge branch 'master' into cached-property

* master: (107 commits)
  bpo-22057: Clarify eval() documentation (pythonGH-8812)
  bpo-34318: Convert deprecation warnings to errors in assertRaises() etc. (pythonGH-8623)
  bpo-22602: Raise an exception in the UTF-7 decoder for ill-formed sequences starting with "+". (pythonGH-8741)
  bpo-34415: Updated logging.Formatter docstring. (pythonGH-8811)
  bpo-34432: doc Mention complex and decimal.Decimal on str.format not about locales (pythonGH-8808)
  bpo-34381: refer to 'Running & Writing Tests' in README.rst (pythonGH-8797)
  Improve error message when mock.assert_has_calls fails (pythonGH-8205)
  Warn not to set SIGPIPE to SIG_DFL (python#6773)
  bpo-34419: selectmodule.c does not compile on HP-UX due to bpo-31938 (pythonGH-8796)
  bpo-34418: Fix HTTPErrorProcessor documentation (pythonGH-8793)
  bpo-34391: Fix ftplib test for TLS 1.3 (pythonGH-8787)
  bpo-34217: Use lowercase for windows headers (pythonGH-8472)
  bpo-34395: Fix memory leaks caused by incautious usage of PyMem_Resize(). (pythonGH-8756)
  bpo-34405: Updated to OpenSSL 1.1.0i for Windows builds. (pythonGH-8775)
  bpo-34384: Fix os.readlink() on Windows (pythonGH-8740)
  closes bpo-34400: Fix undefined behavior in parsetok(). (pythonGH-4439)
  bpo-34399: 2048 bits RSA keys and DH params (python#8762)
  Make regular expressions in test_tasks.py raw strings. (pythonGH-8759)
  smtplib documentation fixes (pythonGH-8708)
  Fix misindented yaml in logging how to example (pythonGH-8604)
  ...

Author: carljm

.vsts/docs.yml

@@ -23,21 +23,35 @@ steps:
   clean: true
   fetchDepth: 5
 
+- script: |
+   git fetch -q origin $(system.pullRequest.targetBranch)
+   if ! git diff --name-only HEAD $(git merge-base HEAD FETCH_HEAD) | grep -qE '(\.rst$|^Doc|^Misc)'
+   then
+     echo "No docs were updated, stopping build process."
+     echo "##vso[task.setvariable variable=NoDocs]true"
+     exit
+   fi
+  displayName: Detect doc-only changes
+  condition: and(succeeded(), variables['system.pullRequest.targetBranch'])
+
 - task: UsePythonVersion@0
   displayName: 'Use Python 3.6 or later'
   inputs:
     versionSpec: '>=3.6'
+  condition: and(succeeded(), ne(variables['NoDocs'], 'true'))
 
 - script: python -m pip install sphinx~=1.6.1 blurb python-docs-theme
   displayName: 'Install build dependencies'
+  condition: and(succeeded(), ne(variables['NoDocs'], 'true'))
 
 - script: make check suspicious html PYTHON=python
   workingDirectory: '$(build.sourcesDirectory)/Doc'
   displayName: 'Build documentation'
+  condition: and(succeeded(), ne(variables['NoDocs'], 'true'))
 
 - task: PublishBuildArtifacts@1
   displayName: 'Publish build'
-  condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))
+  condition: and(and(succeeded(), ne(variables['Build.Reason'], 'PullRequest')), ne(variables['NoDocs'], 'true'))
   inputs:
     PathToPublish: '$(build.sourcesDirectory)/Doc/build'
     ArtifactName: build

.vsts/linux-coverage.yml

@@ -27,12 +27,24 @@ steps:
   clean: true
   fetchDepth: 5
 
+- script: |
+   git fetch -q origin $(system.pullRequest.targetBranch)
+   if ! git diff --name-only HEAD $(git merge-base HEAD FETCH_HEAD) | grep -qvE '(\.rst$|^Doc|^Misc)'
+   then
+     echo "Only docs were updated, stopping build process."
+     echo "##vso[task.setvariable variable=DocOnly]true"
+     exit
+   fi
+  displayName: Detect doc-only changes
+  condition: and(succeeded(), variables['system.pullRequest.targetBranch'])
+
 #- template: linux-deps.yml
 
 # See https://github.com/Microsoft/vsts-agent/blob/master/docs/preview/yamlgettingstarted-templates.md
 # For now, we copy/paste the steps
 - script: echo "deb-src http://archive.ubuntu.com/ubuntu/ xenial main" > /etc/apt/sources.list.d/python.list && sudo apt-get update
   displayName: 'Update apt-get lists'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: echo ##vso[task.prependpath]$(OPENSSL_DIR)
   displayName: 'Add $(OPENSSL_DIR) to PATH'
@@ -55,24 +67,32 @@ steps:
     uuid-dev
     xvfb
   displayName: 'Install dependencies'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 - script: python3 Tools/ssl/multissltests.py --steps=library --base-directory $(build.sourcesDirectory)/multissl --openssl $(OPENSSL) --system Linux
   displayName: 'python multissltests.py'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 
 - script: ./configure --with-pydebug
   displayName: 'Configure CPython (debug)'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: make -s -j4
   displayName: 'Build CPython'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: ./python -m venv venv && ./venv/bin/python -m pip install -U coverage
   displayName: 'Set up virtual environment'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: ./venv/bin/python -m test.pythoninfo
   displayName: 'Display build info'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: xvfb-run ./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
   displayName: 'Tests with coverage'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: source ./venv/bin/activate && bash <(curl -s https://codecov.io/bash)
   displayName: 'Publish code coverage results'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))

.vsts/linux-pr.yml

@@ -27,15 +27,29 @@ steps:
   clean: true
   fetchDepth: 5
 
+- script: |
+   git fetch -q origin $(system.pullRequest.targetBranch)
+   if ! git diff --name-only HEAD $(git merge-base HEAD FETCH_HEAD) | grep -qvE '(\.rst$|^Doc|^Misc)'
+   then
+     echo "Only docs were updated, stopping build process."
+     echo "##vso[task.setvariable variable=DocOnly]true"
+     exit
+   fi
+  displayName: Detect doc-only changes
+  condition: and(succeeded(), variables['system.pullRequest.targetBranch'])
+
 #- template: linux-deps.yml
 
 # See https://github.com/Microsoft/vsts-agent/blob/master/docs/preview/yamlgettingstarted-templates.md
 # For now, we copy/paste the steps
 - script: echo "deb-src http://archive.ubuntu.com/ubuntu/ xenial main" > /etc/apt/sources.list.d/python.list && sudo apt-get update
   displayName: 'Update apt-get lists'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: echo ##vso[task.prependpath]$(OPENSSL_DIR)
   displayName: 'Add $(OPENSSL_DIR) to PATH'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
+
 - script: >
     sudo apt-get -yq install
     build-essential
@@ -55,22 +69,30 @@ steps:
     uuid-dev
     xvfb
   displayName: 'Install dependencies'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
+
 - script: python3 Tools/ssl/multissltests.py --steps=library --base-directory $(build.sourcesDirectory)/multissl --openssl $(OPENSSL) --system Linux
   displayName: 'python multissltests.py'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 
 - script: ./configure --with-pydebug
   displayName: 'Configure CPython (debug)'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: make -s -j4
   displayName: 'Build CPython'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: make pythoninfo
   displayName: 'Display build info'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 # Run patchcheck and fail if anything is discovered
 - script: ./python Tools/scripts/patchcheck.py --travis true
   displayName: 'Run patchcheck.py'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: xvfb-run make buildbottest TESTOPTS="-j4 -uall,-cpu"
   displayName: 'Tests'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))

.vsts/macos-pr.yml

@@ -24,14 +24,32 @@ steps:
   clean: true
   fetchDepth: 5
 
+- script: |
+   git fetch -q origin $(system.pullRequest.targetBranch)
+   changes = $(git diff --name-only HEAD $(git merge-base HEAD FETCH_HEAD))
+   echo "Files changed:"
+   echo "$changes"
+   if ! echo "$changes" | grep -qvE '(\.rst$)|(^Doc)|(^Misc)'
+   then
+     echo "Only docs were updated, stopping build process."
+     echo "##vso[task.setvariable variable=DocOnly]true"
+     exit
+   fi
+  displayName: Detect doc-only changes
+  condition: and(succeeded(), variables['system.pullRequest.targetBranch'])
+
 - script: ./configure --with-pydebug --with-openssl=/usr/local/opt/openssl --prefix=/opt/python-vsts
   displayName: 'Configure CPython (debug)'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: make -s -j4
   displayName: 'Build CPython'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: make pythoninfo
   displayName: 'Display build info'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: make buildbottest TESTOPTS="-j4 -uall,-cpu"
   displayName: 'Tests'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))

.vsts/windows-pr.yml

@@ -37,13 +37,25 @@ steps:
   clean: true
   fetchDepth: 5
 
+- powershell: |
+   git fetch -q origin $(System.PullRequest.TargetBranch)
+   if (-not (git diff --name-only HEAD (git merge-base HEAD FETCH_HEAD) | sls -NotMatch '(\.rst$)|(^Doc)|(^Misc)')) {
+      Write-Host 'Only docs were updated. Skipping build'
+      Write-Host '##vso[task.setvariable variable=DocOnly]true'
+   }
+  displayName: Detect doc-only changes
+  condition: and(succeeded(), variables['System.PullRequest.TargetBranch'])
+
 - script: PCbuild\build.bat -e $(buildOpt)
   displayName: 'Build CPython'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: python.bat -m test.pythoninfo
   displayName: 'Display build info'
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
 
 - script: PCbuild\rt.bat -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
   displayName: 'Tests'
   env:
     PREFIX: $(Py_OutDir)\$(outDirSuffix)
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))

Doc/README.rst

@@ -33,7 +33,7 @@ To get started on UNIX, you can create a virtual environment with the command ::
   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;
+the virtual environment was created in the ``venv`` directory (the default;
 configurable with the VENVDIR variable), you can run the following command to
 build the HTML output files::
 

Doc/faq/design.rst

@@ -215,24 +215,25 @@ objects using the ``for`` statement.  For example, :term:`file objects
 Why does Python use methods for some functionality (e.g. list.index()) but functions for other (e.g. len(list))?
 ----------------------------------------------------------------------------------------------------------------
 
-The major reason is history. Functions were used for those operations that were
-generic for a group of types and which were intended to work even for objects
-that didn't have methods at all (e.g. tuples).  It is also convenient to have a
-function that can readily be applied to an amorphous collection of objects when
-you use the functional features of Python (``map()``, ``zip()`` et al).
-
-In fact, implementing ``len()``, ``max()``, ``min()`` as a built-in function is
-actually less code than implementing them as methods for each type.  One can
-quibble about individual cases but it's a part of Python, and it's too late to
-make such fundamental changes now. The functions have to remain to avoid massive
-code breakage.
-
-.. XXX talk about protocols?
-
-.. note::
-
-   For string operations, Python has moved from external functions (the
-   ``string`` module) to methods.  However, ``len()`` is still a function.
+As Guido said:
+
+    (a) For some operations, prefix notation just reads better than
+    postfix -- prefix (and infix!) operations have a long tradition in
+    mathematics which likes notations where the visuals help the
+    mathematician thinking about a problem. Compare the easy with which we
+    rewrite a formula like x*(a+b) into x*a + x*b to the clumsiness of
+    doing the same thing using a raw OO notation.
+
+    (b) When I read code that says len(x) I *know* that it is asking for
+    the length of something. This tells me two things: the result is an
+    integer, and the argument is some kind of container. To the contrary,
+    when I read x.len(), I have to already know that x is some kind of
+    container implementing an interface or inheriting from a class that
+    has a standard len(). Witness the confusion we occasionally have when
+    a class that is not implementing a mapping has a get() or keys()
+    method, or something that isn't a file has a write() method.
+
+    -- https://mail.python.org/pipermail/python-3000/2006-November/004643.html
 
 
 Why is join() a string method instead of a list or tuple method?

Doc/glossary.rst

@@ -123,10 +123,10 @@ Glossary
       :meth:`__aiter__` method.  Introduced by :pep:`492`.
 
    asynchronous iterator
-      An object that implements :meth:`__aiter__` and :meth:`__anext__`
+      An object that implements the :meth:`__aiter__` and :meth:`__anext__`
       methods.  ``__anext__`` must return an :term:`awaitable` object.
-      :keyword:`async for` resolves awaitable returned from asynchronous
-      iterator's :meth:`__anext__` method until it raises
+      :keyword:`async for` resolves the awaitables returned by an asynchronous
+      iterator's :meth:`__anext__` method until it raises a
       :exc:`StopAsyncIteration` exception.  Introduced by :pep:`492`.
 
    attribute