plum 是 Python 中功能最完整、设计最专业的多重分派（Multiple Dispatch）库。它允许开发者为“同一个函数”定义多个实现，并根据多个参数的类型组合自动选择最匹配的版本，从而替代大量的 if isinstance(...) 判断与手写的调度逻辑。

其功能远强于 Python 内置的 functools.singledispatch，特别适合需要基于类型选择算法的领域，比如科学计算、数据流处理、解析器、框架开发等。

安装：

pip install plum-dispatch

注意：PyPI 包名为 plum-dispatch，而非 plum。

导入：

from plum import dispatch

常见应用场景：

（1）科学计算与数值算法分派

在不同参数类型需要不同计算策略时（如 float、Decimal、Fraction 等），plum 能自动选择最合适的计算版本。

（2）数据结构处理与类型敏感的操作

如 JSON、XML、DataFrame、嵌套列表等，根据对象类型自动选择不同的转换或处理逻辑。

（3）解析器与解释器

在编译器、解释器、表达式求值中，不同节点类型（如 NumberNode、BinaryOpNode）需要不同处理函数，plum 可以替代传统的 “visit_xxx” 模式，使代码更简洁。

（4）框架与插件系统

为外部用户提供统一函数名，但可根据用户传入对象的类型扩展功能。

（5）方法级分派的面向对象设计

plum 支持实例方法与类方法分派，可按 self 的类型与参数类型共同决定行为，适合框架设计、数学对象体系等场景。

（6）泛型与类型变量驱动的 API

在需要保持类型一致性的操作中（如 combine(T, T)），plum 可利用 TypeVar 自动推断类型关系。

◆  ◆  ◆

核心概念

1、多重分派（Multiple Dispatch）

依据多个参数类型组合来选定函数实现，是 plum 的核心能力。

2、类型签名（Signature）

每个 @dispatch 修饰的函数版本都绑定一个类型序列，调度器依据实参类型寻找最佳匹配。

3、类型匹配与优先级

plum 会自动计算：

• 类型继承深度

• 泛型参数精确度

• 类型具体程度

• 参数数量是否匹配

最终选择“最具体”的实现。

4、泛型与 TypeVar

plum 支持 TypeVar，允许写出类型一致性约束的重载（如两个参数必须是相同类型）。

5、方法级多重分派

支持类的实例方法与类方法，可将 self / cls 作为分派依据，使 OOP 设计更灵活。

◆  ◆  ◆

应用举例

例 1：为不同数值类型选择不同算法

from plum import dispatch
@dispatchdef area(a: int, b: int):    return a * b
@dispatchdef area(a: float, b: float):    return a * b * 0.9
print(area(4, 5))       # 20print(area(4.0, 5.0))   # 18.0

例 2：根据列表的元素类型自动选择版本

from plum import dispatch
@dispatchdef describe(data: list[int]):    return "List of integers"
@dispatchdef describe(data: list[str]):    return "List of strings"
print(describe([1, 2]))       # List of integersprint(describe(["a", "b"]))   # List of strings

例 3：利用继承体系自动选择行为

class Animal: ...class Dog(Animal): ...
from plum import dispatch
@dispatchdef speak(a: Animal):    return "Some generic sound"
@dispatchdef speak(a: Dog):    return "Woof!"
print(speak(Animal()))    # Some generic soundprint(speak(Dog()))       # Woof!

例 4：类方法中的多重分派

from plum import dispatch
class Calculator:    @dispatch    def mul(self, a: int, b: int):        return a * b    @dispatch    def mul(self, a: str, b: int):        return a * b
c = Calculator()print(c.mul(2, 3))    # 6print(c.mul("a", 4))  # aaaa

例 5：使用 typing 等创建泛型分派

from typing import List, Anyfrom numbers import Numberfrom plum import dispatch
# 1) 基本的按具体类型分派@dispatchdef combine(a: int, b: int):    return f"int add -> {a + b}"
@dispatchdef combine(a: str, b: str):    return f"str concat -> {a + b}"
# 2) 按“泛型容器类型”分派：list 中元素类型不同会命中不同实现@dispatchdef combine(a: List[int], b: List[int]):    return f"list[int] extend -> {a + b}"
@dispatchdef combine(a: List[str], b: List[str]):    return f"list[str] extend -> {a + b}"
# 3) 更通用的数值回退实现（所有 numbers.Number 子类）@dispatchdef combine(a: Number, b: Number):    return f"number fallback -> {a * b}"  # 举例：对数值做乘法作为 fallback
# 4) 一个兜底实现（任意类型）@dispatchdef combine(a: Any, b: Any):    return f"fallback -> ({a!r}, {b!r})"
# 调用示例print(combine(1, 2))                # 走 int 实现print(combine("x", "y"))            # 走 str 实现print(combine([1,2], [3,4]))        # 走 List[int] 实现print(combine(["a"], ["b"]))        # 走 List[str] 实现print(combine(2.5, 4.0))            # 走 Number 回退实现 (float 是 Number 子类)print(combine({1,2}, {3}))          # 没有 set 实现 -> 走 Any 兜底

输出示例：


int add -> 3str concat -> xylist[int] extend -> [1, 2, 3, 4]list[str] extend -> ['a', 'b']number fallback -> 10.0fallback -> ({1, 2}, {3})

◆  ◆  ◆

常用函数与类速览

dispatch(types)

注册重载版本的核心装饰器。

参数：

types：一个或多个类型，对应函数的位置参数类型。

返回：注册后的函数对象。

TypeVar(name, bound=None)

创建用于泛型与类型约束的类型变量。

参数：

name：变量名称。

bound：可选，上界类型。

返回：TypeVar 对象。

Dispatcher

内部调度器，用于管理全部类型签名与缓存。

Dispatcher.register(types, func)

显式注册一个类型签名与对应函数（高级用法）。

参数：

types：类型元组。

func：函数实现。

返回：无。

Dispatcher.dispatch(types)

根据实参类型执行分派。

参数：

types：实参类型元组。

返回：最终选中的函数对象。

Signature(types)

用于构建类型签名对象（通常无需手动使用）。

参数：

types：类型元组。

返回：Signature 实例。

◆  ◆  ◆

补充说明

（1）plum 是 Python 中最强大的多重分派工具之一，广泛用于科学计算、数据结构处理、解析器等需要“根据类型自动选算法”的系统。

（2）内置智能调度算法，可显著提升 API 美观度与可维护性。

（3）支持 Python typing 的全部主要特性，使其能很好应用于大型工程。

📘 小结

plum 是 Python 中功能完善的多重分派库，通过基于类型自动选择最合适的函数实现，使复杂的类型判断逻辑变得简洁、可维护且高度扩展。它支持同时依据多个参数类型进行调度，也支持泛型、类型变量以及类方法分派，适用于科学计算、数据解析、框架设计等需要类型驱动行为的场景。

使用 plum，开发者能够以更清晰的方式组织算法族和 API，同时大幅减少手写的 isinstance 判断，从而构建更优雅而稳健的代码结构。

“点赞有美意，赞赏是鼓励”