C API 棄用

背景

NumPy 為第三方擴充功能公開的 API 隨著多年的發布而成長，並允許程式設計師從 C 語言直接存取 NumPy 功能。這個 API 可以最好地描述為「有機的」。它源於多年來多個相互競爭的需求和多個觀點，深受讓使用者從 Numeric 和 Numarray 輕鬆轉移到 NumPy 的願望影響。核心 API 起源於 1995 年的 Numeric，並且存在一些模式，例如大量使用巨集來模仿 Python 的 C-API 以及考慮到 90 年代末的編譯器技術。而且只有一小群志願者有很少的時間花在改進這個 API 上。

目前正在努力改進 API。在這項努力中，重要的是確保為 NumPy 1.X 編譯的程式碼繼續為 NumPy 1.X 編譯。同時，某些 API 將被標記為已棄用，以便面向未來的程式碼可以避免這些 API 並遵循更好的實踐。

棄用標記在 C API 中扮演的另一個重要角色是朝著隱藏 NumPy 實作的內部細節發展。對於那些需要直接、輕鬆地存取 ndarray 資料的人來說，這不會消除這種能力。相反，有許多潛在的效能優化需要更改實作細節，而 NumPy 開發人員由於保持 ABI 相容性的高度價值而一直無法嘗試它們。透過棄用這種直接存取，我們未來將能夠以目前無法做到的方式提高 NumPy 的效能。

棄用機制 NPY_NO_DEPRECATED_API

在 C 語言中，沒有相當於 Python 支援的棄用警告。一種進行棄用的方法是在文件和發行說明中標記它們，然後在未來的主要版本（NumPy 2.0 及更高版本）中刪除或更改已棄用的功能。NumPy 的次要版本不應有重大的 C-API 變更，但是，這些變更會阻止在先前的次要版本上運行的程式碼。例如，我們將盡力確保在 NumPy 1.4 上編譯和運行的程式碼應繼續在 NumPy 1.7 上運行（但可能會有編譯器警告）。

要使用 NPY_NO_DEPRECATED_API 機制，您需要在 #include 任何 NumPy 標頭之前將其 #define 為 NumPy 的目標 API 版本。如果您想確認您的程式碼對 1.7 是乾淨的，請使用

#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION

在支援 #warning 機制的編譯器上，如果您未定義符號 NPY_NO_DEPRECATED_API，NumPy 會發出編譯器警告。這樣，對於可能沒有仔細閱讀發行說明的第三方開發人員來說，存在棄用的事實將被標記出來。

請注意，定義 NPY_NO_DEPRECATED_API 不足以使您的擴充功能與給定的 NumPy 版本 ABI 相容。請參閱〈針對下游套件作者〉。