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 标准库中一个模块的名称。

在某些情况下，公共 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 模块 被定义为一个 Python 包，例如 yyy，它位于 scipy/ 目录下。

理想情况下，每个 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 子模块以获取指导。