Merge branch 'main' into monitoring-capi

Doc/c-api/init.rst

@@ -699,7 +699,7 @@ Process-wide parameters
       It is recommended that applications embedding the Python interpreter
       for purposes other than executing a single script pass ``0`` as *updatepath*,
       and update :data:`sys.path` themselves if desired.
-      See `CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
+      See :cve:`2008-5983`.
 
       On versions before 3.1.3, you can achieve the same effect by manually
       popping the first :data:`sys.path` element after having called

Doc/c-api/tuple.rst

@@ -59,6 +59,12 @@ Tuple Objects
    Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
    negative or out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
 
+   The returned reference is borrowed from the tuple *p*
+   (that is: it is only valid as long as you hold a reference to *p*).
+   To get a :term:`strong reference`, use
+   :c:func:`Py_NewRef(PyTuple_GetItem(...)) <Py_NewRef>`
+   or :c:func:`PySequence_GetItem`.
+
 
 .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
 

Doc/c-api/typeobj.rst

@@ -1034,7 +1034,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
       the type, and the type object is INCREF'ed when a new instance is created, and
       DECREF'ed when an instance is destroyed (this does not apply to instances of
       subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
-      DECREF'ed).
+      DECREF'ed). Heap types should also :ref:`support garbage collection <supporting-cycle-detection>`
+      as they can form a reference cycle with their own module object.
 
       **Inheritance:**
 

Doc/library/ast.rst

@@ -2536,7 +2536,8 @@ to stdout.  Otherwise, the content is read from stdin.
     code that generated them. This is helpful for tools that make source code
     transformations.
 
-    `leoAst.py <https://leoeditor.com/appendices.html#leoast-py>`_ unifies the
+    `leoAst.py <https://leo-editor.github.io/leo-editor/appendices.html#leoast-py>`_
+    unifies the
     token-based and parse-tree-based views of python programs by inserting
     two-way links between tokens and ast nodes.
 
@@ -2548,4 +2549,4 @@ to stdout.  Otherwise, the content is read from stdin.
     `Parso <https://parso.readthedocs.io>`_ is a Python parser that supports
     error recovery and round-trip parsing for different Python versions (in
     multiple Python versions). Parso is also able to list multiple syntax errors
-    in your python file.
+    in your Python file.

Doc/library/bz2.rst

@@ -91,7 +91,7 @@ The :mod:`bz2` module contains:
    and :meth:`~io.IOBase.truncate`.
    Iteration and the :keyword:`with` statement are supported.
 
-   :class:`BZ2File` also provides the following methods:
+   :class:`BZ2File` also provides the following methods and attributes:
 
    .. method:: peek([n])
 
@@ -148,6 +148,19 @@ The :mod:`bz2` module contains:
 
       .. versionadded:: 3.3
 
+   .. attribute:: mode
+
+      ``'rb'`` for reading and ``'wb'`` for writing.
+
+      .. versionadded:: 3.13
+
+   .. attribute:: name
+
+      The bzip2 file name.  Equivalent to the :attr:`~io.FileIO.name`
+      attribute of the underlying :term:`file object`.
+
+      .. versionadded:: 3.13
+
 
    .. versionchanged:: 3.1
       Support for the :keyword:`with` statement was added.

Doc/library/doctest.rst

@@ -800,18 +800,18 @@ guarantee about output.  For example, when printing a set, Python doesn't
 guarantee that the element is printed in any particular order, so a test like ::
 
    >>> foo()
-   {"Hermione", "Harry"}
+   {"spam", "eggs"}
 
 is vulnerable!  One workaround is to do ::
 
-   >>> foo() == {"Hermione", "Harry"}
+   >>> foo() == {"spam", "eggs"}
    True
 
 instead.  Another is to do ::
 
    >>> d = sorted(foo())
    >>> d
-   ['Harry', 'Hermione']
+   ['eggs', 'spam']
 
 There are others, but you get the idea.
 

Doc/library/gzip.rst

@@ -133,6 +133,13 @@ The module defines the following items:
 
       .. versionadded:: 3.2
 
+   .. attribute:: mode
+
+      ``'rb'`` for reading and ``'wb'`` for writing.
+
+      .. versionchanged:: 3.13
+         In previous versions it was an integer ``1`` or ``2``.
+
    .. attribute:: mtime
 
       When decompressing, this attribute is set to the last timestamp in the most
@@ -168,14 +175,14 @@ The module defines the following items:
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
-   .. versionchanged:: 3.12
-      Remove the ``filename`` attribute, use the :attr:`~GzipFile.name`
-      attribute instead.
-
    .. deprecated:: 3.9
       Opening :class:`GzipFile` for writing without specifying the *mode*
       argument is deprecated.
 
+   .. versionchanged:: 3.12
+      Remove the ``filename`` attribute, use the :attr:`~GzipFile.name`
+      attribute instead.
+
 
 .. function:: compress(data, compresslevel=9, *, mtime=None)
 

Doc/library/lzma.rst

@@ -104,7 +104,7 @@ Reading and writing compressed files
    and :meth:`~io.IOBase.truncate`.
    Iteration and the :keyword:`with` statement are supported.
 
-   The following method is also provided:
+   The following method and attributes are also provided:
 
    .. method:: peek(size=-1)
 
@@ -117,6 +117,20 @@ Reading and writing compressed files
          file object (e.g. if the :class:`LZMAFile` was constructed by passing a
          file object for *filename*).
 
+   .. attribute:: mode
+
+      ``'rb'`` for reading and ``'wb'`` for writing.
+
+      .. versionadded:: 3.13
+
+   .. attribute:: name
+
+      The lzma file name.  Equivalent to the :attr:`~io.FileIO.name`
+      attribute of the underlying :term:`file object`.
+
+      .. versionadded:: 3.13
+
+
    .. versionchanged:: 3.4
       Added support for the ``"x"`` and ``"xb"`` modes.
 

Doc/library/pprint.rst

@@ -19,9 +19,8 @@ such as files, sockets or classes are included, as well as many other
 objects which are not representable as Python literals.
 
 The formatted representation keeps objects on a single line if it can, and
-breaks them onto multiple lines if they don't fit within the allowed width.
-Construct :class:`PrettyPrinter` objects explicitly if you need to adjust the
-width constraint.
+breaks them onto multiple lines if they don't fit within the allowed width,
+adjustable by the *width* parameter defaulting to 80 characters.
 
 Dictionaries are sorted by key before the display is computed.
 

Doc/library/statistics.rst

@@ -501,9 +501,9 @@ However, for reading convenience, most of the examples show sorted sequences.
    variance indicates that the data is spread out; a small variance indicates
    it is clustered closely around the mean.
 
-   If the optional second argument *mu* is given, it is typically the mean of
-   the *data*.  It can also be used to compute the second moment around a
-   point that is not the mean.  If it is missing or ``None`` (the default),
+   If the optional second argument *mu* is given, it should be the *population*
+   mean of the *data*.  It can also be used to compute the second moment around
+   a point that is not the mean.  If it is missing or ``None`` (the default),
    the arithmetic mean is automatically calculated.
 
    Use this function to calculate the variance from the entire population.  To
@@ -573,8 +573,8 @@ However, for reading convenience, most of the examples show sorted sequences.
    the data is spread out; a small variance indicates it is clustered closely
    around the mean.
 
-   If the optional second argument *xbar* is given, it should be the mean of
-   *data*.  If it is missing or ``None`` (the default), the mean is
+   If the optional second argument *xbar* is given, it should be the *sample*
+   mean of *data*.  If it is missing or ``None`` (the default), the mean is
    automatically calculated.
 
    Use this function when your data is a sample from a population. To calculate
@@ -590,8 +590,8 @@ However, for reading convenience, most of the examples show sorted sequences.
       >>> variance(data)
       1.3720238095238095
 
-   If you have already calculated the mean of your data, you can pass it as the
-   optional second argument *xbar* to avoid recalculation:
+   If you have already calculated the sample mean of your data, you can pass it
+   as the optional second argument *xbar* to avoid recalculation:
 
    .. doctest::
 

Doc/library/stdtypes.rst

@@ -5542,6 +5542,13 @@ types, where they are relevant.  Some of these are not reported by the
       [<class 'bool'>, <enum 'IntEnum'>, <flag 'IntFlag'>, <class 're._constants._NamedIntConstant'>]
 
 
+.. attribute:: class.__static_attributes__
+
+      A tuple containing names of attributes of this class which are accessed
+      through ``self.X`` from any function in its body.
+
+      .. versionadded:: 3.13
+
 .. _int_max_str_digits:
 
 Integer string conversion length limitation

Doc/library/tarfile.rst

@@ -565,6 +565,10 @@ be finalized; only the internally used file object will be closed. See the
    .. versionchanged:: 3.3
       Return an :class:`io.BufferedReader` object.
 
+   .. versionchanged:: 3.13
+      The returned :class:`io.BufferedReader` object has the :attr:`!mode`
+      attribute which is always equal to ``'rb'``.
+
 .. attribute:: TarFile.errorlevel
    :type: int
 
@@ -637,11 +641,15 @@ be finalized; only the internally used file object will be closed. See the
 
 .. method:: TarFile.addfile(tarinfo, fileobj=None)
 
-   Add the :class:`TarInfo` object *tarinfo* to the archive. If *fileobj* is given,
-   it should be a :term:`binary file`, and
-   ``tarinfo.size`` bytes are read from it and added to the archive.  You can
+   Add the :class:`TarInfo` object *tarinfo* to the archive. If *tarinfo* represents
+   a non zero-size regular file, the *fileobj* argument should be a :term:`binary file`,
+   and ``tarinfo.size`` bytes are read from it and added to the archive.  You can
    create :class:`TarInfo` objects directly, or by using :meth:`gettarinfo`.
 
+   .. versionchanged:: 3.13
+
+      *fileobj* must be given for non-zero-sized regular files.
+
 
 .. method:: TarFile.gettarinfo(name=None, arcname=None, fileobj=None)
 

Doc/library/typing.rst

@@ -1972,7 +1972,7 @@ without the dedicated syntax, as documented below.
       * :ref:`annotating-callables`
 
 .. data:: ParamSpecArgs
-.. data:: ParamSpecKwargs
+          ParamSpecKwargs
 
    Arguments and keyword arguments attributes of a :class:`ParamSpec`. The
    ``P.args`` attribute of a ``ParamSpec`` is an instance of ``ParamSpecArgs``,
@@ -3024,7 +3024,9 @@ Introspection helpers
 
    This is often the same as ``obj.__annotations__``. In addition,
    forward references encoded as string literals are handled by evaluating
-   them in ``globals`` and ``locals`` namespaces. For a class ``C``, return
+   them in ``globals``, ``locals`` and (where applicable)
+   :ref:`type parameter <type-params>` namespaces.
+   For a class ``C``, return
    a dictionary constructed by merging all the ``__annotations__`` along
    ``C.__mro__`` in reverse order.
 

Doc/library/zipfile.rst

@@ -301,6 +301,10 @@ ZipFile Objects
    attempting to read or write other files in the ZIP file will raise a
    :exc:`ValueError`.
 
+   In both cases the file-like object has also attributes :attr:`!name`,
+   which is equivalent to the name of a file within the archive, and
+   :attr:`!mode`, which is ``'rb'`` or ``'wb'`` depending on the input mode.
+
    When writing a file, if the file size is not known in advance but may exceed
    2 GiB, pass ``force_zip64=True`` to ensure that the header format is
    capable of supporting large files.  If the file size is known in advance,
@@ -325,6 +329,12 @@ ZipFile Objects
       Calling :meth:`.open` on a closed ZipFile will raise a :exc:`ValueError`.
       Previously, a :exc:`RuntimeError` was raised.
 
+   .. versionchanged:: 3.13
+      Added attributes :attr:`!name` and :attr:`!mode` for the writeable
+      file-like object.
+      The value of the :attr:`!mode` attribute for the readable file-like
+      object was changed from ``'r'`` to ``'rb'``.
+
 
 .. method:: ZipFile.extract(member, path=None, pwd=None)
 

Doc/reference/datamodel.rst

@@ -970,6 +970,7 @@ A class object can be called (see above) to yield a class instance (see below).
    single: __doc__ (class attribute)
    single: __annotations__ (class attribute)
    single: __type_params__ (class attribute)
+   single: __static_attributes__ (class attribute)
 
 Special attributes:
 
@@ -1000,6 +1001,10 @@ Special attributes:
       A tuple containing the :ref:`type parameters <type-params>` of
       a :ref:`generic class <generic-classes>`.
 
+   :attr:`~class.__static_attributes__`
+      A tuple containing names of attributes of this class which are accessed
+      through ``self.X`` from any function in its body.
+
 
 Class instances
 ---------------

Doc/reference/executionmodel.rst

@@ -139,8 +139,9 @@ namespace.  Names are resolved in the top-level namespace by searching the
 global namespace, i.e. the namespace of the module containing the code block,
 and the builtins namespace, the namespace of the module :mod:`builtins`.  The
 global namespace is searched first.  If the names are not found there, the
-builtins namespace is searched.  The :keyword:`!global` statement must precede
-all uses of the listed names.
+builtins namespace is searched next. If the names are also not found in the
+builtins namespace, new variables are created in the global namespace.
+The global statement must precede all uses of the listed names.
 
 The :keyword:`global` statement has the same scope as a name binding operation
 in the same block.  If the nearest enclosing scope for a free variable contains

Doc/whatsnew/3.12.rst

@@ -726,7 +726,7 @@ inspect
 
 * Add :func:`inspect.markcoroutinefunction` to mark sync functions that return
   a :term:`coroutine` for use with :func:`inspect.iscoroutinefunction`.
-  (Contributed Carlton Gibson in :gh:`99247`.)
+  (Contributed by Carlton Gibson in :gh:`99247`.)
 
 * Add :func:`inspect.getasyncgenstate` and :func:`inspect.getasyncgenlocals`
   for determining the current state of asynchronous generators.
@@ -751,8 +751,8 @@ math
   (Contributed by Raymond Hettinger in :gh:`100485`.)
 
 * Extend :func:`math.nextafter` to include a *steps* argument
-  for moving up or down multiple steps at a time.
-  (By Matthias Goergens, Mark Dickinson, and Raymond Hettinger in :gh:`94906`.)
+  for moving up or down multiple steps at a time. (Contributed by
+  Matthias Goergens, Mark Dickinson, and Raymond Hettinger in :gh:`94906`.)
 
 os
 --