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 版本使开发人员很难处理错误报告，因为我们通常不知道 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 提供的 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明确支持。

讨论#

参考文献和脚注#