Merge branch 'main' into bpo-2920

Author: ned-deily

Doc/deprecations/index.rst

@@ -13,6 +13,8 @@ Deprecations
 
 .. include:: pending-removal-in-3.20.rst
 
+.. include:: pending-removal-in-3.21.rst
+
 .. include:: pending-removal-in-future.rst
 
 .. include:: soft-deprecations.rst

Doc/deprecations/pending-removal-in-3.21.rst

@@ -0,0 +1,10 @@
+Pending removal in Python 3.21
+------------------------------
+
+* :mod:`ast`:
+
+  * Classes ``slice``, ``Index``, ``ExtSlice``, ``Suite``, ``Param``,
+    ``AugLoad`` and ``AugStore``, will be removed in Python 3.21. These types
+    are not generated by the parser or accepted by the code generator.
+  * The ``dims`` property of ``ast.Tuple`` will be removed in Python 3.21. Use
+    the ``ast.Tuple.elts`` property instead.

Doc/library/dataclasses.rst

@@ -418,7 +418,7 @@ Module contents
    :func:`!astuple` raises :exc:`TypeError` if *obj* is not a dataclass
    instance.
 
-.. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False, module=None, decorator=dataclass)
+.. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False, module=None, qualname=None, decorator=dataclass)
 
    Creates a new dataclass with name *cls_name*, fields as defined
    in *fields*, base classes as given in *bases*, and initialized
@@ -434,6 +434,9 @@ Module contents
    of the dataclass is set to that value.
    By default, it is set to the module name of the caller.
 
+   If *qualname* is defined, the :attr:`~type.__qualname__` attribute of the dataclass
+   is set to that value. By default, it is set to the value passed to *cls_name*.
+
    The *decorator* parameter is a callable that will be used to create the dataclass.
    It should take the class object as a first argument and the same keyword arguments
    as :deco:`dataclass`. By default, the :deco:`dataclass`
@@ -464,6 +467,8 @@ Module contents
 
    .. versionadded:: 3.14
       Added the *decorator* parameter.
+   .. versionadded:: next
+      Added the *qualname* parameter.
 
 .. function:: replace(obj, /, **changes)
 

Doc/library/inspect.rst

@@ -424,24 +424,63 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 
    Return ``True`` if the object is a bound method written in Python.
 
+   .. note::
 
-.. function:: ispackage(object)
+      For example, given this class::
 
-   Return ``True`` if the object is a :term:`package`.
+          >>> class Greeter:
+          ...     def say_hello(self):
+          ...         print('hello!')
 
-   .. versionadded:: 3.14
+      A bound method (also known as an *instance method*) is created when
+      accessing ``say_hello`` (a :term:`function` defined in the
+      ``Greeter`` namespace) through an instance of the ``Greeter`` class::
+
+          >>> instance = Greeter()
+
+          >>> instance.say_hello
+          <bound method Greeter.say_hello of <__main__.Greeter object ...>>
+          >>> ismethod(instance.say_hello)
+          True
+          >>> isfunction(instance.say_hello)
+          False
+
+      Accessing ``say_hello`` through the ``Greeter`` class will return the
+      function itself. For this function, :func:`ismethod` will return
+      ``False``, but :func:`isfunction` will return ``True``::
+
+          >>> Greeter.say_hello
+          <function Greeter.say_hello at 0x7f7503854a90>
+          >>> ismethod(Greeter.say_hello)
+          False
+          >>> isfunction(Greeter.say_hello)
+          True
+
+      See :ref:`typesmethods` for details.
 
 
 .. function:: isfunction(object)
 
    Return ``True`` if the object is a Python function, which includes functions
    created by a :term:`lambda` expression.
 
+   See the note for :func:`~inspect.ismethod` for an example.
+
+
+.. function:: ispackage(object)
+
+   Return ``True`` if the object is a :term:`package`.
+
+   .. versionadded:: 3.14
+
 
 .. function:: isgeneratorfunction(object)
 
    Return ``True`` if the object is a Python generator function.
 
+   It also returns ``True`` for bound methods created from Python generator functions
+   (see :ref:`typesmethods` for more information).
+
    .. versionchanged:: 3.8
       Functions wrapped in :func:`functools.partial` now return ``True`` if the
       wrapped function is a Python generator function.

Doc/library/os.rst

@@ -2549,7 +2549,8 @@ features:
       Windows now handles a *mode* of ``0o700``.
 
 
-.. function:: makedirs(name, mode=0o777, exist_ok=False)
+.. function:: makedirs(name, mode=0o777, exist_ok=False, *, \
+                       parent_mode=None)
 
    .. index::
       single: directory; creating
@@ -2567,6 +2568,12 @@ features:
    If *exist_ok* is ``False`` (the default), a :exc:`FileExistsError` is
    raised if the target directory already exists.
 
+   If *parent_mode* is not ``None``, it is used as the mode for any
+   newly-created, intermediate-level directories.  Like *mode*, it is
+   combined with the process's umask value; see :ref:`the mkdir()
+   description <mkdir_modebits>`.  Otherwise, intermediate directories are
+   created with the default mode, which is also subject to the umask.
+
    .. note::
 
       :func:`makedirs` will become confused if the path elements to create
@@ -2593,6 +2600,11 @@ features:
       The *mode* argument no longer affects the file permission bits of
       newly created intermediate-level directories.
 
+   .. versionadded:: 3.15
+      The *parent_mode* parameter. To match the behavior from Python 3.6 and
+      earlier (where *mode* was applied to all created directories), pass
+      ``parent_mode=mode``.
+
 
 .. function:: mkfifo(path, mode=0o666, *, dir_fd=None)
 

Doc/library/pathlib.rst

@@ -1518,7 +1518,8 @@ Creating files and directories
       :meth:`~Path.write_bytes` methods are often used to create files.
 
 
-.. method:: Path.mkdir(mode=0o777, parents=False, exist_ok=False)
+.. method:: Path.mkdir(mode=0o777, parents=False, exist_ok=False, *, \
+                       parent_mode=None)
 
    Create a new directory at this given path.  If *mode* is given, it is
    combined with the process's ``umask`` value to determine the file mode
@@ -1529,6 +1530,12 @@ Creating files and directories
    as needed; they are created with the default permissions without taking
    *mode* into account (mimicking the POSIX ``mkdir -p`` command).
 
+   If *parent_mode* is not ``None``, it is used as the mode for any
+   newly-created, intermediate-level directories when *parents* is true.
+   Like *mode*, it is combined with the process's ``umask`` value.
+   Otherwise, intermediate directories are created with the default
+   permissions (also subject to the umask).
+
    If *parents* is false (the default), a missing parent raises
    :exc:`FileNotFoundError`.
 
@@ -1542,6 +1549,9 @@ Creating files and directories
    .. versionchanged:: 3.5
       The *exist_ok* parameter was added.
 
+   .. versionadded:: 3.15
+      The *parent_mode* parameter.
+
 
 .. method:: Path.symlink_to(target, target_is_directory=False)
 

Doc/library/ssl.rst

@@ -2076,7 +2076,7 @@ to speed up repeated connections from the same clients.
    :attr:`~SSLContext.minimum_version` and
    :attr:`SSLContext.options` all affect the supported SSL
    and TLS versions of the context. The implementation does not prevent
-   invalid combination. For example a context with
+   invalid combinations. For example a context with
    :attr:`OP_NO_TLSv1_2` in :attr:`~SSLContext.options` and
    :attr:`~SSLContext.maximum_version` set to :attr:`TLSVersion.TLSv1_2`
    will not be able to establish a TLS 1.2 connection.
@@ -2891,11 +2891,11 @@ disabled by default.
 ::
 
    >>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
-   >>> client_context.minimum_version = ssl.TLSVersion.TLSv1_3
+   >>> client_context.minimum_version = ssl.TLSVersion.TLSv1_2
    >>> client_context.maximum_version = ssl.TLSVersion.TLSv1_3
 
 
-The SSL context created above will only allow TLSv1.3 and later (if
+The SSL client context created above will only allow TLSv1.2 and TLSv1.3 (if
 supported by your system) connections to a server. :const:`PROTOCOL_TLS_CLIENT`
 implies certificate validation and hostname checks by default. You have to
 load certificates into the context.

Doc/whatsnew/3.15.rst

@@ -1285,6 +1285,10 @@ os
   glibc versions 2.28 and later.
   (Contributed by Jeffrey Bosboom and Victor Stinner in :gh:`83714`.)
 
+* :func:`os.makedirs` function now has a *parent_mode* parameter that allows
+  specifying the mode for intermediate directories. This can be used to match
+  the behavior from Python 3.6 and earlier by passing ``parent_mode=mode``.
+  (Contributed by Zackery Spytz and Gregory P. Smith in :gh:`86533`.)
 
 os.path
 -------
@@ -2057,6 +2061,10 @@ importlib.resources
 pathlib
 -------
 
+* :meth:`pathlib.Path.mkdir` now has a *parent_mode* parameter that allows
+  specifying the mode for intermediate directories when ``parents=True``.
+  (Contributed by Gregory P. Smith in :gh:`86533`.)
+
 * Removed deprecated :meth:`!pathlib.PurePath.is_reserved`.
   Use :func:`os.path.isreserved` to detect reserved paths on Windows.
   (Contributed by Nikita Sobolev in :gh:`133875`.)

Doc/whatsnew/3.16.rst

@@ -184,9 +184,16 @@ tarfile
 Deprecated
 ==========
 
-* module_name:
-  TODO
-
+* :mod:`ast`:
+
+  * Classes ``slice``, ``Index``, ``ExtSlice``, ``Suite``, ``Param``,
+    ``AugLoad`` and ``AugStore``, deprecated since Python 3.9, are no longer
+    imported by ``from ast import *`` and issue a deprecation warning on
+    use. The classes are slated for removal in Python 3.21. These types are not
+    generated by the parser or accepted by the code generator.
+  * The ``dims`` property of ``ast.Tuple`` objects, deprecated since Python
+    3.9, now issues a deprecation warning on use. This property is slated for
+    removal in 3.21. Use ``ast.Tuple.elts`` instead.
 
 .. Add deprecations above alphabetically, not here at the end.
 

Lib/ast.py

@@ -21,7 +21,7 @@
 :license: Python License.
 """
 from _ast import *
-
+lazy import warnings
 
 def parse(source, filename='<unknown>', mode='exec', *,
           type_comments=False, feature_version=None, optimize=-1, module=None):
@@ -630,9 +630,11 @@ def __new__(cls, dims=(), **kwargs):
 
     def _dims_getter(self):
         """Deprecated. Use elts instead."""
+        warnings._deprecated(f"ast.Tuple.dims", remove=(3, 21))
         return self.elts
 
     def _dims_setter(self, value):
+        warnings._deprecated(f"ast.Tuple.dims", remove=(3, 21))
         self.elts = value
 
     Tuple.dims = property(_dims_getter, _dims_setter)
@@ -714,5 +716,23 @@ def main(args=None):
                color=can_colorize(file=sys.stdout),
                indent=args.indent, show_empty=args.show_empty))
 
+_deprecated = {
+        'slice': globals().pop("slice"),
+        'Index': globals().pop("Index"),
+        'ExtSlice': globals().pop("ExtSlice"),
+        'Suite': globals().pop("Suite"),
+        'AugLoad': globals().pop("AugLoad"),
+        'AugStore': globals().pop("AugStore"),
+        'Param': globals().pop("Param")
+}
+
+def __getattr__(attr):
+    try:
+        val = _deprecated[attr]
+    except KeyError:
+        raise AttributeError(f"module 'ast' has no attribute {attr!r}") from None
+    warnings._deprecated(f"ast.{attr}", remove=(3, 21))
+    return val
+
 if __name__ == '__main__':
     main()