NEP 36 — 公平竞争#

作者:

Stéfan van der Walt <stefanv@berkeley.edu>

状态:

活动

类型:

信息

创建:

2019-10-24

解决:

https://mail.python.org/pipermail/numpy-discussion/2021-June/081890.html

摘要#

本文概述了参与 NumPy 项目的公司和外部开发者的游戏规则。它涵盖了

  • NumPy 命名使用的限制

  • 如何以及是否发布修改后的发行版

  • 如何让我们了解已修补的版本

阅读本文档后，公司和开发人员将了解社区希望看到哪些行为，以及我们认为哪些行为令人困扰、麻烦和不可接受。

动机#

我们偶尔会了解到外部人员修改和传播的 NumPy 版本。这些修补过的版本可能会给 NumPy 社区带来问题（例如，参见 [1] 和 [2]）。当出现此类问题时，我们的开发人员会浪费时间识别有问题的版本、定位修改并确定适当的行动方案。

此外，Python 包索引上的包有时命名为，使用户认为它们是由 NumPy 批准或维护的。我们希望减少此类事件的发生。

在 2019 年 10 月 16 日的社区电话会议中 （2019 年 10 月 16 日），社区决定起草指南来解决这些问题。

范围#

本文档旨在定义一组最小的规则，遵循这些规则将被视为符合 NumPy 开发人员期望的良好信誉行为。

我们的希望是，认为需要修改 NumPy 的开发人员首先考虑为该项目做出贡献，或者使用几种现有的机制来扩展我们的 API 以及对外部定义的数组对象进行操作。

如有疑问，请 先与我们联系。我们可能会建议一个替代方案；至少，我们将做好准备。

公平竞争规则#

  1. 不要将 NumPy 名称用于 NumPy 社区未开发的项目。

    截至撰写本文时，社区开发的 `numpy` 命名包只有少数几个，包括 `numpy`、`numpy-financial` 和 `unumpy`。我们要求外部包不包含短语 `numpy`，即避免名称，例如 `mycompany_numpy`。

    需要明确的是，此规则仅适用于模块（包名称）；拥有名为 `mylibrary.numpy` 的子模块完全可以。

    NumPy 是 NumFOCUS 拥有的商标。

  2. 不要重新发布修改后的 NumPy 版本。

    修改后的 NumPy 版本使得开发人员难以处理 bug 报告，因为我们通常不知道 NumPy 的哪些部分已被修改。

    如果您必须违反此规则（我们恳请您不要这样做！），请在 `__version__` 标签中清楚地说明您已修改了 NumPy，例如

    >>> print(np.__version__)
'1.17.2+mycompany.15`

    我们理解，在发行版内部，通常需要进行一些小修补以使库正常工作。例如，Debian 可能会修补 NumPy，使其在正确的位置搜索优化的 BLAS 库。这是可以接受的，但我们要求不要进行实质性更改。

  3. 不要扩展或修改 NumPy 的 API。

    如果您绝对必须违反规则二，请勿向命名空间添加其他函数，或修改现有函数的 API。NumPy 的 API 已经相当庞大，我们正在努力在可行的情况下减少它。在分布式版本中公开额外的函数会让用户和开发人员感到困惑。

  4. 确实 使用官方机制与 API 交互。

    诸如 __array_ufunc__ 和 __array_function__ 等协议旨在帮助外部包更容易地与 NumPy 交互。例如，后者允许来自外部库的对象通过 NumPy。我们积极鼓励使用这些“官方认可”的机制来覆盖或与 NumPy 交互。

    如果这些机制被认为是不够的，请在猴子补丁 NumPy 之前在邮件列表上开始讨论。

问题和答案#

问：我们想分发一个利用我们公司 CPU 的特殊指令的优化 NumPy 版本。您建议不要这样做，那么我们该怎么办？

答：请考虑将所需的补丁包含在官方 NumPy 存储库中。我们不仅鼓励做出此类贡献，而且我们已经为某些平台提供了优化的循环。

问：我们想分发比 NumPy 提供的 FFT 快得多的版本，但 NumPy 没有任何机制来覆盖其 FFT 例程。我们该怎么办？

答：我们批准了两种解决方案：让用户使用以下代码片段安装您的优化。

from my_company_accel import patch_numpy_fft
patch_numpy_fft()

或者让您的发行版自动执行上述操作，但要向终端打印一条清晰的消息，说明正在发生什么。

We are now patching NumPy for optimal performance under MyComp
Special Platform.  Please direct all bug reports to
https://mycomp.com/numpy-bugs

如果您需要额外的机制来覆盖代码，请在邮件列表上与开发团队讨论。

问：我们想分发具有更快线性代数例程的 NumPy。我们允许这样做吗？

答：是的，这明确地支持链接到不同的 BLAS 版本。

讨论#

参考资料和脚注#

此页上的内容