Merge branch 'main' into pyio-take-bytes

Author: emmatyping

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/imaplib.rst

@@ -199,6 +199,11 @@ An :class:`IMAP4` instance has the following methods:
 
    Append *message* to named mailbox.
 
+   *flags* may be ``None`` or a string of IMAP flag tokens.  Multiple
+   flags are separated by spaces, for example ``r'\Seen \Answered'``.
+   If *flags* is not already enclosed in parentheses, parentheses are
+   added automatically.
+
 
 .. method:: IMAP4.authenticate(mechanism, authobject)
 

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/multiprocessing.rst

@@ -100,10 +100,10 @@ To show the individual process IDs involved, here is an expanded example::
 For an explanation of why the ``if __name__ == '__main__'`` part is
 necessary, see :ref:`multiprocessing-programming`.
 
-The arguments to :class:`Process` usually need to be unpickleable from within
-the child process. If you tried typing the above example directly into a REPL it
-could lead to an :exc:`AttributeError` in the child process trying to locate the
-*f* function in the ``__main__`` module.
+The arguments to :class:`Process` usually need to be picklable so they can be
+passed to the child process. If you tried typing the above example directly
+into a REPL it could lead to an :exc:`AttributeError` in the child process
+trying to locate the *f* function in the ``__main__`` module.
 
 
 .. _multiprocessing-start-methods:

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)
 
@@ -5062,6 +5074,18 @@ written in Python, such as a mail server's external command delivery program.
    .. availability:: Linux >= 5.10
    .. versionadded:: 3.12
 
+.. function:: pidfd_getfd(pidfd, targetfd, *, flags=0)
+
+   Duplicate *targetfd* from the process referred to by the process file
+   descriptor *pidfd*, into the calling process.  The returned file descriptor
+   is :ref:`non-inheritable <fd_inheritance>`.
+
+   *flags* is reserved, and currently must be ``0``.
+
+   See the :manpage:`pidfd_getfd(2)` man page for more details.
+
+   .. availability:: Linux >= 5.6, Android >= :func:`build-time <sys.getandroidapilevel>` API level 31
+   .. versionadded:: next
 
 .. function:: plock(op, /)
 

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

@@ -86,10 +86,12 @@ New modules
 Improved modules
 ================
 
-module_name
------------
+os
+--
 
-* TODO
+* Add :func:`os.pidfd_getfd` for duplicating a file descriptor from another
+  process via a pidfd.  Available on Linux 5.6+.
+  (Contributed by Maurycy Pawłowski-Wieroński in :gh:`149464`.)
 
 .. Add improved modules above alphabetically, not here at the end.
 
@@ -182,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.