SciPy API¶
从SciPy导入¶
在Python中,什么是库的公共API和什么是私有实现细节之间的区别并不总是很清楚。与Java等其他语言不同,在Python中可以访问“私有”函数或对象。偶尔这可能会很方便,但请注意,如果这样做,您的代码可能会在未来版本中毫无警告地崩溃。关于Python中哪些是公共的,哪些不是公共的,一些广为人知的规则包括:
名称以前导下划线开头的方法/函数/类和模块属性是私有的。
如果类名以前导下划线开头,则其成员都不是公共的,无论它们是否以前导下划线开头。
如果包中的模块名称以前导下划线开头,则其成员都不是公共的,无论它们是否以前导下划线开头。
如果模块或包定义
__all__
,它权威性地定义了公共接口。如果模块或包没有定义
__all__
,则所有不以前导下划线开头的名称都是公开的。
注解
阅读上述指南可以得出结论,每个私有模块或对象都以下划线开头。事实并非如此;有下划线确实会将某些内容标记为私有,但没有下划线并不会将某些内容标记为公共。
在本网站中,有些模块的名称不以下划线开头,但这应该被认为是私有的。为了澄清这些模块是什么,我们在下面定义了什么是本网站的公共API,并就如何从本网站导入模块/函数/对象提供了一些建议。
从SciPy导入函数的指导原则¶
scipy名称空间本身只包含从numpy导入的函数。为了向后兼容,这些函数仍然存在,但是应该直接从Numpy导入。
Scipy子模块的名称空间中的所有内容都是公共的。通常,建议从子模块命名空间导入函数。例如,函数 curve_fit
(在scipy/Optimize/minpack.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(...)
在这种情况下,可以选择第二种形式 if 在下一节中将记录有问题的子模块是公共的。
接口定义¶
下面列出的每个子模块都是公共的。这意味着这些子模块不太可能以不兼容的方式进行重命名或更改,如果有必要,在进行更改之前,将对一个SciPy版本发出弃用警告。
-
scipy.io.harwell_boeing
scipy.io.idl
scipy.io.matlab
scipy.io.netcdf
-
scipy.stats.distributions
SciPy结构¶
所有的SciPy模块都应遵循以下约定。在以下内容中,一个 SciPy模块 被定义为Python包,比方说 yyy
,它位于scipy/目录中。
理想情况下,每个SciPy模块都应该尽可能地自给自足。也就是说,它对其他包或模块的依赖性应该最小。即使是对其他SciPy模块的依赖也应该保持在最低限度。当然,对NumPy的依赖是假定的。
目录
yyy/
包含:一份文件
setup.py
它定义了configuration(parent_package='',top_path=None)
函数用于numpy.distutils
。一个目录
tests/
包含文件的test_<name>.py
对应于模块yyy/<name>{{.py,.so,/}}
。
私有模块应以下划线作为前缀
_
例如,yyy/_somemodule.py
。用户可见的函数应该有良好的文档,遵循 NumPy documentation style 。
这个
__init__.py
模块的文档字符串中应包含主要参考文档。它连接到下面的Sphinx文档doc/
通过斯芬克斯的自动模块指令。参考文档应该首先给出使用以下命令的模块内容的分类列表
autosummary::
指令,然后解释理解模块使用所必需的要点。包含大量示例的教程样式文档应该分开放置在
doc/source/tutorial/
。
有关指导,请参阅现有的SciPy子模块。
有关NumPy distutils的更多详细信息,请参见 NumPy Distutils - User's Guide 。