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 儲存庫中。我們不僅鼓勵此類貢獻，而且我們已經為某些平台提供了最佳化的迴圈。

問： 我們想要發布比 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，明確支援此功能。

討論#

參考文獻和註腳#