SPEC 2 — API 分发

描述#

此 SPEC（科学 Python 生态系统协调）关于 API 分发的建议旨在增强科学 Python 生态系统中的互操作性和性能，利用 Python entry_points 的功能。

此建议提出了一种系统方法，使用户能够无缝地将函数调用重定向到替代计算后端。这种灵活性允许用户简单地通过配置环境变量或添加额外的关键字参数（稍后详细介绍）来利用优化的实现，而不必学习新 API 的接口，这可能对“Python 用户”不太友好。这种适应性促进了硬件特定优化、用其他编程语言（如 C 或 Rust）重新实现以及利用全新数据结构的集成。

核心项目认可#

生态系统采用#

徽章#

项目可以通过包含 SPEC 徽章来突出显示他们对本 SPEC 的采用。

要使用一个徽章指示多个 SPEC 的采用，请参阅 此处。

实现#

此 SPEC 的一个成功的原型实现已集成到 NetworkX 中，体现了其核心原则。NetworkX 建立了一个灵活的分发层，能够与多个计算后端交互。目前，这包括有助于分发到 CuGraph、GraphBLAS、nx-parallel 中的并行实现以及最近添加的后端 nx-pandas 的后端。

概述：NetworkX 中的 API 分发#

1. Python entry_point 的利用 entry_point 机制是后端发现和集成的关键组成部分。通过在软件包的元数据中通过 networkx.backends entry_point 注册后端，开发人员可以使 NetworkX 能够识别并利用这些后端，而无需显式导入。示例注册

   [project.entry-points."networkx.backends"]
   your_backend_name = "your_dispatcher_class"
   

2. 后端要求 为了确保后端与 NetworkX 兼容，它必须遵守特定的结构要求

   1. 后端必须实现一个类，该类的行为类似于 nx.Graph 对象，包括一个标识后端的属性 __networkx_backend__。

   2. 后端应提供 convert_from_nx 和 convert_to_nx 方法，以促进 NetworkX 图与后端图表示之间的转换。

3. 测试后端 为了确保后端符合主要 NetworkX 的 API，鼓励开发人员在自定义后端上运行 NetworkX 测试套件。测试设置

   NETWORKX_TEST_BACKEND=<your_backend_name>
   pytest --pyargs networkx
   

4. 目前，NetworkX 中存在以下几种将函数调用分发到后端的方法

   1. 基于类型的分发

      H = nx_parallel.ParallelGraph(G)
      nx.betweenness_centrality(H)

   2. 使用 backend kwarg

      nx.betweenness_centrality(G, backend=”parallel”)

   3. 环境变量

      export NETWORKX_AUTOMATIC_BACKENDS=parallel && python nx_code.py

   4. [WIP] 将后端指定为配置参数（参考 PR#7485）

      with nx.config(backend=”parallel”):
          nx.betweenness_centrality(G)

有关更多信息，请阅读 NetworkX 的后端和配置文档！

正在进行的有趣讨论：#

• spatch 存储库
• “生态系统类型分发器的要求和讨论” 讨论
• 科学 Python 讨论 - SPEC 2

正在开发基于 Python entry_points 的后端分发的项目：#

• networkx：后端和配置文档
• scikit-image：PR#7466
• scikit-learn：PR#25535

注释#