SciPy API

在 Python 中，库的公共 API 和私有实现细节之间的区别并不总是很清楚。与 Java 等其他语言不同，Python 可以访问“私有”函数或对象。有时这可能很方便，但请注意，如果您这样做，您的代码可能会在将来的版本中毫无警告地中断。关于 Python 中公开和不公开的一些广泛理解的规则是：

• 名称以下划线开头的方法/函数/类和模块属性是私有的。

• 如果类名以前导下划线开头，则其成员都不是公共的，无论它们是否以前导下划线开头。

• 如果包中的模块名称以前导下划线开头，则其成员都不是公共的，无论它们是否以前导下划线开头。

• 如果一个模块或包定义了__all__，则它权威地定义了公共接口。

• 如果模块或包没有定义__all__，那么所有不以前导下划线开头的名称都是公共的。

在 SciPy 中，有些模块的名称不以下划线开头，但这应该被视为私有的。为了阐明这些是哪些模块，我们在下面定义了 SciPy 的公共 API，并就如何从 SciPy 导入模块/函数/对象给出了一些建议。

从 SciPy 导入函数的指南

scipy 命名空间本身只包含从 numpy.xml 导入的函数。为了向后兼容，这些函数仍然存在，但应该直接从 numpy 导入。

scipy 子模块命名空间中的所有内容都是公开的。一般来说，建议从子模块命名空间中导入函数。例如，函数curve_fit（在 scipy/optimize/_minpack_py.py 中定义）应该像这样导入：

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

这种导入子模块的形式是所有子模块的首选，除了 scipy.io（因为io也是 Python stdlib 中的模块名称）：

from scipy import interpolate
from scipy import integrate
import scipy.io as spio

在某些情况下，公共 API 更深一层。例如， scipy.sparse.linalg模块是公共的，它所包含的功能在命名空间中是不可用的scipy.sparse。如果从更深的一层导入函数，有时可能会导致更容易理解的代码。例如，在下文中，lomax如果选择第二种形式，则很明显这是一个分布：

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

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

在这种情况下，如果在下一节中记录了所讨论的子模块是公共的，则可以选择第二种形式。

API定义

下面列出的每个子模块都是公共的。这意味着这些子模块不太可能以不兼容的方式重命名或更改，如果有必要，将在进行更改之前为一个 SciPy 版本发出弃用警告。

• scipy.cluster

  • scipy.cluster.vq

  • scipy.cluster.hierarchy

• scipy.constants

• scipy.fft

• scipy.fftpack

• scipy.integrate

• scipy.interpolate

• scipy.io

  • scipy.io.arff

  • scipy.io.matlab

  • scipy.io.wavfile

• scipy.linalg

  • scipy.linalg.blas

  • scipy.linalg.cython_blas

  • scipy.linalg.lapack

  • scipy.linalg.cython_lapack

  • scipy.linalg.interpolative

• scipy.misc

• scipy.ndimage

• scipy.odr

• scipy.optimize

  • scipy.optimize.cython_optimize

• scipy.signal

  • scipy.signal.windows

• scipy.sparse

  • scipy.sparse.linalg

  • scipy.sparse.csgraph

• scipy.spatial

  • scipy.spatial.distance

  • scipy.spatial.transform

• scipy.special

• scipy.stats

  • scipy.stats.contingency

  • scipy.stats.distributions

  • scipy.stats.mstats

  • scipy.stats.qmc

  • scipy.stats.sampling

SciPy 结构

所有 SciPy 模块都应遵循以下约定。在下文中，SciPy 模块被定义为 Python 包，例如 yyy，位于 scipy/ 目录中。

• 理想情况下，每个 SciPy 模块都应尽可能独立。也就是说，它应该对其他包或模块具有最小的依赖关系。甚至对其他 SciPy 模块的依赖也应保持在最低限度。当然假设了对 NumPy 的依赖。

• 目录yyy/包含：

  • 为numpy.distutilssetup.py定义 configuration(parent_package='',top_path=None)函数的文件。

  • tests/包含test_<name>.py 与 modules 对应的文件的目录yyy/<name>{.py,.so,/}。

• 例如，私有模块应以下划线_为前缀yyy/_somemodule.py。

• 用户可见的函数应该具有遵循NumPy 文档风格的良好文档。

• 模块的__init__.py文档字符串中应该包含主要的参考文档。doc/这通过 Sphinx 的 automodule 指令连接到 Sphinx 文档。

  参考文档应该首先使用指令给出模块内容的分类列表autosummary::，然后解释理解模块使用的要点。

  带有大量示例的教程式文档应该分开放置在doc/source/tutorial/.

请参阅现有的 SciPy 子模块以获取指导。

有关 NumPy distutils 的更多详细信息，请参阅NumPy Distutils - 用户指南。