python3模块文档_6.模块—Pythontutorial3.6.3documentation

6.4. 包¶

包通常是使用用“圆点模块名”的结构化模块命名空间。例如&＃xff0c;名为 A.B 的模块表示了名为 A 的包中名为 B 的子模块。正如同用模块来保存不同的模块架构可以避免全局变量之间的相互冲突&＃xff0c;使用圆点模块名保存像 NumPy 或 Python Imaging Library 之类的不同类库架构可以避免模块之间的命名冲突。

假设你现在想要设计一个模块集&＃xff08;一个“包”&＃xff09;来统一处理声音文件和声音数据。存在几种不同的声音格式&＃xff08;通常由它们的扩展名来标识&＃xff0c;例如&＃xff1a;.wav&＃xff0c;

.aiff&＃xff0c;.au &＃xff09;&＃xff0c;于是&＃xff0c;为了在不同类型的文件格式之间转换&＃xff0c;你需要维护一个不断增长的包集合。可能你还想要对声音数据做很多不同的操作&＃xff08;例如混音&＃xff0c;添加回声&＃xff0c;应用平衡 功能&＃xff0c;创建一个人造效果&＃xff09;&＃xff0c;所以你要加入一个无限流模块来执行这些操作。你的包可能会是这个样子&＃xff08;通过分级的文件体系来进行分组&＃xff09;:

sound/ Top-level package

__init__.py Initialize the sound package

formats/ Subpackage for file format conversions

__init__.py

wavread.py

wavwrite.py

aiffread.py

aiffwrite.py

auread.py

auwrite.py

...

effects/ Subpackage for sound effects

__init__.py

echo.py

surround.py

reverse.py

...

filters/ Subpackage for filters

__init__.py

equalizer.py

vocoder.py

karaoke.py

...

当导入这个包时&＃xff0c;Python 通过 sys.path 搜索路径查找包含这个包的子目录。

为了让 Python 将目录当做内容包&＃xff0c;目录中必须包含 __init__.py 文件。这是为了避免一个含有烂俗名字的目录无意中隐藏了稍后在模块搜索路径中出现的有效模块&＃xff0c;比如 string。最简单的情况下&＃xff0c;只需要一个空的 __init__.py 文件即可。当然它也可以执行包的初始化代码&＃xff0c;或者定义稍后介绍的 __all__ 变量。

用户可以每次只导入包里的特定模块&＃xff0c;例如:

import sound.effects.echo

这样就导入了 sound.effects.echo 子模块。它必需通过完整的名称来引用:

sound.effects.echo.echofilter(input, output, delay&＃61;0.7, atten&＃61;4)

导入包时有一个可以选择的方式:

from sound.effects import echo

这样就加载了 echo 子模块&＃xff0c;并且使得它在没有包前缀的情况下也可以使用&＃xff0c;所以它可以如下方式调用:

echo.echofilter(input, output, delay&＃61;0.7, atten&＃61;4)

还有另一种变体用于直接导入函数或变量:

from sound.effects.echo import echofilter

这样就又一次加载了 echo 子模块&＃xff0c;但这样就可以直接调用它的 echofilter() 函数:

echofilter(input, output, delay&＃61;0.7, atten&＃61;4)

需要注意的是使用 from package import item 方式导入包时&＃xff0c;这个子项&＃xff08;item&＃xff09;既可以是包中的一个子模块&＃xff08;或一个子包&＃xff09;&＃xff0c;也可以是包中定义的其它命名&＃xff0c;像函数、类或变量。import 语句首先核对是否包中有这个子项&＃xff0c;如果没有&＃xff0c;它假定这是一个模块&＃xff0c;并尝试加载它。如果没有找到它&＃xff0c;会引发一个 ImportError 异常。

相反&＃xff0c;使用类似 import item.subitem.subsubitem 这样的语法时&＃xff0c;这些子项必须是包&＃xff0c;最后的子项可以是包或模块&＃xff0c;但不能是前面子项中定义的类、函数或变量。

6.4.1. 从 * 导入包¶

那么当用户写下 from sound.effects import * 时会发生什么事&＃xff1f;理想中&＃xff0c;总是希望在文件系统中找出包中所有的子模块&＃xff0c;然后导入它们。这可能会花掉很长时间&＃xff0c;并且出现期待之外的边界效应&＃xff0c;导出了希望只能显式导入的包。

对于包的作者来说唯一的解决方案就是给提供一个明确的包索引。import 语句按如下条件进行转换&＃xff1a;执行 from package import * 时&＃xff0c;如果包中的 __init__.py 代码定义了一个名为 __all__ 的列表&＃xff0c;就会按照列表中给出的模块名进行导入。新版本的包发布时作者可以任意更新这个列表。如果包作者不想 import * 的时候导入他们的包中所有模块&＃xff0c;那么也可能会决定不支持它&＃xff08; import * &＃xff09;。例如&＃xff0c; sound/effects/__init__.py 这个文件可能包括如下代码:

__all__ &＃61; ["echo", "surround", "reverse"]

这意味着 from sound.effects import * 语句会从 sound 包中导入以上三个已命名的子模块。

如果没有定义 __all__ &＃xff0c; from sound.effects import * 语句 不会 从 sound.effects 包中导入所有的子模块。无论包中定义多少命名&＃xff0c;只能确定的是导入了 sound.effects 包&＃xff08;可能会运行 __init__.py 中的初始化代码&＃xff09;以及包中定义的所有命名会随之导入。这样就从 __init__.py 中导入了每一个命名&＃xff08;以及明确导入的子模块&＃xff09;。同样也包括了前述的 import 语句从包中明确导入的子模块&＃xff0c;考虑以下代码:

import sound.effects.echo

import sound.effects.surround

from sound.effects import *

在这个例子中&＃xff0c;echo 和 surround 模块导入了当前的命名空间&＃xff0c;这是因为执行 from...import 语句时它们已经定义在 sound.effects 包中了&＃xff08;定义了 __all__ 时也会同样工作&＃xff09;。

尽管某些模块设计为使用 import * 时它只导出符合某种规范/模式的命名&＃xff0c;仍然不建议在生产代码中使用这种写法。

记住&＃xff0c;from Package import specific_submodule 没有错误&＃xff01;事实上&＃xff0c;除非导入的模块需要使用其它包中的同名子模块&＃xff0c;否则这是推荐的写法。

6.4.2. 包内引用¶

如果包中使用了子包结构&＃xff08;就像示例中的 sound 包&＃xff09;&＃xff0c;可以按绝对位置从相邻的包中引入子模块。例如&＃xff0c;如果 sound.filters.vocoder 包需要使用 sound.effects 包中的 echo 模块&＃xff0c;它可以 from sound.Effects import echo。

你可以用这样的形式 from module import name 来写显式的相对位置导入。那些显式相对导入用点号标明关联导入当前和上级包。以 surround 模块为例&＃xff0c;你可以这样用:

from . import echo

from .. import formats

from ..filters import equalizer

需要注意的是显式或隐式相对位置导入都基于当前模块的命名。因为主模块的名字总是 "__main__"&＃xff0c;Python 应用程序的主模块应该总是用绝对导入。

6.4.3. 多重目录中的包¶

包支持一个更为特殊的特性&＃xff0c; __path__。 在包的 __init__.py 文件代码执行之前&＃xff0c;该变量初始化一个目录名列表。该变量可以修改&＃xff0c;它作用于包中的子包和模块的搜索功能。

这个功能可以用于扩展包中的模块集&＃xff0c;不过它不常用。

Footnotes

事实上函数定义既是“声明”又是“可执行体”&＃xff1b;执行体由函数在模块全局语义表中的命名导入。