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 结构

所有 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 - 用户指南

  • 3
    点赞
  • 7
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

Sonhhxg_柒

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值