在 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.stats.distributions
SciPy 结构
所有 SciPy 模块都应遵循以下约定。在下文中,SciPy 模块被定义为 Python 包,例如 yyy
,位于 scipy/ 目录中。
-
理想情况下,每个 SciPy 模块都应尽可能独立。也就是说,它应该对其他包或模块具有最小的依赖关系。甚至对其他 SciPy 模块的依赖也应保持在最低限度。当然假设了对 NumPy 的依赖。
-
目录
yyy/
包含:-
为numpy.distutils
setup.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 - 用户指南。