numbers —- 数字抽象基类

源代码： Lib/numbers.py [https://github.com/python/cpython/tree/3.13/Lib/numbers.py]

numbers 模块 ( PEP 3141 [https://peps.python.org/pep-3141/]) 定义了数字 抽象基类 的层级结构，其中逐级定义了更多的操作。 此模块中定义的类型都不可被实例化。

  • class numbers.Number
  • 数字的层次结构的基础。 如果你只想确认参数 x 是不是数字而不关心其类型，则使用 isinstance(x, Number)。

数字的层次

  • class numbers.Complex

  • 这个类型的子类描述了复数并包括了适用于内置 complex 类型的操作。 这些操作有: 转换为 complex 和 bool, real, imag, +, -, *, /, **, abs(), conjugate(), == 以及 !=。 除 - 和 != 之外所有操作都是抽象的。

    • real

    • 抽象的。得到该数字的实数部分。

    • imag

    • 抽象的。得到该数字的虚数部分。

    • abstractmethod conjugate()

    • 抽象的。返回共轭复数。例如 (1+3j).conjugate() == (1-3j)。
  • class numbers.Real
  • 相对于 Complex，Real 加入了只适用于实数的操作。

简单的说，它们是：转化至 float，math.trunc()、 round()、 math.floor()、 math.ceil()、 divmod()、 //、 %、 <、 <=、 >、 和 >=。

实数同样默认支持 complex()、 real、 imag 和 conjugate()。

numerator 和 denominator 值应为 Integral 的实例并且应当是具有 denominator 正值的最低项。

  • numerator

  • 抽象的。

  • denominator

  • 抽象的。
  • class numbers.Integral
  • 子类型 Rational 还增加了到 int 的转换操作。 为 float(), numerator 和 denominator 提供了默认支持。 为 pow() 方法增加了求余和按位字符串运算的抽象方法: <<, >>, &, ^, |, ~。

有关类型实现的注释

实现方应当注意让相等的数值保证相等并使它们哈希运算的结果值相同。 当相互比较的实数属于两个不同的扩展模块时可能会有微妙的差异。 举例来说，fractions.Fraction 是这样实现 hash() 的:

  1. def __hash__(self):
  2.     if self.denominator == 1:
  3.         # 正确获取整数。
  4.         return hash(self.numerator)
  5.     # 高开销的检查，但肯定正确。
  6.     if self == float(self):
  7.         return hash(float(self))
  8.     else:
  9.         # 使用元组的哈希值来避免简单分数的
  10.         # 高碰撞率。
  11.         return hash((self.numerator, self.denominator))

加入更多数字的ABC

当然，这里有更多支持数字的ABC，如果不加入这些，就将缺少层次感。你可以用如下方法在 Complex 和 Real 中加入 MyFoo:

  1. class MyFoo(Complex): ...
  2. MyFoo.register(Real)

实现算术运算

我们想要实现算术运算，因此混合模式运算要么调用一个开发者知道两个参数类型的实现，要么将两个参数转换为最接近的内置类型再执行运算。 对于 Integral 的子类，这意味着 __add__() 和 __radd__() 应当被定义为:

  1. class MyIntegral(Integral):
  2.  
  3.     def __add__(self, other):
  4.         if isinstance(other, MyIntegral):
  5.             return do_my_adding_stuff(self, other)
  6.         elif isinstance(other, OtherTypeIKnowAbout):
  7.             return do_my_other_adding_stuff(self, other)
  8.         else:
  9.             return NotImplemented
  10.  
  11.     def __radd__(self, other):
  12.         if isinstance(other, MyIntegral):
  13.             return do_my_adding_stuff(other, self)
  14.         elif isinstance(other, OtherTypeIKnowAbout):
  15.             return do_my_other_adding_stuff(other, self)
  16.         elif isinstance(other, Integral):
  17.             return int(other) + int(self)
  18.         elif isinstance(other, Real):
  19.             return float(other) + float(self)
  20.         elif isinstance(other, Complex):
  21.             return complex(other) + complex(self)
  22.         else:
  23.             return NotImplemented

Complex 有 5 种不同的混合类型的操作。 我将上面提到的所有代码作为“模板”称作 MyIntegral 和 OtherTypeIKnowAbout。 a 是 Complex 的子类型 A 的实例 (a : A <: Complex)，同时 b : B <: Complex。 我将要计算 a + b:

  • 如果 A 定义了接受 b 的 __add__()，一切都没有问题。

  • 如果 A 回退至基础代码，它将返回一个来自 __add__() 的值，我们就没有机会为 B 定义更加智能的 __radd__()，因此基础代码应当从 __add__() 返回 NotImplemented。 （或者 A 可能完全不实现 __add__()。）

  • 那么 B 的 __radd__() 将有机会发挥作用。 如果它接受 a，一切都没有问题。

  • 如果没有成功回退到模板，就没有更多的方法可以去尝试，因此这里将使用默认的实现。

  • 如果 B <: A ， Python 在 A.__add__ 之前尝试 B.__radd__ 。 这是可行的，是通过对 A 的认识实现的，因此这可以在交给 Complex 处理之前处理这些实例。

如果 A <: Complex 和 B <: Real 没有共享任何其他信息，那么内置 complex 的共享操作就是最适当的，两个 __radd__() 都将应用该操作，因此 a+b == b+a。

由于对任何一直类型的大部分操作是十分相似的，可以定义一个帮助函数，即一个生成后续或相反的实例的生成器。例如，使用 fractions.Fraction 如下：

  1. def operatorfallbacks(monomorphic_operator, fallback_operator):
  2.     def forward(a, b):
  3.         if isinstance(b, (int, Fraction)):
  4.             return monomorphic_operator(a, b)
  5.         elif isinstance(b, float):
  6.             return fallback_operator(float(a), b)
  7.         elif isinstance(b, complex):
  8.             return fallback_operator(complex(a), b)
  9.         else:
  10.             return NotImplemented
  11.     forward.__name__ = '__' + fallback_operator.__name__ + '__'
  12.     forward.__doc__ = monomorphic_operator.__doc__
  13.  
  14.     def reverse(b, a):
  15.         if isinstance(a, Rational):
  16.             # Includes ints.
  17.             return monomorphic_operator(a, b)
  18.         elif isinstance(a, Real):
  19.             return fallback_operator(float(a), float(b))
  20.         elif isinstance(a, Complex):
  21.             return fallback_operator(complex(a), complex(b))
  22.         else:
  23.             return NotImplemented
  24.     reverse.__name__ = '__r' + fallback_operator.__name__ + '__'
  25.     reverse.__doc__ = monomorphic_operator.__doc__
  26.  
  27.     return forward, reverse
  28.  
  29. def _add(a, b): """a + b"""
  30.     return Fraction(a.numerator * b.denominator +
  31.                     b.numerator * a.denominator,
  32.                     a.denominator * b.denominator)
  33.  
  34. __add__, __radd__ = operatorfallbacks(_add, operator.add)
  35.  
  36. # ...