Merge branch 'main' into copy-free-vars-in-bytecode

Author: markshannon

Doc/library/importlib.rst

@@ -383,11 +383,11 @@ ABC hierarchy::
     See :pep:`302` for the exact definition for a loader.
 
     Loaders that wish to support resource reading should implement a
-    ``get_resource_reader(fullname)`` method as specified by
+    :meth:`get_resource_reader` method as specified by
     :class:`importlib.abc.ResourceReader`.
 
     .. versionchanged:: 3.7
-       Introduced the optional ``get_resource_reader()`` method.
+       Introduced the optional :meth:`get_resource_reader` method.
 
     .. method:: create_module(spec)
 
@@ -405,80 +405,82 @@ ABC hierarchy::
 
        An abstract method that executes the module in its own namespace
        when a module is imported or reloaded.  The module should already
-       be initialized when ``exec_module()`` is called. When this method exists,
-       :meth:`~importlib.abc.Loader.create_module` must be defined.
+       be initialized when :meth:`exec_module` is called.  When this method exists,
+       :meth:`create_module` must be defined.
 
        .. versionadded:: 3.4
 
        .. versionchanged:: 3.6
-          :meth:`~importlib.abc.Loader.create_module` must also be defined.
+          :meth:`create_module` must also be defined.
 
     .. method:: load_module(fullname)
 
-        A legacy method for loading a module. If the module cannot be
+        A legacy method for loading a module.  If the module cannot be
         loaded, :exc:`ImportError` is raised, otherwise the loaded module is
         returned.
 
         If the requested module already exists in :data:`sys.modules`, that
         module should be used and reloaded.
         Otherwise the loader should create a new module and insert it into
         :data:`sys.modules` before any loading begins, to prevent recursion
-        from the import. If the loader inserted a module and the load fails, it
+        from the import.  If the loader inserted a module and the load fails, it
         must be removed by the loader from :data:`sys.modules`; modules already
         in :data:`sys.modules` before the loader began execution should be left
         alone (see :func:`importlib.util.module_for_loader`).
 
-        The loader should set several attributes on the module.
-        (Note that some of these attributes can change when a module is
+        The loader should set several attributes on the module
+        (note that some of these attributes can change when a module is
         reloaded):
 
         - :attr:`__name__`
-            The name of the module.
+            The module's fully-qualified name.
+            It is ``'__main__'`` for an executed module.
 
         - :attr:`__file__`
-            The path to where the module data is stored (not set for built-in
-            modules).
+            The location the :term:`loader` used to load the module.
+            For example, for modules loaded from a .py file this is the filename.
+            It is not set on all modules (e.g. built-in modules).
 
         - :attr:`__cached__`
-            The path to where a compiled version of the module is/should be
-            stored (not set when the attribute would be inappropriate).
+            The filename of a compiled version of the module's code.
+            It is not set on all modules (e.g. built-in modules).
 
         - :attr:`__path__`
-            A list of strings specifying the search path within a
-            package. This attribute is not set on modules.
+            The list of locations where the package's submodules will be found.
+            Most of the time this is a single directory.
+            The import system passes this attribute to ``__import__()`` and to finders
+            in the same way as :attr:`sys.path` but just for the package.
+            It is not set on non-package modules so it can be used
+            as an indicator that the module is a package.
 
         - :attr:`__package__`
-            The fully-qualified name of the package under which the module was
-            loaded as a submodule (or the empty string for top-level modules).
-            For packages, it is the same as :attr:`__name__`.  The
-            :func:`importlib.util.module_for_loader` decorator can handle the
-            details for :attr:`__package__`.
+            The fully-qualified name of the package the module is in (or the
+            empty string for a top-level module).
+            If the module is a package then this is the same as :attr:`__name__`.
 
         - :attr:`__loader__`
-            The loader used to load the module. The
-            :func:`importlib.util.module_for_loader` decorator can handle the
-            details for :attr:`__package__`.
+            The :term:`loader` used to load the module.
 
         When :meth:`exec_module` is available then backwards-compatible
         functionality is provided.
 
         .. versionchanged:: 3.4
            Raise :exc:`ImportError` when called instead of
-           :exc:`NotImplementedError`. Functionality provided when
+           :exc:`NotImplementedError`.  Functionality provided when
            :meth:`exec_module` is available.
 
         .. deprecated:: 3.4
            The recommended API for loading a module is :meth:`exec_module`
-           (and :meth:`create_module`).  Loaders should implement
-           it instead of load_module().  The import machinery takes care of
-           all the other responsibilities of load_module() when exec_module()
-           is implemented.
+           (and :meth:`create_module`).  Loaders should implement it instead of
+           :meth:`load_module`.  The import machinery takes care of all the
+           other responsibilities of :meth:`load_module` when
+           :meth:`exec_module` is implemented.
 
     .. method:: module_repr(module)
 
-        A legacy method which when implemented calculates and returns the
-        given module's repr, as a string. The module type's default repr() will
-        use the result of this method as appropriate.
+        A legacy method which when implemented calculates and returns the given
+        module's representation, as a string.  The module type's default
+        :meth:`__repr__` will use the result of this method as appropriate.
 
         .. versionadded:: 3.3
 
@@ -1420,69 +1422,80 @@ 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.  This is
-   typically exposed as the module's ``__spec__`` attribute.  In the
+   typically exposed as the module's :attr:`__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
+   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``.
+   no synchronization between the two objects.  For example, it is possible to update
+   the module's :attr:`__file__` at runtime and this will not be automatically
+   reflected in the module's :attr:`__spec__.origin`, and vice versa.
 
    .. versionadded:: 3.4
 
    .. attribute:: name
 
-   (``__name__``)
+   (:attr:`__name__`)
 
-   A string for the fully-qualified name of the module.
+   The module's fully-qualified name.
+   The :term:`finder` should always set this attribute to a non-empty string.
 
    .. attribute:: loader
 
-   (``__loader__``)
+   (:attr:`__loader__`)
 
-   The :term:`Loader <loader>` that should be used when loading
-   the module.  :term:`Finders <finder>` should always set this.
+   The :term:`loader` used to load the module.
+   The :term:`finder` should always set this attribute.
 
    .. attribute:: origin
 
-   (``__file__``)
+   (:attr:`__file__`)
 
-   Name of the place from which the module is loaded, e.g. "builtin" for
-   built-in modules and the filename for modules loaded from source.
-   Normally "origin" should be set, but it may be ``None`` (the default)
-   which indicates it is unspecified (e.g. for namespace packages).
+   The location the :term:`loader` should use to load the module.
+   For example, for modules loaded from a .py file this is the filename.
+   The :term:`finder` should always set this attribute to a meaningful value
+   for the :term:`loader` to use.  In the uncommon case that there is not one
+   (like for namespace packages), it should be set to ``None``.
 
    .. attribute:: submodule_search_locations
 
-   (``__path__``)
+   (:attr:`__path__`)
 
-   List of strings for where to find submodules, if a package (``None``
-   otherwise).
+   The list of locations where the package's submodules will be found.
+   Most of the time this is a single directory.
+   The :term:`finder` should set this attribute to a list, even an empty one, to indicate
+   to the import system that the module is a package.  It should be set to ``None`` for
+   non-package modules.  It is set automatically later to a special object for
+   namespace packages.
 
    .. attribute:: loader_state
 
-   Container of extra module-specific data for use during loading (or
-   ``None``).
+   The :term:`finder` may set this attribute to an object containing additional,
+   module-specific data to use when loading the module.  Otherwise it should be
+   set to ``None``.
 
    .. attribute:: cached
 
-   (``__cached__``)
+   (:attr:`__cached__`)
 
-   String for where the compiled module should be stored (or ``None``).
+   The filename of a compiled version of the module's code.
+   The :term:`finder` should always set this attribute but it may be ``None``
+   for modules that do not need compiled code stored.
 
    .. attribute:: parent
 
-   (``__package__``)
+   (:attr:`__package__`)
 
-   (Read-only) The fully-qualified name of the package under which the module
-   should be loaded as a submodule (or the empty string for top-level modules).
-   For packages, it is the same as :attr:`__name__`.
+   (Read-only) The fully-qualified name of the package the module is in (or the
+   empty string for a top-level module).
+   If the module is a package then this is the same as :attr:`name`.
 
    .. attribute:: has_location
 
-   Boolean indicating whether or not the module's "origin"
-   attribute refers to a loadable location.
+   ``True`` if the spec's :attr:`origin` refers to a loadable location,
+    ``False`` otherwise.  This value impacts how :attr:`origin` is interpreted
+    and how the module's :attr:`__file__` is populated.
+
 
 :mod:`importlib.util` -- Utility code for importers
 ---------------------------------------------------
@@ -1574,8 +1587,9 @@ an :term:`importer`.
 
    :exc:`ImportError` is raised if **name** is a relative module name but
    **package** is a false value (e.g. ``None`` or the empty string).
-   :exc:`ImportError` is also raised a relative name would escape its containing
-   package (e.g. requesting ``..bacon`` from within the ``spam`` package).
+   :exc:`ImportError` is also raised if a relative name would escape its
+   containing package (e.g. requesting ``..bacon`` from within the ``spam``
+   package).
 
    .. versionadded:: 3.3
 

Doc/library/netrc.rst

@@ -41,6 +41,10 @@ the Unix :program:`ftp` program and other FTP clients.
    .. versionchanged:: 3.10
       :class:`netrc` try UTF-8 encoding before using locale specific
       encoding.
+      The entry in the netrc file no longer needs to contain all tokens.  The missing
+      tokens' value default to an empty string.  All the tokens and their values now
+      can contain arbitrary characters, like whitespace and non-ASCII characters.
+      If the login name is anonymous, it won't trigger the security check.
 
 
 .. exception:: NetrcParseError
@@ -85,10 +89,3 @@ Instances of :class:`~netrc.netrc` have public instance variables:
 .. attribute:: netrc.macros
 
    Dictionary mapping macro names to string lists.
-
-.. note::
-
-   Passwords are limited to a subset of the ASCII character set.  All ASCII
-   punctuation is allowed in passwords, however, note that whitespace and
-   non-printable characters are not allowed in passwords.  This is a limitation
-   of the way the .netrc file is parsed and may be removed in the future.

Doc/library/time.rst

@@ -362,17 +362,17 @@ Functions
    On Windows, if *secs* is zero, the thread relinquishes the remainder of its
    time slice to any other thread that is ready to run. If there are no other
    threads ready to run, the function returns immediately, and the thread
-   continues execution.
+   continues execution.  On Windows 8.1 and newer the implementation uses
+   a `high-resolution timer
+   <https://docs.microsoft.com/en-us/windows-hardware/drivers/kernel/high-resolution-timers>`_
+   which provides resolution of 100 nanoseconds. If *secs* is zero, ``Sleep(0)`` is used.
 
    Unix implementation:
 
    * Use ``clock_nanosleep()`` if available (resolution: 1 nanosecond);
    * Or use ``nanosleep()`` if available (resolution: 1 nanosecond);
    * Or use ``select()`` (resolution: 1 microsecond).
 
-   On Windows, a waitable timer is used (resolution: 100 nanosecond). If *secs* is
-   zero, ``Sleep(0)`` is used.
-
    .. versionchanged:: 3.11
       On Unix, the ``clock_nanosleep()`` and ``nanosleep()`` functions are now
       used if available. On Windows, a waitable timer is now used.

Doc/library/unittest.rst

@@ -227,7 +227,7 @@ Command-line options
 
    Only run test methods and classes that match the pattern or substring.
    This option may be used multiple times, in which case all test cases that
-   match of the given patterns are included.
+   match any of the given patterns are included.
 
    Patterns that contain a wildcard character (``*``) are matched against the
    test name using :meth:`fnmatch.fnmatchcase`; otherwise simple case-sensitive

Doc/whatsnew/3.11.rst

@@ -269,6 +269,7 @@ threading
   by system clock changes.
   (Contributed by Victor Stinner in :issue:`41710`.)
 
+
 time
 ----
 
@@ -278,10 +279,13 @@ time
   of 1 microsecond (10\ :sup:`-6` seconds).
   (Contributed by Benjamin Szőke and Victor Stinner in :issue:`21302`.)
 
-* On Windows, :func:`time.sleep` now uses a waitable timer which has a
-  resolution of 100 nanoseconds (10\ :sup:`-7` seconds). Previously, it had
-  a resolution of 1 millisecond (10\ :sup:`-3` seconds).
-  (Contributed by Benjamin Szőke and Victor Stinner in :issue:`21302`.)
+* On Windows 8.1 and newer, :func:`time.sleep` now uses a waitable timer based
+  on `high-resolution timers
+  <https://docs.microsoft.com/en-us/windows-hardware/drivers/kernel/high-resolution-timers>`_
+  which has a resolution of 100 nanoseconds (10\ :sup:`-7` seconds). Previously,
+  it had a resolution of 1 millisecond (10\ :sup:`-3` seconds).
+  (Contributed by Benjamin Szőke, Dong-hee Na, Eryk Sun and Victor Stinner in :issue:`21302` and :issue:`45429`.)
+
 
 unicodedata
 -----------

Include/internal/pycore_abstract.h

@@ -16,6 +16,9 @@ _PyIndex_Check(PyObject *obj)
     return (tp_as_number != NULL && tp_as_number->nb_index != NULL);
 }
 
+PyObject *_PyNumber_PowerNoMod(PyObject *lhs, PyObject *rhs);
+PyObject *_PyNumber_InPlacePowerNoMod(PyObject *lhs, PyObject *rhs);
+
 #ifdef __cplusplus
 }
 #endif

Include/internal/pycore_code.h

@@ -17,6 +17,7 @@ typedef struct {
     uint8_t original_oparg;
     uint8_t counter;
     uint16_t index;
+    uint32_t version;
 } _PyAdaptiveEntry;
 
 
@@ -266,7 +267,7 @@ int _Py_Specialize_LoadAttr(PyObject *owner, _Py_CODEUNIT *instr, PyObject *name
 int _Py_Specialize_StoreAttr(PyObject *owner, _Py_CODEUNIT *instr, PyObject *name, SpecializedCacheEntry *cache);
 int _Py_Specialize_LoadGlobal(PyObject *globals, PyObject *builtins, _Py_CODEUNIT *instr, PyObject *name, SpecializedCacheEntry *cache);
 int _Py_Specialize_LoadMethod(PyObject *owner, _Py_CODEUNIT *instr, PyObject *name, SpecializedCacheEntry *cache);
-int _Py_Specialize_BinarySubscr(PyObject *sub, PyObject *container, _Py_CODEUNIT *instr);
+int _Py_Specialize_BinarySubscr(PyObject *sub, PyObject *container, _Py_CODEUNIT *instr, SpecializedCacheEntry *cache);
 int _Py_Specialize_CallFunction(PyObject *callable, _Py_CODEUNIT *instr, int nargs, SpecializedCacheEntry *cache, PyObject *builtins);
 void _Py_Specialize_BinaryOp(PyObject *lhs, PyObject *rhs, _Py_CODEUNIT *instr,
                              SpecializedCacheEntry *cache);

Include/internal/pycore_long.h

@@ -23,6 +23,7 @@ static inline PyObject* _PyLong_GetOne(void)
 
 PyObject *_PyLong_Add(PyLongObject *left, PyLongObject *right);
 PyObject *_PyLong_Multiply(PyLongObject *left, PyLongObject *right);
+PyObject *_PyLong_Subtract(PyLongObject *left, PyLongObject *right);
 
 /* Used by Python/mystrtoul.c, _PyBytes_FromHex(),
    _PyBytes_DecodeEscape(), etc. */