[Python-checkins] gh-101100: Docs: Fix references to several numeric dunders (#106278)
AlexWaygood
webhook-mailer at python.org
Fri Jun 30 10:27:13 EDT 2023
https://github.com/python/cpython/commit/a8ae73965b02302b7661ea07a6e4f955a961aca9
commit: a8ae73965b02302b7661ea07a6e4f955a961aca9
branch: main
author: F3eQnxN3RriK <drsuaimqjgar at gmail.com>
committer: AlexWaygood <Alex.Waygood at Gmail.com>
date: 2023-06-30T15:27:09+01:00
summary:
gh-101100: Docs: Fix references to several numeric dunders (#106278)
Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>
files:
M Doc/c-api/complex.rst
M Doc/c-api/float.rst
M Doc/c-api/long.rst
M Doc/library/cmath.rst
M Doc/library/functions.rst
M Doc/library/struct.rst
diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index 344da903da4c1..cb8b270fcbab6 100644
--- a/Doc/c-api/complex.rst
+++ b/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.
diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
index 0118bea4e720f..fd0be1108c630 100644
--- a/Doc/c-api/float.rst
+++ b/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)
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 5c1d026a330ae..fe379ffe91239 100644
--- a/Doc/c-api/long.rst
+++ b/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)
diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst
index b17d58e1cc0ce..fdac51d9603ce 100644
--- a/Doc/library/cmath.rst
+++ b/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.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 3d2bb8efc95d8..9b9731e918985 100644
--- a/Doc/library/functions.rst
+++ b/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)
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index 78fd6e397ae63..6d2739b4557fb 100644
--- a/Doc/library/struct.rst
+++ b/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
More information about the Python-checkins
mailing list