bpo-32891: rename numbers.Integral to numbers.Integer

Doc/library/math.rst

@@ -33,7 +33,7 @@ Number-theoretic and representation functions
 
    Return the ceiling of *x*, the smallest integer greater than or equal to *x*.
    If *x* is not a float, delegates to ``x.__ceil__()``, which should return an
-   :class:`~numbers.Integral` value.
+   :class:`~numbers.Integer` value.
 
 
 .. function:: comb(n, k)
@@ -79,7 +79,7 @@ Number-theoretic and representation functions
 
    Return the floor of *x*, the largest integer less than or equal to *x*.
    If *x* is not a float, delegates to ``x.__floor__()``, which should return an
-   :class:`~numbers.Integral` value.
+   :class:`~numbers.Integer` value.
 
 
 .. function:: fmod(x, y)
@@ -299,7 +299,7 @@ Number-theoretic and representation functions
 .. function:: trunc(x)
 
    Return the :class:`~numbers.Real` value *x* truncated to an
-   :class:`~numbers.Integral` (usually an integer). Delegates to
+   :class:`~numbers.Integer` (usually an integer). Delegates to
    :meth:`x.__trunc__() <object.__trunc__>`.
 
 .. function:: ulp(x)

Doc/library/numbers.rst

@@ -2,7 +2,7 @@
 ================================================
 
 .. module:: numbers
-   :synopsis: Numeric abstract base classes (Complex, Real, Integral, etc.).
+   :synopsis: Numeric abstract base classes (Complex, Real, Integer, etc.).
 
 **Source code:** :source:`Lib/numbers.py`
 
@@ -72,13 +72,19 @@ The numeric tower
       Abstract.
 
 
-.. class:: Integral
+.. class:: Integer
 
    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: ``<<``, ``>>``, ``&``, ``^``, ``|``, ``~``.
 
+.. class:: Integral
+
+   Alias for :class:`Integer`.
+
+   .. deprecated:: 3.10
+
 
 Notes for type implementors
 ---------------------------
@@ -121,25 +127,25 @@ Implementing the arithmetic operations
 We want to implement the arithmetic operations so that mixed-mode
 operations either call an implementation whose author knew about the
 types of both arguments, or convert both to the nearest built in type
-and do the operation there. For subtypes of :class:`Integral`, this
+and do the operation there. For subtypes of :class:`Integer`, this
 means that :meth:`__add__` and :meth:`__radd__` should be defined as::
 
-    class MyIntegral(Integral):
+    class MyInteger(Integer):
 
         def __add__(self, other):
-            if isinstance(other, MyIntegral):
+            if isinstance(other, MyInteger):
                 return do_my_adding_stuff(self, other)
             elif isinstance(other, OtherTypeIKnowAbout):
                 return do_my_other_adding_stuff(self, other)
             else:
                 return NotImplemented
 
         def __radd__(self, other):
-            if isinstance(other, MyIntegral):
+            if isinstance(other, MyInteger):
                 return do_my_adding_stuff(other, self)
             elif isinstance(other, OtherTypeIKnowAbout):
                 return do_my_other_adding_stuff(other, self)
-            elif isinstance(other, Integral):
+            elif isinstance(other, Integer):
                 return int(other) + int(self)
             elif isinstance(other, Real):
                 return float(other) + float(self)
@@ -151,7 +157,7 @@ means that :meth:`__add__` and :meth:`__radd__` should be defined as::
 
 There are 5 different cases for a mixed-type operation on subclasses
 of :class:`Complex`. I'll refer to all of the above code that doesn't
-refer to ``MyIntegral`` and ``OtherTypeIKnowAbout`` as
+refer to ``MyInteger`` and ``OtherTypeIKnowAbout`` as
 "boilerplate". ``a`` will be an instance of ``A``, which is a subtype
 of :class:`Complex` (``a : A <: Complex``), and ``b : B <:
 Complex``. I'll consider ``a + b``:

Doc/library/stdtypes.rst

@@ -362,17 +362,17 @@ the following operations:
 +--------------------+---------------------------------------------+
 | Operation          | Result                                      |
 +====================+=============================================+
-| :func:`math.trunc(\| *x* truncated to :class:`~numbers.Integral` |
+| :func:`math.trunc(\| *x* truncated to :class:`~numbers.Integer`  |
 | x) <math.trunc>`   |                                             |
 +--------------------+---------------------------------------------+
 | :func:`round(x[,   | *x* rounded to *n* digits,                  |
 | n]) <round>`       | rounding half to even. If *n* is            |
 |                    | omitted, it defaults to 0.                  |
 +--------------------+---------------------------------------------+
-| :func:`math.floor(\| the greatest :class:`~numbers.Integral`     |
+| :func:`math.floor(\| the greatest :class:`~numbers.Integer`      |
 | x) <math.floor>`   | <= *x*                                      |
 +--------------------+---------------------------------------------+
-| :func:`math.ceil(x)| the least :class:`~numbers.Integral` >= *x* |
+| :func:`math.ceil(x)| the least :class:`~numbers.Integer` >= *x*  |
 | <math.ceil>`       |                                             |
 +--------------------+---------------------------------------------+
 
@@ -449,7 +449,7 @@ Notes:
 Additional Methods on Integer Types
 -----------------------------------
 
-The int type implements the :class:`numbers.Integral` :term:`abstract base
+The int type implements the :class:`numbers.Integer` :term:`abstract base
 class`. In addition, it provides a few more methods:
 
 .. method:: int.bit_length()

Doc/reference/datamodel.rst

@@ -208,7 +208,7 @@ Ellipsis
    Python distinguishes between integers, floating point numbers, and complex
    numbers:
 
-   :class:`numbers.Integral`
+   :class:`numbers.Integer`
       .. index:: object: integer
 
       These represent elements from the mathematical set of integers (positive and
@@ -2495,7 +2495,7 @@ left undefined.
    Called to implement the built-in function :func:`round` and :mod:`math`
    functions :func:`~math.trunc`, :func:`~math.floor` and :func:`~math.ceil`.
    Unless *ndigits* is passed to :meth:`!__round__` all these methods should
-   return the value of the object truncated to an :class:`~numbers.Integral`
+   return the value of the object truncated to an :class:`~numbers.Integer`
    (typically an :class:`int`).
 
    If :meth:`__int__` is not defined then the built-in function :func:`int`

Doc/whatsnew/2.6.rst

@@ -1415,7 +1415,7 @@ converted to floats.  Python 2.6 adds a simple rational-number class,
 :class:`Fraction` instead of :class:`Rational` to avoid
 a name clash with :class:`numbers.Rational`.)
 
-:class:`Integral` numbers derive from :class:`Rational`, and
+``Integral`` numbers derive from :class:`Rational`, and
 can be shifted left and right with ``<<`` and ``>>``,
 combined using bitwise operations such as ``&`` and ``|``,
 and can be used as array indexes and slice boundaries.
@@ -1424,7 +1424,7 @@ In Python 3.0, the PEP slightly redefines the existing builtins
 :func:`round`, :func:`math.floor`, :func:`math.ceil`, and adds a new
 one, :func:`math.trunc`, that's been backported to Python 2.6.
 :func:`math.trunc` rounds toward zero, returning the closest
-:class:`Integral` that's between the function's argument and zero.
+``Integral`` that's between the function's argument and zero.
 
 .. seealso::
 
@@ -1445,7 +1445,7 @@ values as a numerator and denominator forming a fraction, and can
 exactly represent numbers such as ``2/3`` that floating-point numbers
 can only approximate.
 
-The :class:`Fraction` constructor takes two :class:`Integral` values
+The :class:`Fraction` constructor takes two ``Integral`` values
 that will be the numerator and denominator of the resulting fraction. ::
 
     >>> from fractions import Fraction
@@ -2111,7 +2111,7 @@ changes, or look through the Subversion logs for all the details.
     (base *e*).
 
   * :func:`trunc` rounds a number toward zero, returning the closest
-    :class:`Integral` that's between the function's argument and zero.
+    ``Integral`` that's between the function's argument and zero.
     Added as part of the backport of
     `PEP 3141's type hierarchy for numbers <#pep-3141>`__.
 

Lib/fractions.py

@@ -171,7 +171,7 @@ def from_float(cls, f):
         Beware that Fraction.from_float(0.3) != Fraction(3, 10).
 
         """
-        if isinstance(f, numbers.Integral):
+        if isinstance(f, numbers.Integer):
             return cls(f)
         elif not isinstance(f, float):
             raise TypeError("%s.from_float() only takes floats, not %r (%s)" %
@@ -182,7 +182,7 @@ def from_float(cls, f):
     def from_decimal(cls, dec):
         """Converts a finite Decimal instance to a rational number, exactly."""
         from decimal import Decimal
-        if isinstance(dec, numbers.Integral):
+        if isinstance(dec, numbers.Integer):
             dec = Decimal(int(dec))
         elif not isinstance(dec, Decimal):
             raise TypeError(

Lib/numbers.py

@@ -7,7 +7,7 @@
 
 from abc import ABCMeta, abstractmethod
 
-__all__ = ["Number", "Complex", "Real", "Rational", "Integral"]
+__all__ = ["Number", "Complex", "Real", "Rational", "Integer", "Integral"]
 
 class Number(metaclass=ABCMeta):
     """All numbers inherit from this class.
@@ -164,32 +164,32 @@ def __float__(self):
 
     @abstractmethod
     def __trunc__(self):
-        """trunc(self): Truncates self to an Integral.
+        """trunc(self): Truncates self to an Integer.
 
-        Returns an Integral i such that:
+        Returns an Integer i such that:
           * i>0 iff self>0;
           * abs(i) <= abs(self);
-          * for any Integral j satisfying the first two conditions,
+          * for any Integer j satisfying the first two conditions,
             abs(i) >= abs(j) [i.e. i has "maximal" abs among those].
         i.e. "truncate towards 0".
         """
         raise NotImplementedError
 
     @abstractmethod
     def __floor__(self):
-        """Finds the greatest Integral <= self."""
+        """Finds the greatest Integer <= self."""
         raise NotImplementedError
 
     @abstractmethod
     def __ceil__(self):
-        """Finds the least Integral >= self."""
+        """Finds the least Integer >= self."""
         raise NotImplementedError
 
     @abstractmethod
     def __round__(self, ndigits=None):
         """Rounds self to ndigits decimal places, defaulting to 0.
 
-        If ndigits is omitted or None, returns an Integral, otherwise
+        If ndigits is omitted or None, returns an Integer, otherwise
         returns a Real. Rounds half toward even.
         """
         raise NotImplementedError
@@ -291,8 +291,8 @@ def __float__(self):
         return self.numerator / self.denominator
 
 
-class Integral(Rational):
-    """Integral adds a conversion to int and the bit-string operations."""
+class Integer(Rational):
+    """Integer adds a conversion to int and the bit-string operations."""
 
     __slots__ = ()
 
@@ -311,7 +311,7 @@ def __pow__(self, exponent, modulus=None):
 
         Accept the modulus argument if you want to support the
         3-argument version of pow(). Raise a TypeError if exponent < 0
-        or any argument isn't Integral. Otherwise, just implement the
+        or any argument isn't Integer. Otherwise, just implement the
         2-argument version described in Complex.
         """
         raise NotImplementedError
@@ -386,4 +386,7 @@ def denominator(self):
         """Integers have a denominator of 1."""
         return 1
 
-Integral.register(int)
+Integer.register(int)
+
+# Compatibility alias.
+Integral = Integer

Lib/pydoc_data/topics.py

@@ -7870,7 +7870,7 @@
                   '*ndigits* is\n'
                   '   passed to "__round__()" all these methods should return '
                   'the value\n'
-                  '   of the object truncated to an "Integral" (typically an '
+                  '   of the object truncated to an "Integer" (typically an '
                   '"int").\n'
                   '\n'
                   '   If "__int__()" is not defined then the built-in function '
@@ -10592,7 +10592,7 @@
                  '*ndigits* is\n'
                  '   passed to "__round__()" all these methods should return '
                  'the value\n'
-                 '   of the object truncated to an "Integral" (typically an '
+                 '   of the object truncated to an "Integer" (typically an '
                  '"int").\n'
                  '\n'
                  '   If "__int__()" is not defined then the built-in function '
@@ -12316,7 +12316,7 @@
           'and\n'
           '   complex numbers:\n'
           '\n'
-          '   "numbers.Integral"\n'
+          '   "numbers.Integer"\n'
           '      These represent elements from the mathematical set of '
           'integers\n'
           '      (positive and negative).\n'

Lib/statistics.py

@@ -258,7 +258,7 @@ def _exact_ratio(x):
         if type(x) is float or type(x) is Decimal:
             return x.as_integer_ratio()
         try:
-            # x may be an int, Fraction, or Integral ABC.
+            # x may be an int, Fraction, or Integer ABC.
             return (x.numerator, x.denominator)
         except AttributeError:
             try:

Lib/test/test_abstract_numbers.py

@@ -3,10 +3,11 @@
 import math
 import operator
 import unittest
-from numbers import Complex, Real, Rational, Integral
+from numbers import Complex, Real, Rational, Integer, Integral
 
 class TestNumbers(unittest.TestCase):
     def test_int(self):
+        self.assertTrue(issubclass(int, Integer))
         self.assertTrue(issubclass(int, Integral))
         self.assertTrue(issubclass(int, Complex))
 

Lib/test/test_int.py

@@ -396,20 +396,20 @@ def __trunc__(self):
                         return Intable()
                 self.assertEqual(int(TruncReturnsNonInt()), 42)
 
-                class NonIntegral(trunc_result_base):
+                class NonInteger(trunc_result_base):
                     def __trunc__(self):
                         # Check that we avoid infinite recursion.
-                        return NonIntegral()
+                        return NonInteger()
 
-                class TruncReturnsNonIntegral(base):
+                class TruncReturnsNonInteger(base):
                     def __trunc__(self):
-                        return NonIntegral()
+                        return NonInteger()
                 try:
-                    int(TruncReturnsNonIntegral())
+                    int(TruncReturnsNonInteger())
                 except TypeError as e:
                     self.assertEqual(str(e),
-                                      "__trunc__ returned non-Integral"
-                                      " (type NonIntegral)")
+                                      "__trunc__ returned non-Integer"
+                                      " (type NonInteger)")
                 else:
                     self.fail("Failed to raise TypeError with %s" %
                               ((base, trunc_result_base),))

Misc/NEWS.d/3.10.0a1.rst

@@ -2566,7 +2566,7 @@ with other number types.
 .. section: Library
 
 The x.is_integer() method is incorporated into the abstract types of the
-numeric tower, Real, Rational and Integral, with appropriate default
+numeric tower, Real, Rational and Integer, with appropriate default
 implementations.
 
 ..

Misc/NEWS.d/next/Library/2021-04-22-11-01-25.bpo-32891.fQqX89.rst

@@ -0,0 +1,2 @@
+Added :class:`~numbers.Integer` as a synonym for old :class:`~numbers.Integral`,
+which is deprecated.  Contributed by Sergey B Kirpichev.