Ctrl+K

SciPy API#

從 SciPy 匯入#

在 Python 中，程式庫的公開 API 和私有實作細節之間的區別並不總是那麼明確。與其他語言（如 Java）不同，在 Python 中可以存取「私有」函式或物件。有時這可能很方便，但請注意，如果您這樣做，您的程式碼可能會在未來的版本中無預警地損壞。以下是一些廣為人知的規則，說明在 Python 中哪些是公開的，哪些不是：

  • 名稱以底線開頭的方法／函式／類別和模組屬性是私有的。

  • 如果類別名稱以底線開頭，則其所有成員都不是公開的，無論它們是否以底線開頭。

  • 如果套件中的模組名稱以底線開頭，則其所有成員都不是公開的，無論它們是否以底線開頭。

  • 如果模組或套件定義了 __all__，則它權威地定義了公共介面。

  • 如果模組或套件沒有定義 __all__，則所有不以底線開頭的名稱都是公開的。

注意

閱讀上述指南，人們可能會得出結論，每個私有模組或物件都以底線開頭。情況並非如此；底線的存在確實將某事物標記為私有，但底線的缺失並不將某事物標記為公開。

在 SciPy 中，有些模組的名稱沒有以底線開頭，但應該被視為私有的。為了澄清這些模組是哪些，我們在下面定義了 SciPy 的公開 API 是什麼，並就如何從 SciPy 匯入模組／函式／物件提供了一些建議。

從 SciPy 匯入函式的指南#

SciPy 子模組命名空間中的所有內容都是公開的。通常在 Python 中，建議使用命名空間。例如，函式 curve_fit（定義在 scipy/optimize/_minpack_py.py 中）應該像這樣匯入

import scipy
result = scipy.optimize.curve_fit(...)

或者，可以像這樣使用子模組作為命名空間

from scipy import optimize
result = optimize.curve_fit(...)

注意

對於 scipy.io，建議使用 import scipy，因為 io 也是 Python stdlib 中模組的名稱。

在某些情況下，公開 API 會更深一層。例如，scipy.sparse.linalg 模組是公開的，並且它包含的函式在 scipy.sparse 命名空間中不可用。有時，如果從更深一層匯入函式，可能會產生更容易理解的程式碼。例如，在以下程式碼中，如果選擇第二種形式，則立即清楚 lomax 是一種分佈

# first form
from scipy import stats
stats.lomax(...)

# second form
from scipy.stats import distributions
distributions.lomax(...)

在這種情況下，如果下一節中記錄了所討論的子模組是公開的，則可以選擇第二種形式。當然，您仍然可以使用

import scipy
scipy.stats.lomax(...)
# or
scipy.stats.distributions.lomax(...)

注意

SciPy 使用延遲載入機制，這表示模組僅在您第一次嘗試存取它們時才載入記憶體。

API 定義#

下面列出的每個子模組都是公開的。這表示這些子模組不太可能被重新命名或以不相容的方式更改，如果確實有必要，則會在進行更改之前的一個 SciPy 版本中發出棄用警告。

SciPy 結構#

所有 SciPy 模組都應遵循以下慣例。在下文中，「SciPy 模組」定義為位於 scipy/ 目錄中的 Python 套件，例如 yyy。

  • 理想情況下，每個 SciPy 模組都應盡可能自我包含。也就是說，它應該盡可能減少對其他套件或模組的依賴。即使是對其他 SciPy 模組的依賴也應保持在最低限度。當然，假設依賴 NumPy。

  • 目錄 yyy/ 包含

    • 一個檔案 meson.build，其中包含子模組的建置配置。

    • 一個目錄 tests/，其中包含對應於模組 yyy/<name>{.py,.so,/} 的檔案 test_<name>.py。

  • 私有模組應以底線 _ 作為前綴，例如 yyy/_somemodule.py。

  • 使用者可見的函式應具有良好的文件，並遵循 NumPy 文件風格。

  • 模組的 __init__.py 應在其 docstring 中包含主要參考文件。這透過 Sphinx 的 automodule 指令連接到 doc/ 下的 Sphinx 文件。

    參考文件應首先使用 autosummary:: 指令提供模組內容的分類列表，然後解釋理解模組使用方式的要點。

    具有大量範例的教學風格文件應分開，並放在 doc/source/tutorial/ 下。

有關指南，請參閱現有的 SciPy 子模組。

在本頁中