Merge branch 'master' into selectors-refactoring

.github/CONTRIBUTING.rst

@@ -31,6 +31,9 @@ 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>`_.
+One key point is to keep comments on GitHub to only those related to the reviewing
+the code in the pull request. All other discussions -- e.g. about the issue being
+fixed -- should happen on bugs.python.org.
 
 If you are making a code contribution or large documentation contribution,
 please feel free to add yourself to the ``Misc/ACKS`` file alphabetically.

.codecov.yml → .github/codecov.yml

@@ -12,18 +12,12 @@ ignore:
   - "Grammar/*"
 coverage:
   precision: 2
-  range:
-  - 70.0
-  - 100.0
+  range: 70...90
   round: down
   status:
     changes: off
     project: off
-    patch:
-      default:
-        target: 100%
-        only_pulls: true
-        threshold: 0.05
+    patch: off
 parsers:
   gcov:
     branch_detection:

.mention-bot

@@ -7,5 +7,14 @@
     "Doc/whatsnew/*.rst"
   ],
   "userBlacklist": ["gvanrossum", "skrah", "haypo"],
-  "userBlacklistForPR": ["benjaminp", "skrah", "berkerpeksag"]
+  "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

@@ -32,14 +32,17 @@ matrix:
   include:
     - os: linux
       language: python
+      # Build the docs against a stable version of Python so code bugs don't hold up doc-related PRs.
       python: 3.6
       env:
         - TESTING=docs
       before_script:
         - cd Doc
-        - make venv
+        # 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
       script:
-        - make check suspicious html PYTHON="./venv/bin/python" SPHINXBUILD="./venv/bin/python -m sphinx" SPHINXOPTS="-q -W"
+        - make check suspicious html SPHINXOPTS="-q -W"
     - os: linux
       language: c
       compiler: gcc

Doc/c-api/exceptions.rst

@@ -295,7 +295,7 @@ an error value).
    :c:data:`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`;
    the default warning category is :c:data:`PyExc_RuntimeWarning`. The standard
    Python warning categories are available as global variables whose names are
-   enumerated at :ref:`standarwarningcategories`.
+   enumerated at :ref:`standardwarningcategories`.
 
    For information about warning control, see the documentation for the
    :mod:`warnings` module and the :option:`-W` option in the command line
@@ -958,7 +958,7 @@ Notes:
    Only defined on Windows; protect code that uses this by testing that the
    preprocessor macro ``MS_WINDOWS`` is defined.
 
-.. _standarwarningcategories:
+.. _standardwarningcategories:
 
 Standard Warning Categories
 ===========================
@@ -971,7 +971,7 @@ the variables:
 .. index::
    single: PyExc_Warning
    single: PyExc_BytesWarning
-   single: PyExc_DepricationWarning
+   single: PyExc_DeprecationWarning
    single: PyExc_FutureWarning
    single: PyExc_ImportWarning
    single: PyExc_PendingDeprecationWarning
@@ -994,7 +994,7 @@ the variables:
 +------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ImportWarning`            | :exc:`ImportWarning`            |          |
 +------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_PendingDepricationWarning`| :exc:`PendingDeprecationWarning`|          |
+| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`|          |
 +------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ResourceWarning`          | :exc:`ResourceWarning`          |          |
 +------------------------------------------+---------------------------------+----------+

Doc/c-api/slice.rst

@@ -75,7 +75,7 @@ Slice Objects
    Extract the start, stop and step data members from a slice object as
    C integers.  Silently reduce values larger than ``PY_SSIZE_T_MAX`` to
    ``PY_SSIZE_T_MAX``, silently boost the start and stop values less than
-   ``-PY_SSIZE_T_MAX-1`` to ``-PY_SSIZE_T_MAX-1``, and silently boost the step
+   ``PY_SSIZE_T_MIN`` to ``PY_SSIZE_T_MIN``, and silently boost the step
    values less than ``-PY_SSIZE_T_MAX`` to ``-PY_SSIZE_T_MAX``.
 
    Return ``-1`` on error, ``0`` on success.

Doc/extending/newtypes.rst

@@ -124,7 +124,7 @@ our objects and in some error messages, for example::
 
    >>> "" + noddy.new_noddy()
    Traceback (most recent call last):
-     File "<stdin>", line 1, in ?
+     File "<stdin>", line 1, in <module>
    TypeError: cannot add type "noddy.Noddy" to string
 
 Note that the name is a dotted name that includes both the module name and the

Doc/howto/functional.rst

@@ -210,7 +210,7 @@ You can experiment with the iteration interface manually:
     3
     >>> next(it)
     Traceback (most recent call last):
-      File "<stdin>", line 1, in ?
+      File "<stdin>", line 1, in <module>
     StopIteration
     >>>
 
@@ -474,7 +474,7 @@ Here's a sample usage of the ``generate_ints()`` generator:
     2
     >>> next(gen)
     Traceback (most recent call last):
-      File "stdin", line 1, in ?
+      File "stdin", line 1, in <module>
       File "stdin", line 2, in generate_ints
     StopIteration
 
@@ -577,7 +577,7 @@ And here's an example of changing the counter:
     9
     >>> next(it)  #doctest: +SKIP
     Traceback (most recent call last):
-      File "t.py", line 15, in ?
+      File "t.py", line 15, in <module>
         it.next()
     StopIteration
 

Doc/howto/logging-cookbook.rst

@@ -1683,7 +1683,7 @@ Implementing structured logging
 -------------------------------
 
 Although most logging messages are intended for reading by humans, and thus not
-readily machine-parseable, there might be cirumstances where you want to output
+readily machine-parseable, there might be circumstances where you want to output
 messages in a structured format which *is* capable of being parsed by a program
 (without needing complex regular expressions to parse the log message). This is
 straightforward to achieve using the logging package. There are a number of

Doc/howto/urllib2.rst

@@ -34,8 +34,8 @@ handling common situations - like basic authentication, cookies, proxies and so
 on. These are provided by objects called handlers and openers.
 
 urllib.request supports fetching URLs for many "URL schemes" (identified by the string
-before the ":" in URL - for example "ftp" is the URL scheme of
-"ftp://python.org/") using their associated network protocols (e.g. FTP, HTTP).
+before the ``":"`` in URL - for example ``"ftp"`` is the URL scheme of
+``"ftp://python.org/"``) using their associated network protocols (e.g. FTP, HTTP).
 This tutorial focuses on the most common case, HTTP.
 
 For straightforward situations *urlopen* is very easy to use. But as soon as you
@@ -511,10 +511,10 @@ than the URL you pass to .add_password() will also match. ::
 
 ``top_level_url`` is in fact *either* a full URL (including the 'http:' scheme
 component and the hostname and optionally the port number)
-e.g. "http://example.com/" *or* an "authority" (i.e. the hostname,
-optionally including the port number) e.g. "example.com" or "example.com:8080"
+e.g. ``"http://example.com/"`` *or* an "authority" (i.e. the hostname,
+optionally including the port number) e.g. ``"example.com"`` or ``"example.com:8080"``
 (the latter example includes a port number).  The authority, if present, must
-NOT contain the "userinfo" component - for example "joe:password@example.com" is
+NOT contain the "userinfo" component - for example ``"joe:password@example.com"`` is
 not correct.
 
 

Doc/library/binascii.rst

@@ -40,11 +40,14 @@ The :mod:`binascii` module defines the following functions:
    data may be followed by whitespace.
 
 
-.. function:: b2a_uu(data)
+.. function:: b2a_uu(data, *, backtick=False)
 
    Convert binary data to a line of ASCII characters, the return value is the
    converted line, including a newline char. The length of *data* should be at most
-   45.
+   45. If *backtick* is true, zeros are represented by ``'`'`` instead of spaces.
+
+   .. versionchanged:: 3.7
+      Added the *backtick* parameter.
 
 
 .. function:: a2b_base64(string)
@@ -53,7 +56,7 @@ The :mod:`binascii` module defines the following functions:
    than one line may be passed at a time.
 
 
-.. function:: b2a_base64(data, \*, newline=True)
+.. function:: b2a_base64(data, *, newline=True)
 
    Convert binary data to a line of ASCII characters in base64 coding. The return
    value is the converted line, including a newline char if *newline* is

Doc/library/cgi.rst

@@ -294,19 +294,20 @@ algorithms implemented in this module in other circumstances.
    This function is deprecated in this module. Use :func:`urllib.parse.parse_qsl`
    instead. It is maintained here only for backward compatibility.
 
-.. function:: parse_multipart(fp, pdict)
+.. function:: parse_multipart(fp, pdict, encoding="utf-8")
 
    Parse input of type :mimetype:`multipart/form-data` (for  file uploads).
-   Arguments are *fp* for the input file and *pdict* for a dictionary containing
-   other parameters in the :mailheader:`Content-Type` header.
+   Arguments are *fp* for the input file, *pdict* for a dictionary containing
+   other parameters in the :mailheader:`Content-Type` header, and *encoding*,
+   the request encoding.
 
-   Returns a dictionary just like :func:`urllib.parse.parse_qs` keys are the field names, each
-   value is a list of values for that field.  This is easy to use but not much good
-   if you are expecting megabytes to be uploaded --- in that case, use the
-   :class:`FieldStorage` class instead which is much more flexible.
+   Returns a dictionary just like :func:`urllib.parse.parse_qs`: keys are the
+   field names, each value is a list of values for that field. For non-file
+   fields, the value is a list of strings.
 
-   Note that this does not parse nested multipart parts --- use
-   :class:`FieldStorage` for that.
+   This is easy to use but not much good if you are expecting megabytes to be
+   uploaded --- in that case, use the :class:`FieldStorage` class instead
+   which is much more flexible.
 
 
 .. function:: parse_header(string)

Doc/library/cgitb.rst

@@ -54,6 +54,24 @@ analysis.
    value forces plain text output.  The default value is ``"html"``.
 
 
+.. function:: text(info, context=5)
+
+   This function handles the exception described by *info* (a 3-tuple containing
+   the result of :func:`sys.exc_info`), formatting its traceback as text and
+   returning the result as a string. The optional argument *context* is the
+   number of lines of context to display around the current line of source code
+   in the traceback; this defaults to ``5``.
+
+
+.. function:: html(info, context=5)
+
+   This function handles the exception described by *info* (a 3-tuple containing
+   the result of :func:`sys.exc_info`), formatting its traceback as HTML and
+   returning the result as a string. The optional argument *context* is the
+   number of lines of context to display around the current line of source code
+   in the traceback; this defaults to ``5``.
+
+
 .. function:: handler(info=None)
 
    This function handles an exception using the default settings (that is, show a

Doc/library/cmath.rst

@@ -47,7 +47,7 @@ rectangular coordinates to polar coordinates and back.
 
    Return the phase of *x* (also known as the *argument* of *x*), as a
    float.  ``phase(x)`` is equivalent to ``math.atan2(x.imag,
-   x.real)``.  The result lies in the range [-π, π], and the branch
+   x.real)``.  The result lies in the range [-\ *π*, *π*], and the branch
    cut for this operation lies along the negative real axis,
    continuous from above.  On systems with support for signed zeros
    (which includes most systems in current use), this means that the
@@ -86,7 +86,8 @@ Power and logarithmic functions
 
 .. function:: exp(x)
 
-   Return the exponential value ``e**x``.
+   Return *e* raised to the power *x*, where *e* is the base of natural
+   logarithms.
 
 
 .. function:: log(x[, base])
@@ -243,7 +244,6 @@ Classification functions
 Constants
 ---------
 
-
 .. data:: pi
 
    The mathematical constant *π*, as a float.
@@ -253,32 +253,37 @@ Constants
 
    The mathematical constant *e*, as a float.
 
+
 .. data:: tau
 
    The mathematical constant *τ*, as a float.
 
    .. versionadded:: 3.6
 
+
 .. data:: inf
 
    Floating-point positive infinity. Equivalent to ``float('inf')``.
 
    .. versionadded:: 3.6
 
+
 .. data:: infj
 
    Complex number with zero real part and positive infinity imaginary
    part. Equivalent to ``complex(0.0, float('inf'))``.
 
    .. versionadded:: 3.6
 
+
 .. data:: nan
 
    A floating-point "not a number" (NaN) value.  Equivalent to
    ``float('nan')``.
 
    .. versionadded:: 3.6
 
+
 .. data:: nanj
 
    Complex number with zero real part and NaN imaginary part. Equivalent to

Doc/library/cmd.rst

@@ -266,10 +266,10 @@ immediate playback::
             'Draw circle with given radius an options extent and steps:  CIRCLE 50'
             circle(*parse(arg))
         def do_position(self, arg):
-            'Print the current turle position:  POSITION'
+            'Print the current turtle position:  POSITION'
             print('Current position is %d %d\n' % position())
         def do_heading(self, arg):
-            'Print the current turle heading in degrees:  HEADING'
+            'Print the current turtle heading in degrees:  HEADING'
             print('Current heading is %d\n' % (heading(),))
         def do_color(self, arg):
             'Set the color:  COLOR BLUE'