Merge branch 'master' of git://github.com/python/cpython into pymain-run-module-sigint

Author: graingert

Doc/Makefile

@@ -143,7 +143,7 @@ clean:
 venv:
 	$(PYTHON) -m venv $(VENVDIR)
 	$(VENVDIR)/bin/python3 -m pip install -U pip setuptools
-	$(VENVDIR)/bin/python3 -m pip install -U Sphinx==2.3.1 blurb python-docs-theme
+	$(VENVDIR)/bin/python3 -m pip install -U Sphinx==3.2.1 blurb python-docs-theme
 	@echo "The venv has been created in the $(VENVDIR) directory"
 
 dist:

Doc/c-api/type.rst

@@ -117,6 +117,13 @@ Type Objects
    If no module is associated with the given type, sets :py:class:`TypeError`
    and returns ``NULL``.
 
+   This function is usually used to get the module in which a method is defined.
+   Note that in such a method, ``PyType_GetModule(Py_TYPE(self))``
+   may not return the intended result.
+   ``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
+   are not necessarily defined in the same module as their superclass.
+   See :c:type:`PyCMethod` to get the class that defines the method.
+
    .. versionadded:: 3.9
 
 .. c:function:: void* PyType_GetModuleState(PyTypeObject *type)
@@ -151,9 +158,12 @@ The following functions and structs are used to create
    If *bases* is ``NULL``, the *Py_tp_base* slot is used instead.
    If that also is ``NULL``, the new type derives from :class:`object`.
 
-   The *module* must be a module object or ``NULL``.
+   The *module* argument can be used to record the module in which the new
+   class is defined. It must be a module object or ``NULL``.
    If not ``NULL``, the module is associated with the new type and can later be
    retreived with :c:func:`PyType_GetModule`.
+   The associated module is not inherited by subclasses; it must be specified
+   for each class individually.
 
    This function calls :c:func:`PyType_Ready` on the new type.
 
@@ -215,7 +225,8 @@ The following functions and structs are used to create
       * ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add`
       * ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length`
 
-      The following fields cannot be set using :c:type:`PyType_Spec` and :c:type:`PyType_Slot`:
+      The following fields cannot be set at all using :c:type:`PyType_Spec` and
+      :c:type:`PyType_Slot`:
 
       * :c:member:`~PyTypeObject.tp_dict`
       * :c:member:`~PyTypeObject.tp_mro`
@@ -229,13 +240,21 @@ The following functions and structs are used to create
         (see :ref:`PyMemberDef <pymemberdef-offsets>`)
       * :c:member:`~PyTypeObject.tp_vectorcall_offset`
         (see :ref:`PyMemberDef <pymemberdef-offsets>`)
+
+      The following fields cannot be set using :c:type:`PyType_Spec` and
+      :c:type:`PyType_Slot` under the limited API:
+
       * :c:member:`~PyBufferProcs.bf_getbuffer`
       * :c:member:`~PyBufferProcs.bf_releasebuffer`
 
       Setting :c:data:`Py_tp_bases` may be problematic on some platforms.
       To avoid issues, use the *bases* argument of
       :py:func:`PyType_FromSpecWithBases` instead.
 
+     .. versionchanged:: 3.9
+
+        Slots in :c:type:`PyBufferProcs` in may be set in the unlimited API.
+
    .. c:member:: void *PyType_Slot.pfunc
 
       The desired value of the slot. In most cases, this is a pointer

Doc/data/refcounts.dat

@@ -2283,6 +2283,11 @@ PyType_CheckExact:PyObject*:o:0:
 PyType_FromSpec:PyObject*::+1:
 PyType_FromSpec:PyType_Spec*:spec::
 
+PyType_FromModuleAndSpec:PyObject*::+1:
+PyType_FromModuleAndSpec:PyObject*:module:+1:
+PyType_FromModuleAndSpec:PyType_Spec*:spec::
+PyType_FromModuleAndSpec:PyObject*:bases:0:
+
 PyType_FromSpecWithBases:PyObject*::+1:
 PyType_FromSpecWithBases:PyType_Spec*:spec::
 PyType_FromSpecWithBases:PyObject*:bases:0:

Doc/faq/design.rst

@@ -573,8 +573,7 @@ whether an instance or a class implements a particular ABC.  The
 :class:`~collections.abc.MutableMapping`.
 
 For Python, many of the advantages of interface specifications can be obtained
-by an appropriate test discipline for components.  There is also a tool,
-PyChecker, which can be used to find problems due to subclassing.
+by an appropriate test discipline for components.
 
 A good test suite for a module can both provide a regression test and serve as a
 module interface specification and a set of examples.  Many Python modules can

Doc/faq/programming.rst

@@ -35,12 +35,6 @@ for Windows Extensions <https://sourceforge.net/projects/pywin32/>`__ project an
 as a part of the ActivePython distribution (see
 https://www.activestate.com/activepython\ ).
 
-`Boa Constructor <http://boa-constructor.sourceforge.net/>`_ is an IDE and GUI
-builder that uses wxWidgets.  It offers visual frame creation and manipulation,
-an object inspector, many views on the source like object browsers, inheritance
-hierarchies, doc string generated html documentation, an advanced debugger,
-integrated help, and Zope support.
-
 `Eric <http://eric-ide.python-projects.org/>`_ is an IDE built on PyQt
 and the Scintilla editing component.
 
@@ -57,22 +51,14 @@ They include:
 * PyCharm (https://www.jetbrains.com/pycharm/)
 
 
-Is there a tool to help find bugs or perform static analysis?
+Are there tools to help find bugs or perform static analysis?
 -------------------------------------------------------------
 
 Yes.
 
-PyChecker is a static analysis tool that finds bugs in Python source code and
-warns about code complexity and style.  You can get PyChecker from
-http://pychecker.sourceforge.net/.
-
-`Pylint <https://www.pylint.org/>`_ is another tool that checks
-if a module satisfies a coding standard, and also makes it possible to write
-plug-ins to add a custom feature.  In addition to the bug checking that
-PyChecker performs, Pylint offers some additional features such as checking line
-length, whether variable names are well-formed according to your coding
-standard, whether declared interfaces are fully implemented, and more.
-https://docs.pylint.org/ provides a full list of Pylint's features.
+`Pylint <https://www.pylint.org/>`_ and
+`Pyflakes <https://github.com/PyCQA/pyflakes>`_ do basic checking that will
+help you catch bugs sooner.
 
 Static type checkers such as `Mypy <http://mypy-lang.org/>`_,
 `Pyre <https://pyre-check.org/>`_, and
@@ -1155,7 +1141,7 @@ How do you remove duplicates from a list?
 
 See the Python Cookbook for a long discussion of many ways to do this:
 
-   https://code.activestate.com/recipes/52560/
+   https://github.com/ActiveState/code/tree/master/recipes/Python/52560_Remove_duplicates/recipe-52560.py
 
 If you don't mind reordering the list, sort it and then scan from the end of the
 list, deleting duplicates as you go::

Doc/howto/logging.rst

@@ -1078,20 +1078,22 @@ need more precise control over what logging information is collected. Here's a
 list of things you can do to avoid processing during logging which you don't
 need:
 
-+-----------------------------------------------+----------------------------------------+
-| What you don't want to collect                | How to avoid collecting it             |
-+===============================================+========================================+
-| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``.  |
-|                                               | This avoids calling                    |
-|                                               | :func:`sys._getframe`, which may help  |
-|                                               | to speed up your code in environments  |
-|                                               | like PyPy (which can't speed up code   |
-|                                               | that uses :func:`sys._getframe`).      |
-+-----------------------------------------------+----------------------------------------+
-| Threading information.                        | Set ``logging.logThreads`` to ``0``.   |
-+-----------------------------------------------+----------------------------------------+
-| Process information.                          | Set ``logging.logProcesses`` to ``0``. |
-+-----------------------------------------------+----------------------------------------+
++-----------------------------------------------------+---------------------------------------------------+
+| What you don't want to collect                      | How to avoid collecting it                        |
++=====================================================+===================================================+
+| Information about where calls were made from.       | Set ``logging._srcfile`` to ``None``.             |
+|                                                     | This avoids calling :func:`sys._getframe`, which  |
+|                                                     | may help to speed up your code in environments    |
+|                                                     | like PyPy (which can't speed up code that uses    |
+|                                                     | :func:`sys._getframe`).                           |
++-----------------------------------------------------+---------------------------------------------------+
+| Threading information.                              | Set ``logging.logThreads`` to ``False``.          |
++-----------------------------------------------------+---------------------------------------------------+
+| Current process ID (:func:`os.getpid`)              | Set ``logging.logProcesses`` to ``False``.        |
++-----------------------------------------------------+---------------------------------------------------+
+| Current process name when using ``multiprocessing`` | Set ``logging.logMultiprocessing`` to ``False``.  |
+| to manage multiple processes.                       |                                                   |
++-----------------------------------------------------+---------------------------------------------------+
 
 Also note that the core logging module only includes the basic handlers. If
 you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't

Doc/howto/urllib2.rst

@@ -601,5 +601,5 @@ This document was reviewed and revised by John Lee.
        scripts with a localhost server, I have to prevent urllib from using
        the proxy.
 .. [#] urllib opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe
-       <https://code.activestate.com/recipes/456195/>`_.
+       <https://github.com/ActiveState/code/tree/master/recipes/Python/456195_urrlib2_opener_SSL_proxy_CONNECT/recipe-456195.py>`_.
 

Doc/library/argparse.rst

@@ -1162,8 +1162,8 @@ keyword argument to :meth:`~ArgumentParser.add_argument`::
    >>> parser.parse_args(['--foo', 'BAR'])
    Namespace(foo='BAR')
    >>> parser.parse_args([])
-   usage: argparse.py [-h] [--foo FOO]
-   argparse.py: error: option --foo is required
+   usage: [-h] --foo FOO
+   : error: the following arguments are required: --foo
 
 As the example shows, if an option is marked as ``required``,
 :meth:`~ArgumentParser.parse_args` will report an error if that option is not

Doc/library/asyncio-dev.rst

@@ -107,6 +107,16 @@ The :meth:`loop.run_in_executor` method can be used with a
 blocking code in a different OS thread without blocking the OS thread
 that the event loop runs in.
 
+There is currently no way to schedule coroutines or callbacks directly
+from a different process (such as one started with
+:mod:`multiprocessing`). The :ref:`Event Loop Methods <asyncio-event-loop>`
+section lists APIs that can read from pipes and watch file descriptors
+without blocking the event loop. In addition, asyncio's
+:ref:`Subprocess <asyncio-subprocess>` APIs provide a way to start a
+process and communicate with it from the event loop. Lastly, the
+aforementioned :meth:`loop.run_in_executor` method can also be used
+with a :class:`concurrent.futures.ProcessPoolExecutor` to execute
+code in a different process.
 
 .. _asyncio-handle-blocking:
 

Doc/library/bisect.rst

@@ -60,7 +60,7 @@ The following functions are provided:
 .. seealso::
 
    `SortedCollection recipe
-   <https://code.activestate.com/recipes/577197-sortedcollection/>`_ that uses
+   <https://github.com/ActiveState/code/tree/master/recipes/Python/577197_SortedCollection/recipe-577197.py>`_ that uses
    bisect to build a full-featured collection class with straight-forward search
    methods and support for a key-function.  The keys are precomputed to save
    unnecessary calls to the key function during searches.

Doc/library/collections.abc.rst

@@ -308,7 +308,7 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
 
 .. seealso::
 
-   * `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an
+   * `OrderedSet recipe <https://github.com/ActiveState/code/tree/master/recipes/Python/576694_OrderedSet/recipe-576694.py>`_ for an
      example built on :class:`MutableSet`.
 
    * For more about ABCs, see the :mod:`abc` module and :pep:`3119`.

Doc/library/collections.rst

@@ -135,12 +135,12 @@ The class can be used to simulate nested scopes and is useful in templating.
       :attr:`~collections.ChainMap.parents` property.
 
     * The `Nested Contexts recipe
-      <https://code.activestate.com/recipes/577434/>`_ has options to control
+      <https://github.com/ActiveState/code/tree/master/recipes/Python/577434_Nested_contexts__chamapping/recipe-577434.py>`_ has options to control
       whether writes and other mutations apply only to the first mapping or to
       any mapping in the chain.
 
     * A `greatly simplified read-only version of Chainmap
-      <https://code.activestate.com/recipes/305268/>`_.
+      <https://github.com/ActiveState/code/tree/master/recipes/Python/305268_Chained_map_lookups/recipe-305268.py>`_.
 
 
 :class:`ChainMap` Examples and Recipes

Doc/library/curses.rst

@@ -717,7 +717,7 @@ the following methods and attributes:
             window.addch(y, x, ch[, attr])
 
    Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any
-   character previously painter at that location.  By default, the character
+   character previously painted at that location.  By default, the character
    position and attributes are the current settings for the window object.
 
    .. note::

Doc/library/difflib.rst

@@ -18,8 +18,8 @@
 --------------
 
 This module provides classes and functions for comparing sequences. It
-can be used for example, for comparing files, and can produce difference
-information in various formats, including HTML and context and unified
+can be used for example, for comparing files, and can produce information
+about file differences in various formats, including HTML and context and unified
 diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
 
 
@@ -633,7 +633,7 @@ If you want to know how to change the first sequence into the second, use
      work.
 
    * `Simple version control recipe
-     <https://code.activestate.com/recipes/576729/>`_ for a small application
+     <https://github.com/ActiveState/code/tree/master/recipes/Python/576729_Simple_Version_Control/recipe-576729.py>`_ for a small application
      built with :class:`SequenceMatcher`.
 
 

Doc/library/enum.rst

@@ -19,6 +19,12 @@ An enumeration is a set of symbolic names (members) bound to unique,
 constant values.  Within an enumeration, the members can be compared
 by identity, and the enumeration itself can be iterated over.
 
+.. note:: Case of Enum Members
+
+    Because Enums are used to represent constants we recommend using
+    UPPER_CASE names for enum members, and will be using that style
+    in our examples.
+
 
 Module Contents
 ---------------
@@ -650,6 +656,13 @@ be combined with them::
     >>> Perm.X | 8
     <Perm.8|X: 9>
 
+:class:`IntFlag` members can also be iterated over::
+
+    >>> list(RW)
+    [<Perm.R: 4>, <Perm.W: 2>]
+
+.. versionadded:: 3.10
+
 
 Flag
 ^^^^
@@ -703,6 +716,14 @@ value::
     >>> bool(Color.BLACK)
     False
 
+:class:`Flag` members can also be iterated over::
+
+    >>> purple = Color.RED | Color.BLUE
+    >>> list(purple)
+    [<Color.BLUE: 2>, <Color.RED: 1>]
+
+.. versionadded:: 3.10
+
 .. note::
 
     For the majority of new code, :class:`Enum` and :class:`Flag` are strongly

Doc/library/glob.rst

@@ -43,7 +43,9 @@ For example, ``'[?]'`` matches the character ``'?'``.
    (like :file:`/usr/src/Python-1.5/Makefile`) or relative (like
    :file:`../../Tools/\*/\*.gif`), and can contain shell-style wildcards. Broken
    symlinks are included in the results (as in the shell). Whether or not the
-   results are sorted depends on the file system.
+   results are sorted depends on the file system.  If a file that satisfies
+   conditions is removed or added during the call of this function, whether
+   a path name for that file be included is unspecified.
 
    If *root_dir* is not ``None``, it should be a :term:`path-like object`
    specifying the root directory for searching.  It has the same effect on

Doc/library/graphlib.rst

@@ -121,7 +121,7 @@
           if ts.is_active():
               ...
 
-      if possible to simply do::
+      it is possible to simply do::
 
           if ts:
               ...

Doc/library/idle.rst

@@ -491,7 +491,7 @@ in the settings dialog.  (To prevent auto popups, set the delay to a
 large number of milliseconds, such as 100000000.) For imported module
 names or class or function attributes, type '.'.
 For filenames in the root directory, type :data:`os.sep` or
-data:`os.altsep` immediately after an opening quote.  (On Windows,
+:data:`os.altsep` immediately after an opening quote.  (On Windows,
 one can specify a drive first.)  Move into subdirectories by typing a
 directory name and a separator.
 

Doc/library/imaplib.rst

@@ -143,7 +143,7 @@ The following utility functions are defined:
 
 .. function:: Int2AP(num)
 
-   Converts an integer into a string representation using characters from the set
+   Converts an integer into a bytes representation using characters from the set
    [``A`` .. ``P``].
 
 
@@ -197,7 +197,7 @@ you want to avoid having an argument string quoted (eg: the *flags* argument to
 
 Each command returns a tuple: ``(type, [data, ...])`` where *type* is usually
 ``'OK'`` or ``'NO'``, and *data* is either the text from the command response,
-or mandated results from the command. Each *data* is either a string, or a
+or mandated results from the command. Each *data* is either a ``bytes``, or a
 tuple. If a tuple, then the first part is the header of the response, and the
 second part contains the data (ie: 'literal' value).
 

Doc/library/locale.rst

@@ -508,7 +508,7 @@ Background, details, hints, tips and caveats
 --------------------------------------------
 
 The C standard defines the locale as a program-wide property that may be
-relatively expensive to change.  On top of that, some implementation are broken
+relatively expensive to change.  On top of that, some implementations are broken
 in such a way that frequent locale changes may cause core dumps.  This makes the
 locale somewhat painful to use correctly.