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

Doc/c-api/function.rst

@@ -37,15 +37,15 @@ There are a few functions specific to Python functions.
    The function's docstring and name are retrieved from the code object. *__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
-   ``co_qualname`` field.
+   :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 ``co_qualname`` field.
+   code object's :attr:`~codeobject.co_qualname` field.
 
    .. versionadded:: 3.3
 

Doc/c-api/hash.rst

@@ -49,3 +49,13 @@ See also the :c:member:`PyTypeObject.tp_hash` member.
       :pep:`456` "Secure and interchangeable hash algorithm".
 
    .. versionadded:: 3.4
+
+
+.. c:function:: Py_hash_t Py_HashPointer(const void *ptr)
+
+   Hash a pointer value: process the pointer value as an integer (cast it to
+   ``uintptr_t`` internally). The pointer is not dereferenced.
+
+   The function cannot fail: it cannot return ``-1``.
+
+   .. versionadded:: 3.13

Doc/c-api/import.rst

@@ -154,7 +154,7 @@ Importing Modules
    :class:`~importlib.machinery.SourceFileLoader` otherwise.
 
    The module's :attr:`__file__` attribute will be set to the code object's
-   :attr:`!co_filename`.  If applicable, :attr:`__cached__` will also
+   :attr:`~codeobject.co_filename`.  If applicable, :attr:`__cached__` will also
    be set.
 
    This function will reload the module if it was already imported.  See

Doc/c-api/typeobj.rst

@@ -343,13 +343,13 @@ slot typedefs
 |                             |    :c:type:`PyTypeObject` * |                      |
 |                             |    :c:type:`Py_ssize_t`     |                      |
 +-----------------------------+-----------------------------+----------------------+
-| :c:type:`destructor`        | void *                      | void                 |
+| :c:type:`destructor`        | :c:type:`PyObject` *        | void                 |
 +-----------------------------+-----------------------------+----------------------+
 | :c:type:`freefunc`          | void *                      | void                 |
 +-----------------------------+-----------------------------+----------------------+
 | :c:type:`traverseproc`      | .. line-block::             | int                  |
 |                             |                             |                      |
-|                             |    void *                   |                      |
+|                             |    :c:type:`PyObject` *     |                      |
 |                             |    :c:type:`visitproc`      |                      |
 |                             |    void *                   |                      |
 +-----------------------------+-----------------------------+----------------------+
@@ -426,7 +426,7 @@ slot typedefs
 |                             |    :c:type:`PyObject` *     |                      |
 |                             |    :c:type:`Py_buffer` *    |                      |
 +-----------------------------+-----------------------------+----------------------+
-| :c:type:`inquiry`           | void *                      | int                  |
+| :c:type:`inquiry`           | :c:type:`PyObject` *        | int                  |
 +-----------------------------+-----------------------------+----------------------+
 | :c:type:`unaryfunc`         | .. line-block::             | :c:type:`PyObject` * |
 |                             |                             |                      |

Doc/glossary.rst

@@ -151,9 +151,9 @@ Glossary
       A :term:`file object` able to read and write
       :term:`bytes-like objects <bytes-like object>`.
       Examples of binary files are files opened in binary mode (``'rb'``,
-      ``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer`,
-      :data:`sys.stdout.buffer`, and instances of :class:`io.BytesIO` and
-      :class:`gzip.GzipFile`.
+      ``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer <sys.stdin>`,
+      :data:`sys.stdout.buffer <sys.stdout>`, and instances of
+      :class:`io.BytesIO` and :class:`gzip.GzipFile`.
 
       See also :term:`text file` for a file object able to read and write
       :class:`str` objects.
@@ -304,8 +304,9 @@ Glossary
       :ref:`class definitions <class>` for more about decorators.
 
    descriptor
-      Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or
-      :meth:`__delete__`.  When a class attribute is a descriptor, its special
+      Any object which defines the methods :meth:`~object.__get__`,
+      :meth:`~object.__set__`, or :meth:`~object.__delete__`.
+      When a class attribute is a descriptor, its special
       binding behavior is triggered upon attribute lookup.  Normally, using
       *a.b* to get, set or delete an attribute looks up the object named *b* in
       the class dictionary for *a*, but if *b* is a descriptor, the respective
@@ -319,7 +320,8 @@ Glossary
 
    dictionary
       An associative array, where arbitrary keys are mapped to values.  The
-      keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
+      keys can be any object with :meth:`~object.__hash__` and
+      :meth:`~object.__eq__` methods.
       Called a hash in Perl.
 
    dictionary comprehension
@@ -383,7 +385,7 @@ Glossary
 
    file object
       An object exposing a file-oriented API (with methods such as
-      :meth:`read()` or :meth:`write()`) to an underlying resource.  Depending
+      :meth:`!read` or :meth:`!write`) to an underlying resource.  Depending
       on the way it was created, a file object can mediate access to a real
       on-disk file or to another type of storage or communication device
       (for example standard input/output, in-memory buffers, sockets, pipes,
@@ -559,8 +561,9 @@ Glossary
 
    hashable
       An object is *hashable* if it has a hash value which never changes during
-      its lifetime (it needs a :meth:`__hash__` method), and can be compared to
-      other objects (it needs an :meth:`__eq__` method).  Hashable objects which
+      its lifetime (it needs a :meth:`~object.__hash__` method), and can be
+      compared to other objects (it needs an :meth:`~object.__eq__` method).
+      Hashable objects which
       compare equal must have the same hash value.
 
       Hashability makes an object usable as a dictionary key and a set member,
@@ -646,7 +649,8 @@ Glossary
       iterables include all sequence types (such as :class:`list`, :class:`str`,
       and :class:`tuple`) and some non-sequence types like :class:`dict`,
       :term:`file objects <file object>`, and objects of any classes you define
-      with an :meth:`__iter__` method or with a :meth:`~object.__getitem__` method
+      with an :meth:`~iterator.__iter__` method or with a
+      :meth:`~object.__getitem__` method
       that implements :term:`sequence` semantics.
 
       Iterables can be
@@ -655,7 +659,7 @@ Glossary
       as an argument to the built-in function :func:`iter`, it returns an
       iterator for the object.  This iterator is good for one pass over the set
       of values.  When using iterables, it is usually not necessary to call
-      :func:`iter` or deal with iterator objects yourself.  The ``for``
+      :func:`iter` or deal with iterator objects yourself.  The :keyword:`for`
       statement does that automatically for you, creating a temporary unnamed
       variable to hold the iterator for the duration of the loop.  See also
       :term:`iterator`, :term:`sequence`, and :term:`generator`.
@@ -666,8 +670,8 @@ Glossary
       :func:`next`) return successive items in the stream.  When no more data
       are available a :exc:`StopIteration` exception is raised instead.  At this
       point, the iterator object is exhausted and any further calls to its
-      :meth:`__next__` method just raise :exc:`StopIteration` again.  Iterators
-      are required to have an :meth:`__iter__` method that returns the iterator
+      :meth:`!__next__` method just raise :exc:`StopIteration` again.  Iterators
+      are required to have an :meth:`~iterator.__iter__` method that returns the iterator
       object itself so every iterator is also iterable and may be used in most
       places where other iterables are accepted.  One notable exception is code
       which attempts multiple iteration passes.  A container object (such as a
@@ -681,7 +685,7 @@ Glossary
       .. impl-detail::
 
          CPython does not consistently apply the requirement that an iterator
-         define :meth:`__iter__`.
+         define :meth:`~iterator.__iter__`.
 
    key function
       A key function or collation function is a callable that returns a value
@@ -875,7 +879,8 @@ Glossary
       Old name for the flavor of classes now used for all class objects.  In
       earlier Python versions, only new-style classes could use Python's newer,
       versatile features like :attr:`~object.__slots__`, descriptors,
-      properties, :meth:`__getattribute__`, class methods, and static methods.
+      properties, :meth:`~object.__getattribute__`, class methods, and static
+      methods.
 
    object
       Any data with state (attributes or value) and defined behavior
@@ -955,7 +960,7 @@ Glossary
       finders implement.
 
    path entry hook
-      A callable on the :data:`sys.path_hook` list which returns a :term:`path
+      A callable on the :data:`sys.path_hooks` list which returns a :term:`path
       entry finder` if it knows how to find modules on a specific :term:`path
       entry`.
 
@@ -1089,18 +1094,18 @@ Glossary
    sequence
       An :term:`iterable` which supports efficient element access using integer
       indices via the :meth:`~object.__getitem__` special method and defines a
-      :meth:`__len__` method that returns the length of the sequence.
+      :meth:`~object.__len__` method that returns the length of the sequence.
       Some built-in sequence types are :class:`list`, :class:`str`,
       :class:`tuple`, and :class:`bytes`. Note that :class:`dict` also
-      supports :meth:`~object.__getitem__` and :meth:`__len__`, but is considered a
+      supports :meth:`~object.__getitem__` and :meth:`!__len__`, but is considered a
       mapping rather than a sequence because the lookups use arbitrary
       :term:`immutable` keys rather than integers.
 
       The :class:`collections.abc.Sequence` abstract base class
       defines a much richer interface that goes beyond just
-      :meth:`~object.__getitem__` and :meth:`__len__`, adding :meth:`count`,
-      :meth:`index`, :meth:`__contains__`, and
-      :meth:`__reversed__`. Types that implement this expanded
+      :meth:`~object.__getitem__` and :meth:`~object.__len__`, adding
+      :meth:`count`, :meth:`index`, :meth:`~object.__contains__`, and
+      :meth:`~object.__reversed__`. Types that implement this expanded
       interface can be registered explicitly using
       :func:`~abc.ABCMeta.register`.
 

Doc/library/dis.rst

@@ -346,8 +346,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Line numbers can be decreasing. Before, they were always increasing.
 
    .. versionchanged:: 3.10
-      The :pep:`626` ``co_lines`` method is used instead of the ``co_firstlineno``
-      and ``co_lnotab`` attributes of the code object.
+      The :pep:`626` ``co_lines`` method is used instead of the
+      :attr:`~codeobject.co_firstlineno` and :attr:`~codeobject.co_lnotab`
+      attributes of the code object.
 
    .. versionchanged:: 3.13
       Line numbers can be ``None`` for bytecode that does not map to source lines.
@@ -983,13 +984,13 @@ iterations of the loop.
 .. opcode:: STORE_NAME (namei)
 
    Implements ``name = STACK.pop()``. *namei* is the index of *name* in the attribute
-   :attr:`!co_names` of the :ref:`code object <code-objects>`.
+   :attr:`~codeobject.co_names` of the :ref:`code object <code-objects>`.
    The compiler tries to use :opcode:`STORE_FAST` or :opcode:`STORE_GLOBAL` if possible.
 
 
 .. opcode:: DELETE_NAME (namei)
 
-   Implements ``del name``, where *namei* is the index into :attr:`!co_names`
+   Implements ``del name``, where *namei* is the index into :attr:`~codeobject.co_names`
    attribute of the :ref:`code object <code-objects>`.
 
 
@@ -1029,7 +1030,7 @@ iterations of the loop.
       value = STACK.pop()
       obj.name = value
 
-   where *namei* is the index of name in :attr:`!co_names` of the
+   where *namei* is the index of name in :attr:`~codeobject.co_names` of the
    :ref:`code object <code-objects>`.
 
 .. opcode:: DELETE_ATTR (namei)
@@ -1039,7 +1040,7 @@ iterations of the loop.
       obj = STACK.pop()
       del obj.name
 
-   where *namei* is the index of name into :attr:`!co_names` of the
+   where *namei* is the index of name into :attr:`~codeobject.co_names` of the
    :ref:`code object <code-objects>`.
 
 
@@ -1402,7 +1403,7 @@ iterations of the loop.
    Pushes a reference to the object the cell contains on the stack.
 
    .. versionchanged:: 3.11
-      ``i`` is no longer offset by the length of ``co_varnames``.
+      ``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`.
 
 
 .. opcode:: LOAD_FROM_DICT_OR_DEREF (i)
@@ -1424,7 +1425,7 @@ iterations of the loop.
    storage.
 
    .. versionchanged:: 3.11
-      ``i`` is no longer offset by the length of ``co_varnames``.
+      ``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`.
 
 
 .. opcode:: DELETE_DEREF (i)
@@ -1435,7 +1436,7 @@ iterations of the loop.
    .. versionadded:: 3.2
 
    .. versionchanged:: 3.11
-      ``i`` is no longer offset by the length of ``co_varnames``.
+      ``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`.
 
 
 .. opcode:: COPY_FREE_VARS (n)

Doc/library/inspect.rst

@@ -1596,8 +1596,8 @@ updated as expected:
 Code Objects Bit Flags
 ----------------------
 
-Python code objects have a ``co_flags`` attribute, which is a bitmap of
-the following flags:
+Python code objects have a :attr:`~codeobject.co_flags` attribute,
+which is a bitmap of the following flags:
 
 .. data:: CO_OPTIMIZED
 

Doc/library/reprlib.rst

@@ -10,7 +10,7 @@
 
 --------------
 
-The :mod:`reprlib` module provides a means for producing object representations
+The :mod:`!reprlib` module provides a means for producing object representations
 with limits on the size of the resulting strings. This is used in the Python
 debugger and may be useful in other contexts as well.
 
@@ -58,29 +58,31 @@ This module provides a class, an instance, and a function:
    limits on most sizes.
 
 In addition to size-limiting tools, the module also provides a decorator for
-detecting recursive calls to :meth:`__repr__` and substituting a placeholder
-string instead.
+detecting recursive calls to :meth:`~object.__repr__` and substituting a
+placeholder string instead.
 
 
 .. index:: single: ...; placeholder
 
 .. decorator:: recursive_repr(fillvalue="...")
 
-   Decorator for :meth:`__repr__` methods to detect recursive calls within the
+   Decorator for :meth:`~object.__repr__` methods to detect recursive calls within the
    same thread.  If a recursive call is made, the *fillvalue* is returned,
-   otherwise, the usual :meth:`__repr__` call is made.  For example:
-
-        >>> from reprlib import recursive_repr
-        >>> class MyList(list):
-        ...     @recursive_repr()
-        ...     def __repr__(self):
-        ...         return '<' + '|'.join(map(repr, self)) + '>'
-        ...
-        >>> m = MyList('abc')
-        >>> m.append(m)
-        >>> m.append('x')
-        >>> print(m)
-        <'a'|'b'|'c'|...|'x'>
+   otherwise, the usual :meth:`!__repr__` call is made.  For example:
+
+   .. doctest::
+
+      >>> from reprlib import recursive_repr
+      >>> class MyList(list):
+      ...     @recursive_repr()
+      ...     def __repr__(self):
+      ...         return '<' + '|'.join(map(repr, self)) + '>'
+      ...
+      >>> m = MyList('abc')
+      >>> m.append(m)
+      >>> m.append('x')
+      >>> print(m)
+      <'a'|'b'|'c'|...|'x'>
 
    .. versionadded:: 3.2
 
@@ -148,10 +150,10 @@ which format specific object types.
    with no line breaks or indentation, like the standard :func:`repr`.
    For example:
 
-   .. code-block:: pycon
+   .. doctest:: indent
 
       >>> example = [
-              1, 'spam', {'a': 2, 'b': 'spam eggs', 'c': {3: 4.5, 6: []}}, 'ham']
+      ...     1, 'spam', {'a': 2, 'b': 'spam eggs', 'c': {3: 4.5, 6: []}}, 'ham']
       >>> import reprlib
       >>> aRepr = reprlib.Repr()
       >>> print(aRepr.repr(example))
@@ -160,7 +162,7 @@ which format specific object types.
    If :attr:`~Repr.indent` is set to a string, each recursion level
    is placed on its own line, indented by that string:
 
-   .. code-block:: pycon
+   .. doctest:: indent
 
       >>> aRepr.indent = '-->'
       >>> print(aRepr.repr(example))
@@ -181,7 +183,7 @@ which format specific object types.
    Setting :attr:`~Repr.indent` to a positive integer value behaves as if it
    was set to a string with that number of spaces:
 
-   .. code-block:: pycon
+   .. doctest:: indent
 
       >>> aRepr.indent = 4
       >>> print(aRepr.repr(example))
@@ -234,7 +236,9 @@ Subclassing Repr Objects
 The use of dynamic dispatching by :meth:`Repr.repr1` allows subclasses of
 :class:`Repr` to add support for additional built-in object types or to modify
 the handling of types already supported. This example shows how special support
-for file objects could be added::
+for file objects could be added:
+
+.. testcode::
 
    import reprlib
    import sys
@@ -248,3 +252,7 @@ for file objects could be added::
 
    aRepr = MyRepr()
    print(aRepr.repr(sys.stdin))         # prints '<stdin>'
+
+.. testoutput::
+
+   <stdin>