Python 模块与包的核心概念与使用详解

注意：如果模块中定义了 __all__ 变量，则只会导入 __all__ 列表中指定的名称。

4. as 定义别名

如果我们觉得模块名或者方法名太长写的时候太麻烦的时候，我们可以使用别名。这常用于避免命名冲突或简化长路径。

import time as t
t.sleep(2)  # 程序会停止两秒再结束

from time import sleep as slp
slp(2)

当我们使用别名之后，之前的名字不能再继续使用，否则会报错。

制作模块

在 Python 中，每个 Python 文件都可以作为一个模块，模块的名字就是文件的名字。也就是说自定义模块名必须要符合标识符命名规则（小写字母、数字、下划线，不能以数字开头）。

我们创建一个 python 文件，例如 my_module.py，并且在该文件中定义一个 add_num 方法。

# my_module.py

def add_num(a, b):
    return a + b

我们可以对该模块内的 add_num 方法进行测试。如果在模块文件中直接运行测试代码，当该模块被其他文件导入时，这些测试代码也会执行，这通常不是我们想要的行为。

如何区分模块是被直接运行还是被导入？

使用 if __name__ == '__main__': 作为条件，来使该代码只会在该模块下执行，当该模块被其他文件导入时就不会执行测试代码。

__name__ 是系统变量，是模块的标识符。值是：如果是自身模块直接运行，值是 __main__，否则是模块所在的文件名。

我们在模块所在文件打印 __name__ 可以验证这一点。然后在导入该模块的文件下运行代码，可以看到 __name__ 的值变成了模块名。

修改后的模块代码如下：

# my_module.py

def add_num(a, b):
    return a + b

if __name__ == '__main__':
    print(add_num(1, 2))  # 仅在直接运行时输出 3

然后在导入该模块的文件下调用该模块的对应方法：

# main.py
import my_module
print(my_module.add_num(3, 5))  # 输出 8，不会触发上面的 print

这里并不会执行我们的测试代码，这样就解决了问题。

注意： 如果使用 from .. import .. 或 from .. import * 导入多个模块的时候，且模块内有同名功能。当调用这个同名功能的时候，调用到的是后面导入的模块的功能。为了避免冲突，建议使用别名或明确指定模块前缀。

模块的定位顺序

当导入一个模块，Python 解析器对模块位置的搜索顺序是：

1. 当前文件所在的目录下的所有文件。
2. 如果不在当前目录，Python 则搜索环境变量 PYTHONPATH 下的每个目录。
3. 如果前面两个路径都找不到，Python 会查看默认安装路径（标准库路径）。

可以通过 import sys; print(sys.path) 来查看具体的搜索路径列表。

注意事项：

• 自己的文件名不要和已有模块名重复（如 random.py），否则会导致模块功能无法使用或覆盖标准库。
• 使用 from 模块名 import 功能 的时候，如果功能名字重复，调用到的是最后定义或导入的功能。

all 控制导出

当我们使用 from 模块名 import * 导入模块的时候，我们可以指定导入的方法，而不是全部方法。我们只需要在模块中定义 __all__ = ['方法 1', '方法 2']，这样就只会导入 __all__ 中的方法。

# my_module.py

__all__ = ['add_num']

def add_num(a, b):
    return a + b

def sub(a, b):
    return a - b

if __name__ == '__main__':
    print(add_num(1, 2))

此时，在其他文件中执行 from my_module import *，只能访问到 add_num，访问 sub 会抛出 NameError。

包 (Package)

Python 包是一种用于组织和管理 Python 代码的方式。它是一个包含模块、子包和资源文件的目录，可以在 Python 程序中被导入和使用。包的主要目的是将相关的功能和数据组织到一个单独的单元中，以便于重用和维护。

一个包通常包含一个名为 __init__.py 的特殊文件，用于标识该目录为一个包。它可以包含其他 Python 模块文件（以 .py 为扩展名）和子包（也是一个包的目录）。

创建包

在文件系统上，创建一个文件夹作为包名，并在其中放置 __init__.py 文件即可。在 IDE（如 PyCharm）中，右键点击目录选择 New -> Package 通常会自动创建该文件。

包结构示例：

mypackage/
    __init__.py
    module_a.py
    module_b.py
    subpackage/
        __init__.py
        module_c.py

导入包

我们首先需要在包下创建几个模块文件。

module_a.py

def add_num(a, b):
    return a + b

module_b.py

def sub_num(a, b):
    return a - b

导入包主要有两种方式：

1. import 包名。模块

当我们使用 import 包名。模块 导入包的时候，我们以 包名。模块名。功能 来使用相关功能。

import mypackage.module_a
import mypackage.module_b
print(mypackage.module_a.add_num(10, 20))  # 30
print(mypackage.module_b.sub_num(50, 20))  # 30

2. from 包名 import *

当我们使用 from 包名 import * 导入包的时候，我们需要在 __init__.py 文件中添加 __all__ = [] 来设置允许导入的模块列表。

mypackage/init.py

__all__ = ['module_a', 'module_b']

from . import module_a
from . import module_b

使用 模块名。功能 的方法来使用相应的功能。

from mypackage import *
print(module_a.add_num(10, 20))  # 30
print(module_b.sub_num(50, 20))  # 30

如果我们将 __init__.py 文件中的 __all__ 给删除或者注释掉的话，可能会导入包目录下所有的 .py 文件，这可能导致命名空间混乱。因此在使用 from 包名 import * 导入包的时候一定要记得设置 __init__.py 里的 __all__ 来设置允许导入的模块列表。

相对导入与绝对导入

在包内部，可以使用相对导入来引用同一包下的其他模块。

# mypackage/module_a.py
from . import module_b  # 相对导入
from .. import other_package  # 向上两级导入

绝对导入则直接使用完整的包路径，例如 from mypackage import module_b。推荐使用绝对导入以提高代码的可移植性。

最佳实践

1. 避免循环导入：模块 A 导入模块 B，模块 B 又导入模块 A，会导致 ImportError。应重构代码结构打破循环依赖。
2. 合理使用 __init__.py：除了标记包之外，可以在其中初始化全局变量或暴露高层接口。
3. 命名规范：包名和模块名应使用小写字母和下划线，避免与标准库冲突。
4. 文档字符串：为每个模块和函数添加 docstring，说明其用途和参数。

总结

Python 的模块和包系统是构建复杂应用的基础设施。通过合理划分模块、规范导入方式、利用 __init__.py 管理包内容，可以显著提升代码的可读性、可维护性和复用性。掌握 __name__、__all__ 以及搜索路径机制，能够帮助开发者解决常见的导入错误，编写出更加健壮的 Python 程序。