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 名称使用的限制

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

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

公司和开发者在阅读本 NEP 后将了解社区希望看到的行为类型，以及我们认为令人烦恼、麻烦和不可接受的行为。

动机#

我们不时会得知由外部人士修改并分发的 NumPy 版本。这些修补过的版本可能会给 NumPy 社区带来问题（例如，请参见 [1] 和 [2]）。当出现此类问题时，我们的开发者会浪费时间来识别有问题的版本、定位更改并确定适当的应对措施。

此外，Python 包索引上的软件包有时会以一种使用户误以为它们得到 NumPy 认可或维护的方式命名。我们希望减少此类事件的数量。

在 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 可以明确支持这一点。

讨论#

参考文献和脚注#