[3.12] gh-101100: Docs: Fix references to several numeric dunders (GH-106278) (#106281)

gh-101100: Docs: Fix references to several numeric dunders (GH-106278)
(cherry picked from commit a8ae739)

Co-authored-by: F3eQnxN3RriK <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>

Author: 3 people

Doc/c-api/complex.rst

@@ -127,12 +127,12 @@ Complex Numbers as Python Objects
 
    Return the :c:type:`Py_complex` value of the complex number *op*.
 
-   If *op* is not a Python complex number object but has a :meth:`__complex__`
+   If *op* is not a Python complex number object but has a :meth:`~object.__complex__`
    method, this method will first be called to convert *op* to a Python complex
-   number object.  If ``__complex__()`` is not defined then it falls back to
-   :meth:`__float__`.  If ``__float__()`` is not defined then it falls back
-   to :meth:`__index__`.  Upon failure, this method returns ``-1.0`` as a real
+   number object.  If :meth:`!__complex__` is not defined then it falls back to
+   :meth:`~object.__float__`.  If :meth:`!__float__` is not defined then it falls back
+   to :meth:`~object.__index__`.  Upon failure, this method returns ``-1.0`` as a real
    value.
 
    .. versionchanged:: 3.8
-      Use :meth:`__index__` if available.
+      Use :meth:`~object.__index__` if available.

Doc/c-api/float.rst

@@ -45,14 +45,14 @@ Floating Point Objects
 .. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
 
    Return a C :c:expr:`double` representation of the contents of *pyfloat*.  If
-   *pyfloat* is not a Python floating point object but has a :meth:`__float__`
+   *pyfloat* is not a Python floating point object but has a :meth:`~object.__float__`
    method, this method will first be called to convert *pyfloat* into a float.
-   If ``__float__()`` is not defined then it falls back to :meth:`__index__`.
+   If :meth:`!__float__` is not defined then it falls back to :meth:`~object.__index__`.
    This method returns ``-1.0`` upon failure, so one should call
    :c:func:`PyErr_Occurred` to check for errors.
 
    .. versionchanged:: 3.8
-      Use :meth:`__index__` if available.
+      Use :meth:`~object.__index__` if available.
 
 
 .. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)

Doc/c-api/long.rst

@@ -121,7 +121,7 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
       single: OverflowError (built-in exception)
 
    Return a C :c:expr:`long` representation of *obj*.  If *obj* is not an
-   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
+   instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` method
    (if present) to convert it to a :c:type:`PyLongObject`.
 
    Raise :exc:`OverflowError` if the value of *obj* is out of range for a
@@ -130,16 +130,16 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
    .. versionchanged:: 3.8
-      Use :meth:`__index__` if available.
+      Use :meth:`~object.__index__` if available.
 
    .. versionchanged:: 3.10
-      This function will no longer use :meth:`__int__`.
+      This function will no longer use :meth:`~object.__int__`.
 
 
 .. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
 
    Return a C :c:expr:`long` representation of *obj*.  If *obj* is not an
-   instance of :c:type:`PyLongObject`, first call its :meth:`__index__`
+   instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__`
    method (if present) to convert it to a :c:type:`PyLongObject`.
 
    If the value of *obj* is greater than :const:`LONG_MAX` or less than
@@ -150,10 +150,10 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
    .. versionchanged:: 3.8
-      Use :meth:`__index__` if available.
+      Use :meth:`~object.__index__` if available.
 
    .. versionchanged:: 3.10
-      This function will no longer use :meth:`__int__`.
+      This function will no longer use :meth:`~object.__int__`.
 
 
 .. c:function:: long long PyLong_AsLongLong(PyObject *obj)
@@ -162,7 +162,7 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
       single: OverflowError (built-in exception)
 
    Return a C :c:expr:`long long` representation of *obj*.  If *obj* is not an
-   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
+   instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` method
    (if present) to convert it to a :c:type:`PyLongObject`.
 
    Raise :exc:`OverflowError` if the value of *obj* is out of range for a
@@ -171,16 +171,16 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
    .. versionchanged:: 3.8
-      Use :meth:`__index__` if available.
+      Use :meth:`~object.__index__` if available.
 
    .. versionchanged:: 3.10
-      This function will no longer use :meth:`__int__`.
+      This function will no longer use :meth:`~object.__int__`.
 
 
 .. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
 
    Return a C :c:expr:`long long` representation of *obj*.  If *obj* is not an
-   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
+   instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` method
    (if present) to convert it to a :c:type:`PyLongObject`.
 
    If the value of *obj* is greater than :const:`LLONG_MAX` or less than
@@ -193,10 +193,10 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.2
 
    .. versionchanged:: 3.8
-      Use :meth:`__index__` if available.
+      Use :meth:`~object.__index__` if available.
 
    .. versionchanged:: 3.10
-      This function will no longer use :meth:`__int__`.
+      This function will no longer use :meth:`~object.__int__`.
 
 
 .. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
@@ -267,7 +267,7 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
 .. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
 
    Return a C :c:expr:`unsigned long` representation of *obj*.  If *obj* is not
-   an instance of :c:type:`PyLongObject`, first call its :meth:`__index__`
+   an instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__`
    method (if present) to convert it to a :c:type:`PyLongObject`.
 
    If the value of *obj* is out of range for an :c:expr:`unsigned long`,
@@ -277,17 +277,17 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    disambiguate.
 
    .. versionchanged:: 3.8
-      Use :meth:`__index__` if available.
+      Use :meth:`~object.__index__` if available.
 
    .. versionchanged:: 3.10
-      This function will no longer use :meth:`__int__`.
+      This function will no longer use :meth:`~object.__int__`.
 
 
 .. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
 
    Return a C :c:expr:`unsigned long long` representation of *obj*.  If *obj*
    is not an instance of :c:type:`PyLongObject`, first call its
-   :meth:`__index__` method (if present) to convert it to a
+   :meth:`~object.__index__` method (if present) to convert it to a
    :c:type:`PyLongObject`.
 
    If the value of *obj* is out of range for an :c:expr:`unsigned long long`,
@@ -297,10 +297,10 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    to disambiguate.
 
    .. versionchanged:: 3.8
-      Use :meth:`__index__` if available.
+      Use :meth:`~object.__index__` if available.
 
    .. versionchanged:: 3.10
-      This function will no longer use :meth:`__int__`.
+      This function will no longer use :meth:`~object.__int__`.
 
 
 .. c:function:: double PyLong_AsDouble(PyObject *pylong)

Doc/library/cmath.rst

@@ -9,7 +9,7 @@
 This module provides access to mathematical functions for complex numbers.  The
 functions in this module accept integers, floating-point numbers or complex
 numbers as arguments. They will also accept any Python object that has either a
-:meth:`__complex__` or a :meth:`__float__` method: these methods are used to
+:meth:`~object.__complex__` or a :meth:`~object.__float__` method: these methods are used to
 convert the object to a complex or floating-point number, respectively, and
 the function is then applied to the result of the conversion.
 

Doc/library/functions.rst

@@ -122,7 +122,7 @@ are always available.  They are listed here in alphabetical order.
 
    Convert an integer number to a binary string prefixed with "0b". The result
    is a valid Python expression. If *x* is not a Python :class:`int` object, it
-   has to define an :meth:`__index__` method that returns an integer. Some
+   has to define an :meth:`~object.__index__` method that returns an integer. Some
    examples:
 
       >>> bin(3)
@@ -383,9 +383,9 @@ are always available.  They are listed here in alphabetical order.
    ``0j``.
 
    For a general Python object ``x``, ``complex(x)`` delegates to
-   ``x.__complex__()``.  If ``__complex__()`` is not defined then it falls back
-   to :meth:`__float__`.  If ``__float__()`` is not defined then it falls back
-   to :meth:`__index__`.
+   ``x.__complex__()``.  If :meth:`~object.__complex__` is not defined then it falls back
+   to :meth:`~object.__float__`.  If :meth:`!__float__` is not defined then it falls back
+   to :meth:`~object.__index__`.
 
    .. note::
 
@@ -400,8 +400,8 @@ are always available.  They are listed here in alphabetical order.
       Grouping digits with underscores as in code literals is allowed.
 
    .. versionchanged:: 3.8
-      Falls back to :meth:`__index__` if :meth:`__complex__` and
-      :meth:`__float__` are not defined.
+      Falls back to :meth:`~object.__index__` if :meth:`~object.__complex__` and
+      :meth:`~object.__float__` are not defined.
 
 
 .. function:: delattr(object, name)
@@ -681,8 +681,8 @@ are always available.  They are listed here in alphabetical order.
    float, an :exc:`OverflowError` will be raised.
 
    For a general Python object ``x``, ``float(x)`` delegates to
-   ``x.__float__()``.  If ``__float__()`` is not defined then it falls back
-   to :meth:`__index__`.
+   ``x.__float__()``.  If :meth:`~object.__float__` is not defined then it falls back
+   to :meth:`~object.__index__`.
 
    If no argument is given, ``0.0`` is returned.
 
@@ -708,7 +708,7 @@ are always available.  They are listed here in alphabetical order.
       *x* is now a positional-only parameter.
 
    .. versionchanged:: 3.8
-      Falls back to :meth:`__index__` if :meth:`__float__` is not defined.
+      Falls back to :meth:`~object.__index__` if :meth:`~object.__float__` is not defined.
 
 
 .. index::
@@ -822,7 +822,7 @@ are always available.  They are listed here in alphabetical order.
 
    Convert an integer number to a lowercase hexadecimal string prefixed with
    "0x". If *x* is not a Python :class:`int` object, it has to define an
-   :meth:`__index__` method that returns an integer. Some examples:
+   :meth:`~object.__index__` method that returns an integer. Some examples:
 
       >>> hex(255)
       '0xff'
@@ -893,9 +893,9 @@ are always available.  They are listed here in alphabetical order.
            int(x, base=10)
 
    Return an integer object constructed from a number or string *x*, or return
-   ``0`` if no arguments are given.  If *x* defines :meth:`__int__`,
-   ``int(x)`` returns ``x.__int__()``.  If *x* defines :meth:`__index__`,
-   it returns ``x.__index__()``.  If *x* defines :meth:`__trunc__`,
+   ``0`` if no arguments are given.  If *x* defines :meth:`~object.__int__`,
+   ``int(x)`` returns ``x.__int__()``.  If *x* defines :meth:`~object.__index__`,
+   it returns ``x.__index__()``.  If *x* defines :meth:`~object.__trunc__`,
    it returns ``x.__trunc__()``.
    For floating point numbers, this truncates towards zero.
 
@@ -932,10 +932,10 @@ are always available.  They are listed here in alphabetical order.
       *x* is now a positional-only parameter.
 
    .. versionchanged:: 3.8
-      Falls back to :meth:`__index__` if :meth:`__int__` is not defined.
+      Falls back to :meth:`~object.__index__` if :meth:`~object.__int__` is not defined.
 
    .. versionchanged:: 3.11
-      The delegation to :meth:`__trunc__` is deprecated.
+      The delegation to :meth:`~object.__trunc__` is deprecated.
 
    .. versionchanged:: 3.11
       :class:`int` string inputs and string representations can be limited to
@@ -1138,7 +1138,7 @@ are always available.  They are listed here in alphabetical order.
 
   Convert an integer number to an octal string prefixed with "0o".  The result
   is a valid Python expression. If *x* is not a Python :class:`int` object, it
-  has to define an :meth:`__index__` method that returns an integer. For
+  has to define an :meth:`~object.__index__` method that returns an integer. For
   example:
 
       >>> oct(8)

Doc/library/struct.rst

@@ -266,11 +266,11 @@ Notes:
 
 (2)
    When attempting to pack a non-integer using any of the integer conversion
-   codes, if the non-integer has a :meth:`__index__` method then that method is
+   codes, if the non-integer has a :meth:`~object.__index__` method then that method is
    called to convert the argument to an integer before packing.
 
    .. versionchanged:: 3.2
-      Added use of the :meth:`__index__` method for non-integers.
+      Added use of the :meth:`~object.__index__` method for non-integers.
 
 (3)
    The ``'n'`` and ``'N'`` conversion codes are only available for the native