Merge branch 'main' into keep-trailing-slash-wip3

.github/workflows/posix-deps-apt.sh

@@ -21,6 +21,7 @@ apt-get -yq install \
     libssl-dev \
     lzma \
     lzma-dev \
+    strace \
     tk-dev \
     uuid-dev \
     xvfb \

Doc/c-api/function.rst

@@ -34,18 +34,20 @@ There are a few functions specific to Python functions.
    Return a new function object associated with the code object *code*. *globals*
    must be a dictionary with the global variables accessible to the function.
 
-   The function's docstring and name are retrieved from the code object. *__module__*
+   The function's docstring and name are retrieved from the code object.
+   :func:`~function.__module__`
    is retrieved from *globals*. The argument defaults, annotations and closure are
-   set to ``NULL``. *__qualname__* is set to the same value as the code object's
-   :attr:`~codeobject.co_qualname` field.
+   set to ``NULL``. :attr:`~function.__qualname__` is set to the same value as
+   the code object's :attr:`~codeobject.co_qualname` field.
 
 
 .. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
 
    As :c:func:`PyFunction_New`, but also allows setting the function object's
-   ``__qualname__`` attribute.  *qualname* should be a unicode object or ``NULL``;
-   if ``NULL``, the ``__qualname__`` attribute is set to the same value as the
-   code object's :attr:`~codeobject.co_qualname` field.
+   :attr:`~function.__qualname__` attribute.
+   *qualname* should be a unicode object or ``NULL``;
+   if ``NULL``, the :attr:`!__qualname__` attribute is set to the same value as
+   the code object's :attr:`~codeobject.co_qualname` field.
 
    .. versionadded:: 3.3
 
@@ -62,11 +64,12 @@ There are a few functions specific to Python functions.
 
 .. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
 
-   Return a :term:`borrowed reference` to the *__module__* attribute of the
-   function object *op*. It can be *NULL*.
+   Return a :term:`borrowed reference` to the :attr:`~function.__module__`
+   attribute of the :ref:`function object <user-defined-funcs>` *op*.
+   It can be *NULL*.
 
-   This is normally a string containing the module name, but can be set to any
-   other object by Python code.
+   This is normally a :class:`string <str>` containing the module name,
+   but can be set to any other object by Python code.
 
 
 .. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)

Doc/c-api/structures.rst

@@ -419,15 +419,15 @@ Accessing attributes of extension types
 
          The string should be static, no copy is made of it.
 
-   .. c:member:: Py_ssize_t offset
-
-      The offset in bytes that the member is located on the type’s object struct.
-
    .. c:member:: int type
 
       The type of the member in the C struct.
       See :ref:`PyMemberDef-types` for the possible values.
 
+   .. c:member:: Py_ssize_t offset
+
+      The offset in bytes that the member is located on the type’s object struct.
+
    .. c:member:: int flags
 
       Zero or more of the :ref:`PyMemberDef-flags`, combined using bitwise OR.

Doc/howto/annotations.rst

@@ -153,7 +153,8 @@ on an arbitrary object ``o``:
   unwrap it by accessing either ``o.__wrapped__`` or ``o.func`` as
   appropriate, until you have found the root unwrapped function.
 * If ``o`` is a callable (but not a class), use
-  ``o.__globals__`` as the globals when calling :func:`eval`.
+  :attr:`o.__globals__ <function.__globals__>` as the globals when calling
+  :func:`eval`.
 
 However, not all string values used as annotations can
 be successfully turned into Python values by :func:`eval`.

Doc/howto/descriptor.rst

@@ -1342,7 +1342,8 @@ Using the non-data descriptor protocol, a pure Python version of
 The :func:`functools.update_wrapper` call adds a ``__wrapped__`` attribute
 that refers to the underlying function.  Also it carries forward
 the attributes necessary to make the wrapper look like the wrapped
-function: ``__name__``, ``__qualname__``, ``__doc__``, and ``__annotations__``.
+function: :attr:`~function.__name__`, :attr:`~function.__qualname__`,
+:attr:`~function.__doc__`, and :attr:`~function.__annotations__`.
 
 .. testcode::
     :hide:
@@ -1522,8 +1523,9 @@ Using the non-data descriptor protocol, a pure Python version of
 The :func:`functools.update_wrapper` call in ``ClassMethod`` adds a
 ``__wrapped__`` attribute that refers to the underlying function.  Also
 it carries forward the attributes necessary to make the wrapper look
-like the wrapped function: ``__name__``, ``__qualname__``, ``__doc__``,
-and ``__annotations__``.
+like the wrapped function: :attr:`~function.__name__`,
+:attr:`~function.__qualname__`, :attr:`~function.__doc__`,
+and :attr:`~function.__annotations__`.
 
 
 Member objects and __slots__

Doc/library/http.cookies.rst

@@ -18,16 +18,17 @@ cookie value.
 
 The module formerly strictly applied the parsing rules described in the
 :rfc:`2109` and :rfc:`2068` specifications.  It has since been discovered that
-MSIE 3.0x doesn't follow the character rules outlined in those specs and also
-many current day browsers and servers have relaxed parsing rules when comes to
-Cookie handling.  As a result, the parsing rules used are a bit less strict.
+MSIE 3.0x didn't follow the character rules outlined in those specs; many
+current-day browsers and servers have also relaxed parsing rules when it comes
+to cookie handling.  As a result, this module now uses parsing rules that are a
+bit less strict than they once were.
 
 The character set, :data:`string.ascii_letters`, :data:`string.digits` and
 ``!#$%&'*+-.^_`|~:`` denote the set of valid characters allowed by this module
-in Cookie name (as :attr:`~Morsel.key`).
+in a cookie name (as :attr:`~Morsel.key`).
 
 .. versionchanged:: 3.3
-   Allowed ':' as a valid Cookie name character.
+   Allowed ':' as a valid cookie name character.
 
 
 .. note::
@@ -54,9 +55,10 @@ in Cookie name (as :attr:`~Morsel.key`).
 
 .. class:: SimpleCookie([input])
 
-   This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
-   and :meth:`value_encode`. SimpleCookie supports strings as cookie values.
-   When setting the value, SimpleCookie calls the builtin :func:`str()` to convert
+   This class derives from :class:`BaseCookie` and overrides :meth:`~BaseCookie.value_decode`
+   and :meth:`~BaseCookie.value_encode`. :class:`!SimpleCookie` supports
+   strings as cookie values. When setting the value, :class:`!SimpleCookie`
+   calls the builtin :func:`str` to convert
    the value to a string. Values received from HTTP are kept as strings.
 
 .. seealso::
@@ -129,17 +131,17 @@ Morsel Objects
    Abstract a key/value pair, which has some :rfc:`2109` attributes.
 
    Morsels are dictionary-like objects, whose set of keys is constant --- the valid
-   :rfc:`2109` attributes, which are
-
-   * ``expires``
-   * ``path``
-   * ``comment``
-   * ``domain``
-   * ``max-age``
-   * ``secure``
-   * ``version``
-   * ``httponly``
-   * ``samesite``
+   :rfc:`2109` attributes, which are:
+
+     .. attribute:: expires
+                    path
+                    comment
+                    domain
+                    max-age
+                    secure
+                    version
+                    httponly
+                    samesite
 
    The attribute :attr:`httponly` specifies that the cookie is only transferred
    in HTTP requests, and is not accessible through JavaScript. This is intended
@@ -152,7 +154,7 @@ Morsel Objects
    The keys are case-insensitive and their default value is ``''``.
 
    .. versionchanged:: 3.5
-      :meth:`~Morsel.__eq__` now takes :attr:`~Morsel.key` and :attr:`~Morsel.value`
+      :meth:`!__eq__` now takes :attr:`~Morsel.key` and :attr:`~Morsel.value`
       into account.
 
    .. versionchanged:: 3.7

Doc/library/inspect.rst

@@ -1225,9 +1225,10 @@ Classes and functions
    * If ``obj`` is a class, ``globals`` defaults to
      ``sys.modules[obj.__module__].__dict__`` and ``locals`` defaults
      to the ``obj`` class namespace.
-   * If ``obj`` is a callable, ``globals`` defaults to ``obj.__globals__``,
+   * If ``obj`` is a callable, ``globals`` defaults to
+     :attr:`obj.__globals__ <function.__globals__>`,
      although if ``obj`` is a wrapped function (using
-     ``functools.update_wrapper()``) it is first unwrapped.
+     :func:`functools.update_wrapper`) it is first unwrapped.
 
    Calling ``get_annotations`` is best practice for accessing the
    annotations dict of any object.  See :ref:`annotations-howto` for

Doc/library/stdtypes.rst

@@ -5384,10 +5384,10 @@ Code objects are used by the implementation to represent "pseudo-compiled"
 executable Python code such as a function body. They differ from function
 objects because they don't contain a reference to their global execution
 environment.  Code objects are returned by the built-in :func:`compile` function
-and can be extracted from function objects through their :attr:`__code__`
-attribute. See also the :mod:`code` module.
+and can be extracted from function objects through their
+:attr:`~function.__code__` attribute. See also the :mod:`code` module.
 
-Accessing ``__code__`` raises an :ref:`auditing event <auditing>`
+Accessing :attr:`~function.__code__` raises an :ref:`auditing event <auditing>`
 ``object.__getattr__`` with arguments ``obj`` and ``"__code__"``.
 
 .. index::
@@ -5461,8 +5461,9 @@ It is written as ``NotImplemented``.
 Internal Objects
 ----------------
 
-See :ref:`types` for this information.  It describes stack frame objects,
-traceback objects, and slice objects.
+See :ref:`types` for this information.  It describes
+:ref:`stack frame objects <frame-objects>`,
+:ref:`traceback objects <traceback-objects>`, and slice objects.
 
 
 .. _specialattrs:

Doc/library/tempfile.rst

@@ -18,7 +18,7 @@ This module creates temporary files and directories.  It works on all
 supported platforms. :class:`TemporaryFile`, :class:`NamedTemporaryFile`,
 :class:`TemporaryDirectory`, and :class:`SpooledTemporaryFile` are high-level
 interfaces which provide automatic cleanup and can be used as
-context managers. :func:`mkstemp` and
+:term:`context managers <context manager>`. :func:`mkstemp` and
 :func:`mkdtemp` are lower-level functions which require manual cleanup.
 
 All the user-callable functions and constructors take additional arguments which
@@ -41,7 +41,7 @@ The module defines the following user-callable items:
    this; your code should not rely on a temporary file created using this
    function having or not having a visible name in the file system.
 
-   The resulting object can be used as a context manager (see
+   The resulting object can be used as a :term:`context manager` (see
    :ref:`tempfile-examples`).  On completion of the context or
    destruction of the file object the temporary file will be removed
    from the filesystem.
@@ -87,9 +87,9 @@ The module defines the following user-callable items:
      determine whether and how the named file should be automatically deleted.
 
    The returned object is always a :term:`file-like object` whose :attr:`!file`
-   attribute is the underlying true file object. This :term:`file-like object`
+   attribute is the underlying true file object. This file-like object
    can be used in a :keyword:`with` statement, just like a normal file.  The
-   name of the temporary file can be retrieved from the :attr:`name` attribute
+   name of the temporary file can be retrieved from the :attr:`!name` attribute
    of the returned file-like object. On Unix, unlike with the
    :func:`TemporaryFile`, the directory entry does not get unlinked immediately
    after the file creation.
@@ -151,18 +151,20 @@ The module defines the following user-callable items:
    contents are written to disk and operation proceeds as with
    :func:`TemporaryFile`.
 
-   The resulting file has one additional method, :func:`rollover`, which
-   causes the file to roll over to an on-disk file regardless of its size.
+   .. method:: SpooledTemporaryFile.rollover
 
-   The returned object is a file-like object whose :attr:`_file` attribute
+      The resulting file has one additional method, :meth:`!rollover`, which
+      causes the file to roll over to an on-disk file regardless of its size.
+
+   The returned object is a file-like object whose :attr:`!_file` attribute
    is either an :class:`io.BytesIO` or :class:`io.TextIOWrapper` object
    (depending on whether binary or text *mode* was specified) or a true file
-   object, depending on whether :func:`rollover` has been called.  This
+   object, depending on whether :meth:`rollover` has been called.  This
    file-like object can be used in a :keyword:`with` statement, just like
    a normal file.
 
    .. versionchanged:: 3.3
-      the truncate method now accepts a ``size`` argument.
+      the truncate method now accepts a *size* argument.
 
    .. versionchanged:: 3.8
       Added *errors* parameter.
@@ -176,24 +178,28 @@ The module defines the following user-callable items:
 .. class:: TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False, *, delete=True)
 
    This class securely creates a temporary directory using the same rules as :func:`mkdtemp`.
-   The resulting object can be used as a context manager (see
+   The resulting object can be used as a :term:`context manager` (see
    :ref:`tempfile-examples`).  On completion of the context or destruction
    of the temporary directory object, the newly created temporary directory
    and all its contents are removed from the filesystem.
 
-   The directory name can be retrieved from the :attr:`name` attribute of the
-   returned object.  When the returned object is used as a context manager, the
-   :attr:`name` will be assigned to the target of the :keyword:`!as` clause in
-   the :keyword:`with` statement, if there is one.
-
-   The directory can be explicitly cleaned up by calling the
-   :func:`cleanup` method. If *ignore_cleanup_errors* is true, any unhandled
-   exceptions during explicit or implicit cleanup (such as a
-   :exc:`PermissionError` removing open files on Windows) will be ignored,
-   and the remaining removable items deleted on a "best-effort" basis.
-   Otherwise, errors will be raised in whatever context cleanup occurs
-   (the :func:`cleanup` call, exiting the context manager, when the object
-   is garbage-collected or during interpreter shutdown).
+   .. attribute:: TemporaryDirectory.name
+
+      The directory name can be retrieved from the :attr:`!name` attribute of the
+      returned object.  When the returned object is used as a :term:`context manager`, the
+      :attr:`!name` will be assigned to the target of the :keyword:`!as` clause in
+      the :keyword:`with` statement, if there is one.
+
+   .. method:: TemporaryDirectory.cleanup
+
+      The directory can be explicitly cleaned up by calling the
+      :meth:`!cleanup` method. If *ignore_cleanup_errors* is true, any unhandled
+      exceptions during explicit or implicit cleanup (such as a
+      :exc:`PermissionError` removing open files on Windows) will be ignored,
+      and the remaining removable items deleted on a "best-effort" basis.
+      Otherwise, errors will be raised in whatever context cleanup occurs
+      (the :meth:`!cleanup` call, exiting the context manager, when the object
+      is garbage-collected or during interpreter shutdown).
 
    The *delete* parameter can be used to disable cleanup of the directory tree
    upon exiting the context.  While it may seem unusual for a context manager

Doc/library/traceback.rst

@@ -16,7 +16,8 @@ interpreter.
 
 .. index:: pair: object; traceback
 
-The module uses traceback objects --- these are objects of type :class:`types.TracebackType`,
+The module uses :ref:`traceback objects <traceback-objects>` --- these are
+objects of type :class:`types.TracebackType`,
 which are assigned to the ``__traceback__`` field of :class:`BaseException` instances.
 
 .. seealso::
@@ -212,7 +213,8 @@ The module defines the following functions:
 
 .. function:: walk_tb(tb)
 
-   Walk a traceback following ``tb_next`` yielding the frame and line number
+   Walk a traceback following :attr:`~traceback.tb_next` yielding the frame and
+   line number
    for each frame. This helper is used with :meth:`StackSummary.extract`.
 
    .. versionadded:: 3.5

Doc/library/types.rst

@@ -378,11 +378,8 @@ Standard names are defined for the following types:
 
 .. data:: FrameType
 
-   The type of frame objects such as found in ``tb.tb_frame`` if ``tb`` is a
-   traceback object.
-
-   See :ref:`the language reference <frame-objects>` for details of the
-   available attributes and operations.
+   The type of :ref:`frame objects <frame-objects>` such as found in
+   :attr:`tb.tb_frame <traceback.tb_frame>` if ``tb`` is a traceback object.
 
 
 .. data:: GetSetDescriptorType

Doc/library/xmlrpc.server.rst

@@ -84,12 +84,12 @@ alone XML-RPC servers.
 
    Register a function that can respond to XML-RPC requests.  If *name* is given,
    it will be the method name associated with *function*, otherwise
-   ``function.__name__`` will be used.  *name* is a string, and may contain
+   :attr:`function.__name__` will be used.  *name* is a string, and may contain
    characters not legal in Python identifiers, including the period character.
 
    This method can also be used as a decorator.  When used as a decorator,
    *name* can only be given as a keyword argument to register *function* under
-   *name*.  If no *name* is given, ``function.__name__`` will be used.
+   *name*.  If no *name* is given, :attr:`function.__name__` will be used.
 
    .. versionchanged:: 3.7
       :meth:`register_function` can be used as a decorator.
@@ -298,12 +298,12 @@ requests sent to Python CGI scripts.
 
    Register a function that can respond to XML-RPC requests.  If *name* is given,
    it will be the method name associated with *function*, otherwise
-   ``function.__name__`` will be used.  *name* is a string, and may contain
+   :attr:`function.__name__` will be used.  *name* is a string, and may contain
    characters not legal in Python identifiers, including the period character.
 
    This method can also be used as a decorator.  When used as a decorator,
    *name* can only be given as a keyword argument to register *function* under
-   *name*.  If no *name* is given, ``function.__name__`` will be used.
+   *name*.  If no *name* is given, :attr:`function.__name__` will be used.
 
    .. versionchanged:: 3.7
       :meth:`register_function` can be used as a decorator.