Python自定义数值类型：深入理解__complex__复数转换协议

如果你写过自定义数值类型，大概率碰到过这个报错：

text复制TypeError: complex() argument can't be coerced to complex

明明你的对象也能表示成复数，比如一个坐标点、一个极坐标值、一个相量，可complex()偏偏不认。原因就藏在一个看起来不起眼的特殊方法里——__complex__。这篇文章我就围绕__complex__这个协议方法，把它在Python数值体系里的位置、与__float__、__index__等转换协议的协作关系、以及实际怎么写、怎么踩坑，一次聊透。

适合的读者是两类人：一类正在实现自定义数值类、几何对象、信号处理相关数据结构，想让它们无缝参与复数运算；另一类是读过官方文档但没实际动手，想知道__complex__到底在什么场景下才真正派上用场的人。我尽量用能直接跑的代码和真实报错来讲，少绕弯子。

1. 从complex()的报错现场说起：谁在决定对象能不能转复数

1.1 一个典型的失败案例

假设你定义了一个极坐标类，内部存的是模长radius和辐角phi，但希望它可以直接被转换成直角坐标形式的复数：

python复制import math

class Polar:
    def __init__(self, radius, phi):
        self.radius = float(radius)
        self.phi = float(phi)

p = Polar(2.0, math.pi / 2)
print(complex(p))

这段代码在没实现任何转换协议时会直接抛出TypeError。注意这个报错和TypeError: cannot convert 'Polar' object to complex这类提示不同，complex()的报错信息往往包含can't be coerced to complex，实际上它在告诉你：解释器已经按既定的规则查找了对象的转换方法，但一无所获。

这里要补一个基础知识点：complex()这个内建函数对“传入一个对象”和“传入一个字符串/数字”的处理路径完全不同。传入字符串时会走解析流程，比如complex("1+2j")；传入数字或自定义对象时，走的是类型转换协议。我们这里讨论的__complex__，就是自定义对象转换路径上的核心入口。

1.2 complex()在CPython里的转换链

在CPython源码中，complex(obj)最终会调用一个名为PyNumber_Complex的C函数，它不会只傻傻地查一个方法，而是按顺序尝试三条路径：

1. 如果对象实现了__complex__，调用它，并要求返回值是complex类型。
2. 如果对象没有__complex__，继续查找__index__，调用它拿到一个整数，再把这个整数封装成复数。
3. 如果__index__也没有，再尝试__float__，拿到浮点数后转成复数。

所以，__complex__不是complex()转换时唯一的救命稻草，但它是最直接、信息量最完整的手段。__index__和__float__在缺少__complex__时是降级替补，但它们的表达能力有限：一个只能出整数，一个只能出实数，都没有办法表达“实部+虚部”这种二维信息。

对应的代码验证很简单：

python复制class WithFloat:
    def __float__(self):
        return 3.14

class WithIndex:
    def __index__(self):
        return 7

class WithComplex:
    def __complex__(self):
        return 2 + 3j

print(complex(WithFloat()))    # (3.14+0j)
print(complex(WithIndex()))    # (7+0j)
print(complex(WithComplex()))  # (2+3j)

从输出能看出，WithFloat和WithIndex虽然能转成复数，但虚部永远是0，它们在转换过程中丢失了“虚数维度”。而WithComplex可以把完整的实部、虚部都表达出来，这正是__complex__存在的根本价值。

可能有人会问：__int__呢？为什么complex()的降级链里没有它？这是因为int()在转换自定义对象时有自己的一套逻辑，__int__主要服务于int(obj)，而且很多实现了__int__的对象并不适合被隐式当作复数。官方在设计数值转换协议时，明确区分了__int__和__index__，__index__才是那个被广泛用于bin()、hex()、oct()、切片以及数值转换兜底的协议。float(obj)和complex(obj)在缺少对应方法时，优先找的是__index__而不是__int__，这一点很多人会搞混。

2. 数值转换协议家族：__complex__在其中的特殊地位

2.1 四个转换协议一句话对比

在这一节，我把Python数值对象最常见的几个转换协议放在一起看，后面写自定义类型时，选择就清晰很多：

这个表格看起来简单，但里面藏着很多实际工程里会踩的点。

__index__是其中比较特殊的一个。官方文档里说它用于实现bin(x)、hex(x)、oct(x)以及operator.index()，但因为它被int()、float()、complex()都当成了降级候选，所以一个只实现了__index__的对象，在很多数值场景里会“表现得很像整数”。比如：

python复制class MyIndex:
    def __index__(self):
        return 42

print(int(MyIndex()))       # 42
print(float(MyIndex()))     # 42.0
print(complex(MyIndex()))   # (42+0j)

这是好事，也是陷阱。如果你实现了__index__但没有实现__float__，那么float(obj)能成功，是因为走了__index__的降级路径，而非你提供了符合预期的浮点转换结果。

2.2 为什么必须单独设计一个__complex__

有人可能会想：既然complex()缺省时可以靠__float__兜底，那我不实现__complex__，只实现__float__不就行了？对于只涉及实数域的对象，确实可以。但一旦对象天然带有二维属性，比如极坐标、向量、相量、复数本身，__float__的表达力就不够了。

举个例子，极坐标radius=2, phi=π/2对应直角坐标是0 + 2j，radius=2, phi=0对应的是2 + 0j。这两者如果只用__float__去表达，得到的都是同一个浮点数，在转换过程中完全丢失了相位信息。而__complex__可以精确返回0+2j和2+0j，信息量完全不同。

所以，设计一个自定义数值类型时，不要偷懒。如果你的对象在数学上确实和复数运算有关联，老老实实实现__complex__；只给一个__float__会导致隐式转换结果不可预期。同样道理，如果你的对象本质是实数，也不要去硬实现一个返回虚部恒为0的__complex__，这不必要，还可能让使用者产生误解。

2.3 __complex__与运算符重载的关系

这里必须澄清一个很常见的误解：实现了__complex__，并不代表你的对象可以直接参与+ - * /等二元运算。看这段代码：

python复制class MyNum:
    def __complex__(self):
        return 10 + 2j

n = MyNum()
print(n + complex(1, 1))

它会报错：

text复制TypeError: unsupported operand type(s) for +: 'MyNum' and 'complex'

为什么明明能转成复数，却不能直接相加？因为二元运算的分派机制走的是__add__、__radd__这些运算符重载方法，而不是__complex__。__complex__只能让你成为“可以被complex()显式转换的对象”，但Python不会在你和complex做加法时悄悄调用它。

这个设计是有道理的。如果Python在n + complex(1, 1)时自动把n转成复数再相加，那就等于强制设定了转换方向，一旦一个类可以同时被转换成多个类型（比如既能转float又能转complex），运算符就会变得混乱。正确的做法是在你的类里实现__add__、__radd__等方法，并在内部显式地借助complex()或__complex__完成转换，再做运算。后面第3节的实战案例会演示这个写法。

3. 手写一个支持__complex__的极坐标类

3.1 极坐标与复数的转换关系

前面反复提到极坐标，现在完整地把它落地成一个可以实际使用的类。数学上，极坐标(r, φ)和复数z = a + bj的转换关系是：

text复制a = r * cos(φ)
b = r * sin(φ)

反过来：

text复制r = abs(z)
φ = 复数的辐角，即 atan2(z.imag, z.real)

这个互转关系非常干净，很适合演示__complex__。我先把基础类写出来：

python复制import math
from typing import Union

class Polar:
    def __init__(self, radius: float, phi: float):
        self.radius = float(radius)
        self.phi = float(phi)

    def __complex__(self) -> complex:
        return complex(
            self.radius * math.cos(self.phi),
            self.radius * math.sin(self.phi)
        )

    def __repr__(self) -> str:
        return f"Polar(radius={self.radius:.6f}, phi={self.phi:.6f})"

__complex__内部直接用complex(实部, 虚部)构造，这个写法也符合官方的建议：返回一个真正的complex实例。这里有个细节值得留意：一定不要写成return complex(self)，那会在方法内部再次调用__complex__，形成无限递归，直接栈溢出。这种错误非常隐蔽，尤其是你后来把这个方法改成从别的属性计算时，一不留神就会踩进去。

测试一下：

python复制p = Polar(2.0, math.pi / 2)
print(complex(p))

输出：

text复制(1.2246467991473532e-16+2j)

那个1.22e-16是浮点数计算cos(π/2)时产生的正常舍入误差，不是bug。在编写几何、信号处理类数值类型时，要习惯这种微小误差的存在，尤其做相等比较时不能直接== 0，而应该用math.isclose。

3.2 扩展运算符，让对象真正参与复数运算

现在给Polar补上__add__、__mul__、__radd__，让它在和复数、整数、浮点数混合运算时表现正常。这里的核心思路：先把self和other都转成复数，在复数域完成运算，再把结果转回极坐标。

python复制class Polar:
    def __init__(self, radius: float, phi: float):
        self.radius = float(radius)
        self.phi = float(phi)

    def __complex__(self) -> complex:
        return complex(
            self.radius * math.cos(self.phi),
            self.radius * math.sin(self.phi)
        )

    @staticmethod
    def _from_complex(z: complex) -> "Polar":
        return Polar(abs(z), math.atan2(z.imag, z.real))

    def __add__(self, other) -> "Polar":
        return self._from_complex(complex(self) + complex(other))

    def __radd__(self, other) -> "Polar":
        return self._from_complex(complex(other) + complex(self))

    def __mul__(self, other) -> "Polar":
        return self._from_complex(complex(self) * complex(other))

    def __rmul__(self, other) -> "Polar":
        return self._from_complex(complex(other) * complex(self))

    def __repr__(self) -> str:
        return f"Polar(radius={self.radius:.6f}, phi={self.phi:.6f})"

这里有三个设计要点。

第一，complex(other)在other是int、float时也能正常工作，因为complex()内建函数对内置数值类型天生支持。所以Polar(1, math.pi/2) + 1这种混合写法不会报错。

第二，_from_complex这个静态方法承担了“从复数结果还原极坐标”的职责。还原时用abs(z)取模长，用math.atan2(z.imag, z.real)取辐角。注意要用atan2而不是atan，因为atan2能根据实部虚部的符号自动判断所处的象限，避免把-1 - 1j的辐角算错。

第三，__add__和__mul__都会把other强制转换成复数。如果other是一个完全无法转换的类型，比如字符串，complex(other)会抛出TypeError，这正好符合预期：加法不合法就应该报错，而不是静默返回错误结果。

实测一下：

python复制p1 = Polar(2.0, 0)      # 表示 2+0j
p2 = Polar(3.0, math.pi / 2)  # 表示 0+3j

print(p1 * p2)   # 模长 6，辐角 π/2，等价于 6j
print(p1 + p2)   # 模长 sqrt(13)，辐角 atan(3/2)

输出：

text复制Polar(radius=6.000000, phi=1.570796)
Polar(radius=3.605551, phi=0.982794)

可以看到，Polar的乘法在极坐标下天然对应“模长相乘、辐角相加”，但因为底层借用了复数的乘法，代码实现非常简洁，不需要额外写三角公式。这就是__complex__带来的实际好处：复数运算的成熟实现可以直接服务于自定义类型。

3.3 配套实现__abs__、__eq__和__hash__

数值类型的体验要完整，光有转换和运算还不够。abs(p)应该返回模长，p1 == p2应该比较两个极坐标是否表示同一个复数（考虑浮点误差），并且随之决定哈希行为。

python复制def __abs__(self) -> float:
    return self.radius

def __eq__(self, other: object) -> bool:
    if isinstance(other, Polar):
        return math.isclose(self.radius, other.radius) and math.isclose(self.phi, other.phi)
    try:
        other_complex = complex(other)
    except (TypeError, ValueError):
        return NotImplemented
    self_complex = complex(self)
    return math.isclose(self_complex.real, other_complex.real) and math.isclose(
        self_complex.imag, other_complex.imag
    )

def __hash__(self) -> int:
    return hash(complex(self))

注意一个细节：因为__eq__被重新定义了，Python会自动把__hash__置为None，导致对象不可哈希。如果你还需要把Polar放进set或当字典的键，就要手动实现__hash__。上面直接对complex(self)做哈希，能保证哈希一致性和相等语义一致：两个相等的极坐标对象，它们的复数值相同，哈希也就相同。

4. 和cmath、numpy协作时，__complex__到底起不起作用

4.1 cmath函数的参数接收

复数专用数学库cmath里的函数，比如cmath.exp、cmath.sin、cmath.sqrt，在CPython的实现里对参数处理比较宽容。实际测试时，把实现了__complex__的Polar对象直接传进去，很多情况下能正常工作：

python复制import cmath

p = Polar(2.0, math.pi / 4)
result = cmath.exp(p)
print(result)

在CPython 3.8到3.12的常见版本中，这段代码会输出类似(1.093+1.189j)的结果，因为cmath底层会尝试把非complex对象提取成复数，过程中会查找__complex__协议。

但我的建议仍然是：就算它能这么跑，也尽量显式转换：

python复制result = cmath.exp(complex(p))

原因主要有三个。第一，cmath自动识别__complex__属于CPython的实现行为，虽然稳定，但官方文档并没有把“任意可转复数的对象都能直接传给cmath函数”作为强约束写在最显眼的位置，跨实现或未来版本存在变数。第二，显式写出complex(p)，读代码的人一眼就能看出这里做了一次极坐标到复数的转换，逻辑更透明。第三，省去你自己在排查“为什么这个对象传给cmath后结果不对”时的那几分钟疑惑。

4.2 numpy数组转换的体验

数值计算里和复数打交道绕不开numpy。对于实现了__complex__的对象，numpy的标量转换函数np.complex128(obj)通常能正确识别并完成转换：

python复制import numpy as np

p = Polar(1.0, math.pi)
print(np.complex128(p))

输出：

text复制(-1+0j)

把自定义对象放进整个数组并指定复数dtype，在常见情况下也能成：

python复制arr = np.array([Polar(1.0, 0), Polar(2.0, math.pi / 2)], dtype=complex)
print(arr)

输出：

text复制[1.+0.j 0.+2.j]

不过需要说明的是，numpy的转换体系比较复杂，它还有自己的__array_interface__、__array__等协议，某些旧版本或特定数据类型下表现会有差异。如果遇到numpy没有自动调用__complex__的情况，一个非常简单的绕法是先把对象列表用列表推导式转成复数再交给numpy：

python复制arr = np.array([complex(i) for i in [Polar(1.0, 0), Polar(2.0, math.pi / 2)]], dtype=complex)

这种写法对版本的依赖最小，也最容易排查问题。工程上我倾向于“框架自动兼容”和“显式控制”之间找平衡：开发调试阶段依赖自动兼容，验证核心功能后，在性能关键路径还是优先用列表推导式或np.vectorize统一转换成原生复数。

4.3 批量转换的推荐写法

如果你有一个规模较大的Polar列表需要转换成复数数组，最自然的写法是利用map：

python复制polar_list = [Polar(i * 0.1, i) for i in range(1000)]
complex_list = list(map(complex, polar_list))

这里map(complex, polar_list)之所以有效，正是因为complex()会逐个调用对象的__complex__。你可以在这行代码上做基准测试，通常对比手写[complex(p) for p in polar_list]，两者性能差距很小，选择更顺眼的风格就好。但要注意，map(complex, polar_list)不会改变原对象，它生产的是一个全新的复数列表，这个和原地修改是两码事。

5. 落地过程中容易踩的坑

5.1 __complex__的返回值必须是complex，别指望自动帮你转

官方文档对__complex__的说明很简短：它应该返回一个complex类型的值。这里“应该”在CPython里实际上是“必须”。看这个错误实现：

python复制class BadComplex:
    def __complex__(self):
        return 3.0   # 返回了 float，不是 complex

print(complex(BadComplex()))

运行后报错信息是：

text复制TypeError: __complex__ returned non-complex (type float)

看到没有，解释器很明确地拒绝了非complex类型的返回值。不要认为“float也可以转成complex，解释器应该会宽宏大量”。我在3.10和3.12上都验证过这个行为，结论一致。所以实现的时候，最安全的写法是在方法末尾显式return complex(real, imag)，而不是返回一个元组、列表或者别的数值类型。

5.2 __complex__不是运算符的魔法开关

这个是前面提到过的高频误区，我再展开一次。有些刚接触协议方法的开发者，以为实现了__complex__后，自己的对象就能和complex实例自由运算，结果遇到TypeError后一头雾水。

正确的理解是：__complex__解决的是“显式转换”问题，而运算符分派是另一套机制。如果你想让自定义类参与加法、乘法，就必须实实在在实现__add__、__radd__等。而且这些方法内部到底用不用__complex__都取决于你的设计，它不是自动被调用的。从设计哲学上讲，这就是Python的“显式优于隐式”：转换可以做，但不能在二元运算时偷偷摸摸做。

举个例子，假设你有一个类，它的__complex__会把对象解释为“10+20j”，但你并没有实现__mul__。那么obj * complex(1, 0)就是不合法的，哪怕数学上完全说得通。遇到这种情况不要和Python讲道理，老老实实补运算符重载。

5.3 同时实现多个转换协议时，优先级是硬规则

如果一个类同时实现了__complex__、__index__、__float__，那么complex(obj)只会调用__complex__，其他方法不会参与。这个优先级是固定的，你不能通过删除某个方法去让complex()选另一个——除非你动态删除属性，但那样会让代码变得很难维护。

更需要注意的是__index__这种“隐形替补”。当你的类没有实现__complex__，但实现了__index__，那么complex(obj)会把它当成整数来转换。这在某些场景下符合直觉，在某些场景下就不太对劲。比如一个表示“角度的度数”的类，实现了__index__来支持角度取整，但它本身并没有实现__complex__，那么complex(angle_obj)得到的是一个整数复数，而不是一个以弧度为实部的复数。这种结果可能会让使用者困惑。

所以，如果你的类可能被用于数值转换，建议把四种转换协议全部梳理一遍，明确什么该实现、什么不该实现，并对不合适的转换主动抛出明确的TypeError或ValueError，而不是让降级链替你做了不符合预期的转换。

5.4 小心Fraction这类内置类型带来的误导

有一个实践场景能帮助理解转换链的边界。内置的fractions.Fraction实现了__float__，但没有实现__complex__。于是：

python复制from fractions import Fraction

z = complex(Fraction(1, 3))
print(z)  # (0.3333333333333333+0j)

它能成功，是因为降级到了__float__。但注意，这个过程丢失了Fraction的精确性。如果你在自定义类里依赖这种转换链，一定要清楚精度风险。举这个例子的目的是提醒：complex()成功转换一个对象，并不表示这个对象实现了__complex__，也不表示转换是无损的。你看到“能跑”，但底层可能已经发生了降级和精度损失。

这也是为什么我建议在实现自定义复数相关类型时，尽量把__complex__写完整、写显式。只要它存在，complex()就一定会优先使用它，转换行为和精度都受你控制，而不是被解释器的降级链牵着走。

6. 我对__complex__的使用总结

写到这里，__complex__的定位其实已经很清楚：它是自定义对象进入Python复数世界的大门。你实现了它，complex()就能理解你的对象；cmath和numpy在多数情况下也能顺藤摸瓜完成转换；更重要的是，你在自己类的运算符重载里可以随时借助它把复杂逻辑拆成“先转复数、做运算、再还原”三步，代码会简洁不少。

如果让我给一个判断标准：只要你的自定义类在数学上能和复数建立明确、无损的双向映射，就应该实现__complex__，并配套实现从复数还原的静态方法。如果映射过程中存在精度损失或者歧义，比如一个角度类既可以理解成弧度也可以理解成度数，那就三思而后行——宁可提供显式命名的to_complex()方法，也不要让complex(obj)的行为充满猜测。

最后再分享一个我实际写代码时的习惯：实现__complex__时，一定顺手把__repr__和__eq__一起写好，并且在__eq__里用math.isclose而不是==处理浮点比较。这三个方法看着独立，实际上共同决定了你的对象调试起来顺不顺手、放进集合或字典时会不会莫名其妙出问题。数值协议这一套东西，写之前觉得只是几个钩子函数，写多了就会发现它们环环相扣，设计好了，整个类型会非常“跟手”。