Merge remote-tracking branch 'upstream/main' into getannos

Author: JelleZijlstra

.pre-commit-config.yaml

@@ -47,6 +47,8 @@ repos:
         exclude: Lib/test/tokenizedata/coding20731.py
       - id: trailing-whitespace
         types_or: [c, inc, python, rst]
+      - id: trailing-whitespace
+        files: '\.(gram)$'
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
     rev: 0.33.0

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

@@ -85,6 +85,13 @@ Pending removal in Python 3.15
     has been deprecated since Python 3.13.
     Use the class-based syntax or the functional syntax instead.
 
+  * When using the functional syntax of :class:`~typing.TypedDict`\s, failing
+    to pass a value to the *fields* parameter (``TD = TypedDict("TD")``) or
+    passing ``None`` (``TD = TypedDict("TD", None)``) has been deprecated
+    since Python 3.13.
+    Use ``class TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``
+    to create a TypedDict with zero field.
+
   * The :func:`typing.no_type_check_decorator` decorator function
     has been deprecated since Python 3.13.
     After eight years in the :mod:`typing` module,

Doc/library/annotationlib.rst

@@ -127,34 +127,34 @@ Classes
 
       Values are the result of evaluating the annotation expressions.
 
-   .. attribute:: FORWARDREF
+   .. attribute:: VALUE_WITH_FAKE_GLOBALS
       :value: 2
 
+      Special value used to signal that an annotate function is being
+      evaluated in a special environment with fake globals. When passed this
+      value, annotate functions should either return the same value as for
+      the :attr:`Format.VALUE` format, or raise :exc:`NotImplementedError`
+      to signal that they do not support execution in this environment.
+      This format is only used internally and should not be passed to
+      the functions in this module.
+
+   .. attribute:: FORWARDREF
+      :value: 3
+
       Values are real annotation values (as per :attr:`Format.VALUE` format)
       for defined values, and :class:`ForwardRef` proxies for undefined
       values. Real objects may contain references to :class:`ForwardRef`
       proxy objects.
 
    .. attribute:: STRING
-      :value: 3
+      :value: 4
 
       Values are the text string of the annotation as it appears in the
       source code, up to modifications including, but not restricted to,
       whitespace normalizations and constant values optimizations.
 
       The exact values of these strings may change in future versions of Python.
 
-   .. attribute:: VALUE_WITH_FAKE_GLOBALS
-      :value: 4
-
-      Special value used to signal that an annotate function is being
-      evaluated in a special environment with fake globals. When passed this
-      value, annotate functions should either return the same value as for
-      the :attr:`Format.VALUE` format, or raise :exc:`NotImplementedError`
-      to signal that they do not support execution in this environment.
-      This format is only used internally and should not be passed to
-      the functions in this module.
-
    .. versionadded:: 3.14
 
 .. class:: ForwardRef
@@ -485,3 +485,117 @@ annotations from the class and puts them in a separate attribute:
          typ.classvars = classvars  # Store the ClassVars in a separate attribute
          return typ
 
+
+Limitations of the ``STRING`` format
+------------------------------------
+
+The :attr:`~Format.STRING` format is meant to approximate the source code
+of the annotation, but the implementation strategy used means that it is not
+always possible to recover the exact source code.
+
+First, the stringifier of course cannot recover any information that is not present in
+the compiled code, including comments, whitespace, parenthesization, and operations that
+get simplified by the compiler.
+
+Second, the stringifier can intercept almost all operations that involve names looked
+up in some scope, but it cannot intercept operations that operate fully on constants.
+As a corollary, this also means it is not safe to request the ``STRING`` format on
+untrusted code: Python is powerful enough that it is possible to achieve arbitrary
+code execution even with no access to any globals or builtins. For example:
+
+.. code-block:: pycon
+
+  >>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__.__builtins__["print"]("Hello world")): pass
+  ...
+  >>> annotationlib.get_annotations(f, format=annotationlib.Format.SOURCE)
+  Hello world
+  {'x': 'None'}
+
+.. note::
+   This particular example works as of the time of writing, but it relies on
+   implementation details and is not guaranteed to work in the future.
+
+Among the different kinds of expressions that exist in Python,
+as represented by the :mod:`ast` module, some expressions are supported,
+meaning that the ``STRING`` format can generally recover the original source code;
+others are unsupported, meaning that they may result in incorrect output or an error.
+
+The following are supported (sometimes with caveats):
+
+* :class:`ast.BinOp`
+* :class:`ast.UnaryOp`
+
+  * :class:`ast.Invert` (``~``), :class:`ast.UAdd` (``+``), and :class:`ast.USub` (``-``) are supported
+  * :class:`ast.Not` (``not``) is not supported
+
+* :class:`ast.Dict` (except when using ``**`` unpacking)
+* :class:`ast.Set`
+* :class:`ast.Compare`
+
+  * :class:`ast.Eq` and :class:`ast.NotEq` are supported
+  * :class:`ast.Lt`, :class:`ast.LtE`, :class:`ast.Gt`, and :class:`ast.GtE` are supported, but the operand may be flipped
+  * :class:`ast.Is`, :class:`ast.IsNot`, :class:`ast.In`, and :class:`ast.NotIn` are not supported
+
+* :class:`ast.Call` (except when using ``**`` unpacking)
+* :class:`ast.Constant` (though not the exact representation of the constant; for example, escape
+  sequences in strings are lost; hexadecimal numbers are converted to decimal)
+* :class:`ast.Attribute` (assuming the value is not a constant)
+* :class:`ast.Subscript` (assuming the value is not a constant)
+* :class:`ast.Starred` (``*`` unpacking)
+* :class:`ast.Name`
+* :class:`ast.List`
+* :class:`ast.Tuple`
+* :class:`ast.Slice`
+
+The following are unsupported, but throw an informative error when encountered by the
+stringifier:
+
+* :class:`ast.FormattedValue` (f-strings; error is not detected if conversion specifiers like ``!r``
+  are used)
+* :class:`ast.JoinedStr` (f-strings)
+
+The following are unsupported and result in incorrect output:
+
+* :class:`ast.BoolOp` (``and`` and ``or``)
+* :class:`ast.IfExp`
+* :class:`ast.Lambda`
+* :class:`ast.ListComp`
+* :class:`ast.SetComp`
+* :class:`ast.DictComp`
+* :class:`ast.GeneratorExp`
+
+The following are disallowed in annotation scopes and therefore not relevant:
+
+* :class:`ast.NamedExpr` (``:=``)
+* :class:`ast.Await`
+* :class:`ast.Yield`
+* :class:`ast.YieldFrom`
+
+
+Limitations of the ``FORWARDREF`` format
+----------------------------------------
+
+The :attr:`~Format.FORWARDREF` format aims to produce real values as much
+as possible, with anything that cannot be resolved replaced with
+:class:`ForwardRef` objects. It is affected by broadly the same Limitations
+as the :attr:`~Format.STRING` format: annotations that perform operations on
+literals or that use unsupported expression types may raise exceptions when
+evaluated using the :attr:`~Format.FORWARDREF` format.
+
+Below are a few examples of the behavior with unsupported expressions:
+
+.. code-block:: pycon
+
+   >>> from annotationlib import get_annotations, Format
+   >>> def zerodiv(x: 1 / 0): ...
+   >>> get_annotations(zerodiv, format=Format.STRING)
+   Traceback (most recent call last):
+     ...
+   ZeroDivisionError: division by zero
+   >>> get_annotations(zerodiv, format=Format.FORWARDREF)
+   Traceback (most recent call last):
+     ...
+   ZeroDivisionError: division by zero
+   >>> def ifexp(x: 1 if y else 0): ...
+   >>> get_annotations(ifexp, format=Format.STRING)
+   {'x': '1'}

Doc/library/datetime.rst

@@ -261,6 +261,22 @@ A :class:`timedelta` object represents a duration, the difference between two
       >>> (d.days, d.seconds, d.microseconds)
       (-1, 86399, 999999)
 
+   Since the string representation of :class:`!timedelta` objects can be confusing,
+   use the following recipe to produce a more readable format:
+
+   .. code-block:: pycon
+
+      >>> def pretty_timedelta(td):
+      ...     if td.days >= 0:
+      ...         return str(td)
+      ...     return f'-({-td!s})'
+      ...
+      >>> d = timedelta(hours=-1)
+      >>> str(d)  # not human-friendly
+      '-1 day, 23:00:00'
+      >>> pretty_timedelta(d)
+      '-(1:00:00)'
+
 
 Class attributes:
 

Doc/library/fcntl.rst

@@ -107,15 +107,15 @@ The module defines the following functions:
    passed to the C :c:func:`fcntl` call.  The return value after a successful
    call is the contents of the buffer, converted to a :class:`bytes` object.
    The length of the returned object will be the same as the length of the
-   *arg* argument. This is limited to 1024 bytes.
+   *arg* argument.
 
    If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised.
 
    .. note::
-      If the type or the size of *arg* does not match the type or size
-      of the argument of the operation (for example, if an integer is
+      If the type or size of *arg* does not match the type or size
+      of the operation's argument (for example, if an integer is
       passed when a pointer is expected, or the information returned in
-      the buffer by the operating system is larger than 1024 bytes),
+      the buffer by the operating system is larger than the size of *arg*),
       this is most likely to result in a segmentation violation or
       a more subtle data corruption.
 
@@ -125,6 +125,9 @@ The module defines the following functions:
       Add support of arbitrary :term:`bytes-like objects <bytes-like object>`,
       not only :class:`bytes`.
 
+   .. versionchanged:: next
+      The size of bytes-like objects is no longer limited to 1024 bytes.
+
 
 .. function:: ioctl(fd, request, arg=0, mutate_flag=True, /)
 
@@ -161,8 +164,7 @@ The module defines the following functions:
       If the type or size of *arg* does not match the type or size
       of the operation's argument (for example, if an integer is
       passed when a pointer is expected, or the information returned in
-      the buffer by the operating system is larger than 1024 bytes,
-      or the size of the mutable bytes-like object is too small),
+      the buffer by the operating system is larger than the size of *arg*),
       this is most likely to result in a segmentation violation or
       a more subtle data corruption.
 
@@ -185,6 +187,10 @@ The module defines the following functions:
       The GIL is always released during a system call.
       System calls failing with EINTR are automatically retried.
 
+   .. versionchanged:: next
+      The size of not mutated bytes-like objects is no longer
+      limited to 1024 bytes.
+
 .. function:: flock(fd, operation, /)
 
    Perform the lock operation *operation* on file descriptor *fd* (file objects providing

Doc/library/heapq.rst

@@ -315,6 +315,7 @@ The strange invariant above is meant to be an efficient memory representation
 for a tournament.  The numbers below are *k*, not ``a[k]``:
 
 .. figure:: heapq-binary-tree.svg
+   :class: invert-in-dark-mode
    :align: center
    :alt: Example (min-heap) binary tree.
 

Doc/library/logging.rst

@@ -1342,8 +1342,9 @@ functions.
 
 .. function:: basicConfig(**kwargs)
 
-   Does basic configuration for the logging system by creating a
-   :class:`StreamHandler` with a default :class:`Formatter` and adding it to the
+   Does basic configuration for the logging system by either creating a
+   :class:`StreamHandler` with a default :class:`Formatter`
+   or using the  given *formatter* instance, and adding it to the
    root logger. The functions :func:`debug`, :func:`info`, :func:`warning`,
    :func:`error` and :func:`critical` will call :func:`basicConfig` automatically
    if no handlers are defined for the root logger.
@@ -1428,6 +1429,19 @@ functions.
    |              | which means that it will be treated the     |
    |              | same as passing 'errors'.                   |
    +--------------+---------------------------------------------+
+   | *formatter*  | If specified, set this formatter instance   |
+   |              | (see :ref:`formatter-objects`)              |
+   |              | for all involved handlers.                  |
+   |              | If not specified, the default is to create  |
+   |              | and use an instance of                      |
+   |              | :class:`logging.Formatter` based on         |
+   |              | arguments *format*, *datefmt* and *style*.  |
+   |              | When *formatter* is specified together with |
+   |              | any of the three arguments *format*,        |
+   |              | *datefmt* and *style*, a ``ValueError`` is  |
+   |              | raised to signal that these arguments would |
+   |              | lose meaning otherwise.                     |
+   +--------------+---------------------------------------------+
 
    .. versionchanged:: 3.2
       The *style* argument was added.
@@ -1444,6 +1458,9 @@ functions.
    .. versionchanged:: 3.9
       The *encoding* and *errors* arguments were added.
 
+   .. versionchanged:: 3.15
+      The *formatter* argument was added.
+
 .. function:: shutdown()
 
    Informs the logging system to perform an orderly shutdown by flushing and

Doc/library/math.rst

@@ -144,8 +144,7 @@ Number-theoretic functions
 
 .. function:: factorial(n)
 
-   Return *n* factorial as an integer.  Raises :exc:`ValueError` if *n* is not integral or
-   is negative.
+   Return factorial of the nonnegative integer *n*.
 
    .. versionchanged:: 3.10
       Floats with integral values (like ``5.0``) are no longer accepted.

Doc/library/shutil.rst

@@ -454,6 +454,10 @@ Directory and files operations
    :envvar:`PATH` environment variable is read from :data:`os.environ`,
    falling back to :data:`os.defpath` if it is not set.
 
+   If *cmd* contains a directory component, :func:`!which` only checks the
+   specified path directly and does not search the directories listed in
+   *path* or in the system's :envvar:`PATH` environment variable.
+
    On Windows, the current directory is prepended to the *path* if *mode* does
    not include ``os.X_OK``. When the *mode* does include ``os.X_OK``, the
    Windows API ``NeedCurrentDirectoryForExePathW`` will be consulted to

Doc/library/stdtypes.rst

@@ -2269,6 +2269,18 @@ expression support in the :mod:`re` module).
       >>> '   1   2   3   '.split()
       ['1', '2', '3']
 
+   If *sep* is not specified or is ``None`` and  *maxsplit* is ``0``, only
+   leading runs of consecutive whitespace are considered.
+
+   For example::
+
+      >>> "".split(None, 0)
+      []
+      >>> "   ".split(None, 0)
+      []
+      >>> "   foo   ".split(maxsplit=0)
+      ['foo   ']
+
 
 .. index::
    single: universal newlines; str.splitlines method