From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Fri, 14 May 2021 22:22:45 +0000 (-0700)
Subject: bpo-44072: fix Complex, Integral docs for `**` (GH-25986)
X-Git-Tag: v3.10.0b2~89
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=2e99869f64bbd3c6590cb5ceaf9cf59e63689d63;p=thirdparty%2FPython%2Fcpython.git

bpo-44072: fix Complex, Integral docs for `**` (GH-25986)


In numbers module docstrings and docs.
(cherry picked from commit 4aa63d65a9971d14f1a2131b989dca0dab514a9d)

Co-authored-by: Rory Yorke <rory.yorke@gmail.com>
---

diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst
index 1b594952ead7..d37123c35476 100644
--- a/Doc/library/numbers.rst
+++ b/Doc/library/numbers.rst
@@ -27,8 +27,8 @@ The numeric tower
    Subclasses of this type describe complex numbers and include the operations
    that work on the built-in :class:`complex` type. These are: conversions to
    :class:`complex` and :class:`bool`, :attr:`.real`, :attr:`.imag`, ``+``,
-   ``-``, ``*``, ``/``, :func:`abs`, :meth:`conjugate`, ``==``, and ``!=``. All
-   except ``-`` and ``!=`` are abstract.
+   ``-``, ``*``, ``/``, ``**``, :func:`abs`, :meth:`conjugate`, ``==``, and
+   ``!=``. All except ``-`` and ``!=`` are abstract.
 
    .. attribute:: real
 
@@ -76,8 +76,9 @@ The numeric tower
 
    Subtypes :class:`Rational` and adds a conversion to :class:`int`.  Provides
    defaults for :func:`float`, :attr:`~Rational.numerator`, and
-   :attr:`~Rational.denominator`.  Adds abstract methods for ``**`` and
-   bit-string operations: ``<<``, ``>>``, ``&``, ``^``, ``|``, ``~``.
+   :attr:`~Rational.denominator`.  Adds abstract methods for :func:`pow` with
+   modulus and bit-string operations: ``<<``, ``>>``, ``&``, ``^``, ``|``,
+   ``~``.
 
 
 Notes for type implementors
diff --git a/Lib/numbers.py b/Lib/numbers.py
index ed815ef41ebe..5b98e642083b 100644
--- a/Lib/numbers.py
+++ b/Lib/numbers.py
@@ -33,7 +33,7 @@ class Complex(Number):
     """Complex defines the operations that work on the builtin complex type.
 
     In short, those are: a conversion to complex, .real, .imag, +, -,
-    *, /, abs(), .conjugate, ==, and !=.
+    *, /, **, abs(), .conjugate, ==, and !=.
 
     If it is given heterogeneous arguments, and doesn't have special
     knowledge about them, it should fall back to the builtin complex
@@ -292,7 +292,11 @@ class Rational(Real):
 
 
 class Integral(Rational):
-    """Integral adds a conversion to int and the bit-string operations."""
+    """Integral adds methods that work on integral numbers.
+
+    In short, these are conversion to int, pow with modulus, and the
+    bit-string operations.
+    """
 
     __slots__ = ()
 
diff --git a/Misc/NEWS.d/next/Documentation/2021-05-08-09-48-05.bpo-44072.fb2x5I.rst b/Misc/NEWS.d/next/Documentation/2021-05-08-09-48-05.bpo-44072.fb2x5I.rst
new file mode 100644
index 000000000000..a5b0c95d85e6
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-05-08-09-48-05.bpo-44072.fb2x5I.rst
@@ -0,0 +1,2 @@
+Correct where in the numeric ABC hierarchy ``**`` support is added, i.e., in
+numbers.Complex, not numbers.Integral.