Merge remote-tracking branch 'origin/main' into gh-158195-unpin-type-lock

Author: nascheme

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

@@ -18,6 +18,15 @@ Pending removal in Python 3.21
   * The ``dims`` property of ``ast.Tuple`` will be removed in Python 3.21. Use
     the ``ast.Tuple.elts`` property instead.
 
+* :mod:`functools`:
+
+  * Using a return annotation to infer the dispatch type for
+    :func:`functools.singledispatch` or
+    :class:`functools.singledispatchmethod` is deprecated since Python 3.16
+    and will raise :exc:`TypeError` in Python 3.21. Annotate the dispatch
+    parameter or pass the dispatch type explicitly instead.
+    (Contributed by Bartosz Sławecki in :gh:`143465`.)
+
 * :mod:`struct`:
 
   * Soft-deprecated since Python 3.15, using ``'F'`` and ``'D'`` type codes are now

Doc/library/argparse.rst

@@ -2072,6 +2072,19 @@ Argument groups
       is now deprecated.
 
 
+.. class:: ArgumentGroup
+
+   The type of objects returned by :meth:`ArgumentParser.add_argument_group`.
+   Its :meth:`~ArgumentParser.add_argument` and
+   :meth:`~ArgumentParser.add_mutually_exclusive_group` methods work as on
+   :class:`ArgumentParser`.  Use :meth:`~ArgumentParser.add_argument_group`
+   to create instances.  Only the methods documented here are part of the
+   public API; other attributes and methods are implementation details.
+
+   .. versionadded:: next
+      The private ``_ArgumentGroup`` name remains as an alias.
+
+
 Mutual exclusion
 ^^^^^^^^^^^^^^^^
 
@@ -2135,6 +2148,20 @@ Mutual exclusion
       exposed through inheritance.
 
 
+.. class:: MutuallyExclusiveGroup
+
+   The type of objects returned by
+   :meth:`ArgumentParser.add_mutually_exclusive_group`.
+   Its :meth:`~ArgumentParser.add_argument` method works as on
+   :class:`ArgumentParser`.  Use
+   :meth:`~ArgumentParser.add_mutually_exclusive_group` to create instances.
+   Only the ``add_argument`` method documented here is part of the public API;
+   other attributes and methods are implementation details.
+
+   .. versionadded:: next
+      The private ``_MutuallyExclusiveGroup`` name remains as an alias.
+
+
 Parser defaults
 ^^^^^^^^^^^^^^^
 

Doc/library/ctypes.rst

@@ -1563,7 +1563,7 @@ way is to instantiate :py:class:`CDLL` or one of its subclasses:
    On non-Windows systems, *name* can  be ``None``. In this case,
    :c:func:`!dlopen` is called with ``NULL``, which opens the main program
    as a "library".
-   (Some systems do the same is *name* is empty; ``None``/``NULL`` is more
+   (Some systems do the same if *name* is empty; ``None``/``NULL`` is more
    portable.)
 
    .. admonition:: CPython implementation detail

Doc/library/functools.rst

@@ -506,24 +506,37 @@ The :mod:`!functools` module defines the following functions:
       :no-typesetting:
 
    To add overloaded implementations to the function, use the :func:`!register`
-   attribute of the generic function, which can be used as a decorator.  For
-   functions annotated with types, the decorator will infer the type of the
-   first argument automatically::
+   attribute of the generic function, which can be used as a decorator.
+   Pass the dispatch type to the decorator::
 
-     >>> @fun.register
-     ... def _(arg: int, verbose=False):
+     >>> @fun.register(int)
+     ... def _(arg, verbose=False):
      ...     if verbose:
      ...         print("Strength in numbers, eh?", end=" ")
      ...     print(arg)
      ...
-     >>> @fun.register
-     ... def _(arg: list, verbose=False):
+     >>> @fun.register(list)
+     ... def _(arg, verbose=False):
      ...     if verbose:
      ...         print("Enumerate this:")
      ...     for i, elem in enumerate(arg):
      ...         print(i, elem)
 
-   :class:`typing.Union` can also be used::
+   As a shortcut, for functions annotated with types, the decorator can infer
+   the dispatch type without an explicit type argument::
+
+     >>> @fun.register
+     ... def _(arg: int, verbose=False):
+     ...     if verbose:
+     ...         print("Strength in numbers, eh?", end=" ")
+     ...     print(arg)
+     ...
+
+   This shortcut uses the first annotation, even if it belongs to another
+   parameter or the return value. Annotate the dispatch parameter, or pass the
+   dispatch type explicitly if its annotation is not first.
+
+   :class:`typing.Union` can also be used with this shortcut::
 
     >>> @fun.register
     ... def _(arg: int | float, verbose=False):
@@ -540,16 +553,6 @@ The :mod:`!functools` module defines the following functions:
     ...         print(i, elem)
     ...
 
-   For code which doesn't use type annotations, the appropriate type
-   argument can be passed explicitly to the decorator itself::
-
-     >>> @fun.register(complex)
-     ... def _(arg, verbose=False):
-     ...     if verbose:
-     ...         print("Better than complicated.", end=" ")
-     ...     print(arg.real, arg.imag)
-     ...
-
    For code that dispatches on a collections type (e.g., ``list``), but wants
    to typehint the items of the collection (e.g., ``list[int]``), the
    dispatch type should be passed explicitly to the decorator itself with the
@@ -662,6 +665,12 @@ The :mod:`!functools` module defines the following functions:
       The :func:`~singledispatch.register` attribute now supports
       :class:`typing.Union` as a type annotation.
 
+   .. deprecated:: 3.16
+      Using a return annotation to infer the dispatch type is deprecated and
+      will raise :exc:`TypeError` in Python 3.21. Annotate the dispatch
+      parameter or pass the dispatch type explicitly to :func:`!register`
+      instead.
+
 
 .. class:: singledispatchmethod(func)
 
@@ -686,6 +695,20 @@ The :mod:`!functools` module defines the following functions:
         def _(self, arg: bool):
             return not arg
 
+   When *self* or *cls* is annotated, pass the dispatch type explicitly rather
+   than relying on annotation inference::
+
+    from typing import Self
+
+    class Negator:
+        @singledispatchmethod
+        def neg(self, arg):
+            raise NotImplementedError("Cannot negate a")
+
+        @neg.register(int)
+        def _(self: Self, arg: int):
+            return -arg
+
    ``@singledispatchmethod`` supports nesting with other decorators such as
    :deco:`classmethod`. Note that to allow for
    ``dispatcher.register``, ``singledispatchmethod`` must be the *outer most*

Doc/library/pickle.rst

@@ -517,7 +517,11 @@ The following types can be pickled:
 * classes accessible from the top level of a module;
 
 * instances of such classes for which the result of calling :meth:`~object.__getstate__`
-  is picklable  (see section :ref:`pickle-inst` for details).
+  is picklable  (see section :ref:`pickle-inst` for details);
+
+* weak references and the weak containers from the :mod:`weakref` module,
+  provided that the weakly referenced objects are strongly referenced
+  elsewhere in the same pickle (see :class:`weakref.ref`).
 
 Attempts to pickle unpicklable objects will raise the :exc:`PicklingError`
 exception; when this happens, an unspecified number of bytes may have already

Doc/library/weakref.rst

@@ -126,6 +126,17 @@ See :ref:`__slots__ documentation <slots>` for details.
    Weak references are :ref:`generic <generics>` over the type of the object they
    reference.
 
+   A weak reference can be pickled
+   if the referent is strongly referenced elsewhere in the same pickle;
+   otherwise pickling raises :exc:`pickle.PicklingError`.
+   The unpickled weak reference refers to the unpickled referent.
+   A reference to a dead object unpickles as a reference to a dead object.
+   The *callback* is not preserved.
+
+   Weak references are atomic for the :mod:`copy` module:
+   :func:`copy.copy` and :func:`copy.deepcopy` return
+   the original weak reference without copying the referent.
+
    .. attribute:: __callback__
 
       This read-only attribute returns the callback currently associated to the
@@ -138,6 +149,9 @@ See :ref:`__slots__ documentation <slots>` for details.
    .. versionchanged:: 3.16
       Raise :exc:`!TypeError` if *callback* is not callable or ``None``.
 
+   .. versionchanged:: next
+      Weak references can now be pickled.
+
 
 .. function:: proxy(object[, callback])
 
@@ -203,9 +217,16 @@ See :ref:`__slots__ documentation <slots>` for details.
       >>> d[k2] = 2   # d = {k2: 2}
       >>> del k1      # d = {k2: 2}
 
+   A :class:`!WeakKeyDictionary` can be copied,
+   and pickled if the keys are strongly referenced
+   elsewhere in the same pickle (see :class:`ref`).
+
    .. versionchanged:: 3.9
       Added support for ``|`` and ``|=`` operators, as specified in :pep:`584`.
 
+   .. versionchanged:: next
+      :class:`!WeakKeyDictionary` can now be pickled.
+
 :class:`WeakKeyDictionary` objects have an additional method that
 exposes the internal references directly.  The references are not guaranteed to
 be "live" at the time they are used, so the result of calling the references
@@ -224,9 +245,16 @@ than needed.
    Mapping class that references values weakly.  Entries in the dictionary will be
    discarded when no strong reference to the value exists any more.
 
+   A :class:`!WeakValueDictionary` can be copied,
+   and pickled if the values are strongly referenced
+   elsewhere in the same pickle (see :class:`ref`).
+
    .. versionchanged:: 3.9
       Added support for ``|`` and ``|=`` operators, as specified in :pep:`584`.
 
+   .. versionchanged:: next
+      :class:`!WeakValueDictionary` can now be pickled.
+
 :class:`WeakValueDictionary` objects have the following additional methods.
 These have the same issues as the :meth:`WeakKeyDictionary.keyrefs` method.
 
@@ -246,6 +274,14 @@ These have the same issues as the :meth:`WeakKeyDictionary.keyrefs` method.
    Set class that keeps weak references to its elements.  An element will be
    discarded when no strong reference to it exists any more.
 
+   A :class:`!WeakSet` can be pickled if the elements are strongly
+   referenced elsewhere in the same pickle (see :class:`ref`).
+   A copy or a deep copy shares the elements with the original;
+   user-defined attributes are copied or deep-copied.
+
+   .. versionchanged:: next
+      :class:`!WeakSet` can now be pickled and copied.
+
 
 .. class:: WeakMethod(method[, callback])
 
@@ -275,8 +311,16 @@ These have the same issues as the :meth:`WeakKeyDictionary.keyrefs` method.
 
    *callback* is the same as the parameter of the same name to the :func:`ref` function.
 
+   A :class:`!WeakMethod` can be copied,
+   and pickled if the object the method is bound to is strongly referenced
+   elsewhere in the same pickle (see :class:`ref`).
+   A copy or a deep copy is an equal weak method to the same object.
+
    .. versionadded:: 3.4
 
+   .. versionchanged:: next
+      :class:`!WeakMethod` can now be pickled and copied.
+
 .. class:: finalize(obj, func, /, *args, **kwargs)
 
    Return a callable finalizer object which will be called when *obj*

Doc/library/zlib.rst

@@ -487,11 +487,14 @@ the following constants:
 
    The version string of the zlib library actually loaded by the interpreter.
 
+   Prefer :const:`!zlib_version` over its :const:`!ZLIB_RUNTIME_VERSION` alias.
+
    .. versionadded:: 3.3
       The :const:`!ZLIB_RUNTIME_VERSION` constant.
 
    .. versionadded:: 3.16
-      The :const:`!zlib_version` alias.
+      The :const:`!zlib_version` constant; :const:`!ZLIB_RUNTIME_VERSION` is now
+      an alias for it.
 
 
 .. data:: ZLIB_VERSION_INFO

Doc/whatsnew/3.16.rst

@@ -126,6 +126,16 @@ New modules
 Improved modules
 ================
 
+argparse
+--------
+
+* :class:`~argparse.ArgumentGroup` and
+  :class:`~argparse.MutuallyExclusiveGroup`, the types returned by
+  :meth:`~argparse.ArgumentParser.add_argument_group` and
+  :meth:`~argparse.ArgumentParser.add_mutually_exclusive_group`, are now
+  public. The ``_``-prefixed names remain as aliases.
+  (Contributed by Bernát Gábor in :gh:`144812`.)
+
 asyncio
 -------
 
@@ -586,6 +596,17 @@ pydoc
   (Contributed by Serhiy Storchaka in :gh:`153906`.)
 
 
+pickle
+------
+
+* Weak references (:class:`weakref.ref`), :class:`weakref.WeakMethod`,
+  :class:`weakref.WeakSet`, :class:`weakref.WeakValueDictionary` and
+  :class:`weakref.WeakKeyDictionary` can now be pickled if the weakly
+  referenced objects are strongly referenced elsewhere in the same pickle;
+  otherwise pickling raises :exc:`pickle.PicklingError`.
+  :class:`!WeakMethod` and :class:`!WeakSet` can now also be copied.
+  (Contributed by Serhiy Storchaka in :gh:`74876`.)
+
 re
 --
 
@@ -1068,6 +1089,16 @@ New deprecations
     3.9, now issues a deprecation warning on use. This property is slated for
     removal in 3.21. Use ``ast.Tuple.elts`` instead.
 
+* :mod:`functools`:
+
+  * Using a return annotation to infer the dispatch type for
+    :func:`functools.singledispatch` or
+    :class:`functools.singledispatchmethod` now emits a
+    :exc:`DeprecationWarning` and will raise :exc:`TypeError` in Python 3.21.
+    Annotate the dispatch parameter or pass the dispatch type explicitly
+    instead.
+    (Contributed by Bartosz Sławecki in :gh:`143465`.)
+
 * :mod:`struct`:
 
   * The ``'F'`` and ``'D'`` type codes, soft-deprecated since Python 3.15,