Merge remote-tracking branch 'upstream/main' into pythongh-114881

.github/workflows/reusable-macos.yml

@@ -17,6 +17,7 @@ jobs:
       HOMEBREW_NO_ANALYTICS: 1
       HOMEBREW_NO_AUTO_UPDATE: 1
       HOMEBREW_NO_INSTALL_CLEANUP: 1
+      HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: 1
       PYTHONSTRICTEXTENSIONBUILD: 1
     strategy:
       fail-fast: false

Doc/library/ast.rst

@@ -103,20 +103,15 @@ Node classes
    For example, to create and populate an :class:`ast.UnaryOp` node, you could
    use ::
 
-      node = ast.UnaryOp()
-      node.op = ast.USub()
-      node.operand = ast.Constant()
-      node.operand.value = 5
-      node.operand.lineno = 0
-      node.operand.col_offset = 0
-      node.lineno = 0
-      node.col_offset = 0
-
-   or the more compact ::
-
       node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),
                          lineno=0, col_offset=0)
 
+   If a field that is optional in the grammar is omitted from the constructor,
+   it defaults to ``None``. If a list field is omitted, it defaults to the empty
+   list. If any other field is omitted, a :exc:`DeprecationWarning` is raised
+   and the AST node will not have this field. In Python 3.15, this condition will
+   raise an error.
+
 .. versionchanged:: 3.8
 
    Class :class:`ast.Constant` is now used for all constants.
@@ -140,6 +135,14 @@ Node classes
    In the meantime, instantiating them will return an instance of
    a different class.
 
+.. deprecated-removed:: 3.13 3.15
+
+   Previous versions of Python allowed the creation of AST nodes that were missing
+   required fields. Similarly, AST node constructors allowed arbitrary keyword
+   arguments that were set as attributes of the AST node, even if they did not
+   match any of the fields of the AST node. This behavior is deprecated and will
+   be removed in Python 3.15.
+
 .. note::
     The descriptions of the specific node classes displayed here
     were initially adapted from the fantastic `Green Tree

Doc/library/functions.rst

@@ -526,9 +526,20 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: eval(expression, globals=None, locals=None)
 
-   The arguments are a string and optional globals and locals.  If provided,
-   *globals* must be a dictionary.  If provided, *locals* can be any mapping
-   object.
+   :param expression:
+      A Python expression.
+   :type expression: :class:`str` | :ref:`code object <code-objects>`
+
+   :param globals:
+      The global namespace (default: ``None``).
+   :type globals: :class:`dict` | ``None``
+
+   :param locals:
+      The local namespace (default: ``None``).
+   :type locals: :term:`mapping` | ``None``
+
+   :returns: The result of the evaluated expression.
+   :raises: Syntax errors are reported as exceptions.
 
    The *expression* argument is parsed and evaluated as a Python expression
    (technically speaking, a condition list) using the *globals* and *locals*
@@ -545,8 +556,7 @@ are always available.  They are listed here in alphabetical order.
    :term:`nested scopes <nested scope>` (non-locals) in the enclosing
    environment.
 
-   The return value is the result of
-   the evaluated expression. Syntax errors are reported as exceptions.  Example:
+   Example:
 
       >>> x = 1
       >>> eval('x+1')

Doc/library/json.rst

@@ -106,7 +106,7 @@ Extending :class:`JSONEncoder`::
     ...         if isinstance(obj, complex):
     ...             return [obj.real, obj.imag]
     ...         # Let the base class default method raise the TypeError
-    ...         return json.JSONEncoder.default(self, obj)
+    ...         return super().default(obj)
     ...
     >>> json.dumps(2 + 1j, cls=ComplexEncoder)
     '[2.0, 1.0]'
@@ -504,7 +504,7 @@ Encoders and Decoders
             else:
                 return list(iterable)
             # Let the base class default method raise the TypeError
-            return json.JSONEncoder.default(self, o)
+            return super().default(o)
 
 
    .. method:: encode(o)

Doc/library/pprint.rst

@@ -31,7 +31,93 @@ Dictionaries are sorted by key before the display is computed.
 .. versionchanged:: 3.10
    Added support for pretty-printing :class:`dataclasses.dataclass`.
 
-The :mod:`pprint` module defines one class:
+.. _pprint-functions:
+
+Functions
+---------
+
+.. function:: pp(object, *args, sort_dicts=False, **kwargs)
+
+   Prints the formatted representation of *object* followed by a newline.
+   If *sort_dicts* is false (the default), dictionaries will be displayed with
+   their keys in insertion order, otherwise the dict keys will be sorted.
+   *args* and *kwargs* will be passed to :func:`~pprint.pprint` as formatting
+   parameters.
+
+   .. versionadded:: 3.8
+
+
+.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
+                     compact=False, sort_dicts=True, underscore_numbers=False)
+
+   Prints the formatted representation of *object* on *stream*, followed by a
+   newline.  If *stream* is ``None``, :data:`sys.stdout` is used. This may be used
+   in the interactive interpreter instead of the :func:`print` function for
+   inspecting values (you can even reassign ``print = pprint.pprint`` for use
+   within a scope).
+
+   The configuration parameters *stream*, *indent*, *width*, *depth*,
+   *compact*, *sort_dicts* and *underscore_numbers* are passed to the
+   :class:`PrettyPrinter` constructor and their meanings are as
+   described in its documentation above.
+
+      >>> import pprint
+      >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
+      >>> stuff.insert(0, stuff)
+      >>> pprint.pprint(stuff)
+      [<Recursion on list with id=...>,
+       'spam',
+       'eggs',
+       'lumberjack',
+       'knights',
+       'ni']
+
+.. function:: pformat(object, indent=1, width=80, depth=None, *, \
+                      compact=False, sort_dicts=True, underscore_numbers=False)
+
+   Return the formatted representation of *object* as a string.  *indent*,
+   *width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are
+   passed to the :class:`PrettyPrinter` constructor as formatting parameters
+   and their meanings are as described in its documentation above.
+
+
+.. function:: isreadable(object)
+
+   .. index:: pair: built-in function; eval
+
+   Determine if the formatted representation of *object* is "readable", or can be
+   used to reconstruct the value using :func:`eval`.  This always returns ``False``
+   for recursive objects.
+
+      >>> pprint.isreadable(stuff)
+      False
+
+
+.. function:: isrecursive(object)
+
+   Determine if *object* requires a recursive representation.  This function is
+   subject to the same limitations as noted in :func:`saferepr` below and may raise an
+   :exc:`RecursionError` if it fails to detect a recursive object.
+
+
+.. function:: saferepr(object)
+
+   Return a string representation of *object*, protected against recursion in
+   some common data structures, namely instances of :class:`dict`, :class:`list`
+   and :class:`tuple` or subclasses whose ``__repr__`` has not been overridden.  If the
+   representation of object exposes a recursive entry, the recursive reference
+   will be represented as ``<Recursion on typename with id=number>``.  The
+   representation is not otherwise formatted.
+
+   >>> pprint.saferepr(stuff)
+   "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
+
+.. _prettyprinter-objects:
+
+PrettyPrinter Objects
+---------------------
+
+This module defines one class:
 
 .. First the implementation class:
 
@@ -44,9 +130,9 @@ The :mod:`pprint` module defines one class:
    Construct a :class:`PrettyPrinter` instance.  This constructor understands
    several keyword parameters.
 
-   *stream* (default ``sys.stdout``) is a :term:`file-like object` to
+   *stream* (default :data:`!sys.stdout`) is a :term:`file-like object` to
    which the output will be written by calling its :meth:`!write` method.
-   If both *stream* and ``sys.stdout`` are ``None``, then
+   If both *stream* and :data:`!sys.stdout` are ``None``, then
    :meth:`~PrettyPrinter.pprint` silently returns.
 
    Other values configure the manner in which nesting of complex data
@@ -87,7 +173,7 @@ The :mod:`pprint` module defines one class:
       Added the *underscore_numbers* parameter.
 
    .. versionchanged:: 3.11
-      No longer attempts to write to ``sys.stdout`` if it is ``None``.
+      No longer attempts to write to :data:`!sys.stdout` if it is ``None``.
 
       >>> import pprint
       >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
@@ -112,89 +198,6 @@ The :mod:`pprint` module defines one class:
       >>> pp.pprint(tup)
       ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
 
-.. function:: pformat(object, indent=1, width=80, depth=None, *, \
-                      compact=False, sort_dicts=True, underscore_numbers=False)
-
-   Return the formatted representation of *object* as a string.  *indent*,
-   *width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are
-   passed to the :class:`PrettyPrinter` constructor as formatting parameters
-   and their meanings are as described in its documentation above.
-
-
-.. function:: pp(object, *args, sort_dicts=False, **kwargs)
-
-   Prints the formatted representation of *object* followed by a newline.
-   If *sort_dicts* is false (the default), dictionaries will be displayed with
-   their keys in insertion order, otherwise the dict keys will be sorted.
-   *args* and *kwargs* will be passed to :func:`pprint` as formatting
-   parameters.
-
-   .. versionadded:: 3.8
-
-
-.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
-                     compact=False, sort_dicts=True, underscore_numbers=False)
-
-   Prints the formatted representation of *object* on *stream*, followed by a
-   newline.  If *stream* is ``None``, ``sys.stdout`` is used. This may be used
-   in the interactive interpreter instead of the :func:`print` function for
-   inspecting values (you can even reassign ``print = pprint.pprint`` for use
-   within a scope).
-
-   The configuration parameters *stream*, *indent*, *width*, *depth*,
-   *compact*, *sort_dicts* and *underscore_numbers* are passed to the
-   :class:`PrettyPrinter` constructor and their meanings are as
-   described in its documentation above.
-
-      >>> import pprint
-      >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
-      >>> stuff.insert(0, stuff)
-      >>> pprint.pprint(stuff)
-      [<Recursion on list with id=...>,
-       'spam',
-       'eggs',
-       'lumberjack',
-       'knights',
-       'ni']
-
-.. function:: isreadable(object)
-
-   .. index:: pair: built-in function; eval
-
-   Determine if the formatted representation of *object* is "readable", or can be
-   used to reconstruct the value using :func:`eval`.  This always returns ``False``
-   for recursive objects.
-
-      >>> pprint.isreadable(stuff)
-      False
-
-
-.. function:: isrecursive(object)
-
-   Determine if *object* requires a recursive representation.  This function is
-   subject to the same limitations as noted in :func:`saferepr` below and may raise an
-   :exc:`RecursionError` if it fails to detect a recursive object.
-
-
-One more support function is also defined:
-
-.. function:: saferepr(object)
-
-   Return a string representation of *object*, protected against recursion in
-   some common data structures, namely instances of :class:`dict`, :class:`list`
-   and :class:`tuple` or subclasses whose ``__repr__`` has not been overridden.  If the
-   representation of object exposes a recursive entry, the recursive reference
-   will be represented as ``<Recursion on typename with id=number>``.  The
-   representation is not otherwise formatted.
-
-   >>> pprint.saferepr(stuff)
-   "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
-
-
-.. _prettyprinter-objects:
-
-PrettyPrinter Objects
----------------------
 
 :class:`PrettyPrinter` instances have the following methods:
 
@@ -258,7 +261,7 @@ are converted to strings.  The default implementation uses the internals of the
 Example
 -------
 
-To demonstrate several uses of the :func:`pprint` function and its parameters,
+To demonstrate several uses of the :func:`~pprint.pprint` function and its parameters,
 let's fetch information about a project from `PyPI <https://pypi.org>`_::
 
    >>> import json
@@ -267,7 +270,7 @@ let's fetch information about a project from `PyPI <https://pypi.org>`_::
    >>> with urlopen('https://pypi.org/pypi/sampleproject/json') as resp:
    ...     project_info = json.load(resp)['info']
 
-In its basic form, :func:`pprint` shows the whole object::
+In its basic form, :func:`~pprint.pprint` shows the whole object::
 
    >>> pprint.pprint(project_info)
    {'author': 'The Python Packaging Authority',

Doc/library/time.rst

@@ -433,6 +433,10 @@ Functions
    | ``%d``    | Day of the month as a decimal number [01,31].  |       |
    |           |                                                |       |
    +-----------+------------------------------------------------+-------+
+   | ``%f``    | Microseconds as a decimal number               | \(1)  |
+   |           |    [000000,999999].                            |       |
+   |           |                                                |       |
+   +-----------+------------------------------------------------+-------+
    | ``%H``    | Hour (24-hour clock) as a decimal number       |       |
    |           | [00,23].                                       |       |
    +-----------+------------------------------------------------+-------+
@@ -448,13 +452,13 @@ Functions
    | ``%M``    | Minute as a decimal number [00,59].            |       |
    |           |                                                |       |
    +-----------+------------------------------------------------+-------+
-   | ``%p``    | Locale's equivalent of either AM or PM.        | \(1)  |
+   | ``%p``    | Locale's equivalent of either AM or PM.        | \(2)  |
    |           |                                                |       |
    +-----------+------------------------------------------------+-------+
-   | ``%S``    | Second as a decimal number [00,61].            | \(2)  |
+   | ``%S``    | Second as a decimal number [00,61].            | \(3)  |
    |           |                                                |       |
    +-----------+------------------------------------------------+-------+
-   | ``%U``    | Week number of the year (Sunday as the first   | \(3)  |
+   | ``%U``    | Week number of the year (Sunday as the first   | \(4)  |
    |           | day of the week) as a decimal number [00,53].  |       |
    |           | All days in a new year preceding the first     |       |
    |           | Sunday are considered to be in week 0.         |       |
@@ -465,7 +469,7 @@ Functions
    | ``%w``    | Weekday as a decimal number [0(Sunday),6].     |       |
    |           |                                                |       |
    +-----------+------------------------------------------------+-------+
-   | ``%W``    | Week number of the year (Monday as the first   | \(3)  |
+   | ``%W``    | Week number of the year (Monday as the first   | \(4)  |
    |           | day of the week) as a decimal number [00,53].  |       |
    |           | All days in a new year preceding the first     |       |
    |           | Monday are considered to be in week 0.         |       |
@@ -500,17 +504,23 @@ Functions
    Notes:
 
    (1)
+       The ``%f`` format directive only applies to :func:`strptime`,
+       not to :func:`strftime`. However, see also :meth:`datetime.datetime.strptime` and
+       :meth:`datetime.datetime.strftime` where the ``%f`` format directive
+       :ref:`applies to microseconds <format-codes>`.
+
+   (2)
       When used with the :func:`strptime` function, the ``%p`` directive only affects
       the output hour field if the ``%I`` directive is used to parse the hour.
 
    .. _leap-second:
 
-   (2)
+   (3)
       The range really is ``0`` to ``61``; value ``60`` is valid in
       timestamps representing `leap seconds`_ and value ``61`` is supported
       for historical reasons.
 
-   (3)
+   (4)
       When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
       calculations when the day of the week and the year are specified.