Python 模块：从代码组织到大型应用架构

Python - 这篇文章属于一个选集。

§ 5: 本文

在 Python 中，模块（Module）是代码组织的核心单元。任何一个非凡的 Python 应用，都是由一个个精心设计的模块构筑而成。

模块基础：代码封装与重用
#

What & Why？
#

从本质上讲，一个 Python 模块就是一个包含了 Python 定义和语句的文件，其文件名就是模块名加上 .py 后缀。

使用模块主要解决了三大问题：

代码重用：将常用的函数、类或变量封装在模块中，可以在任何需要的地方导入并使用，避免重复编写代码。
命名空间隔离：每个模块都有自己独立的私有符号表（Private Symbol Table），这意味着在模块 A 中定义的全局变量不会与模块 B 中的同名变量发生冲突。这对于构建大型项目至关重要。
逻辑组织：将相关的代码组织在不同的模块中，使得项目结构更加清晰，易于理解和维护。

`import` 语句：引入代码
#

import 语句是使用模块的第一步。当解释器执行 import fibo 时，它会查找 fibo.py 文件，并执行其内容，然后将模块对象 fibo 引入到当前模块的符号表中。

# 文件: fibo.py
def fib(n):
    # ... (斐波那契数列实现)
def fib2(n):
    # ...

# 文件: main.py
import fibo  # 导入 fibo 模块

# 必须通过 "模块名.函数名" 的方式访问
fibo.fib(1000)

核心机制：import fibo 并没有将 fib 和 fib2 函数直接导入到当前命名空间，而是导入了名为 fibo 的模块对象。你需要通过该对象的属性来访问其内部的定义。

`import` 方式及其影响
#

Python 提供了多种导入方式，每种都有其特定的适用场景和注意事项。

from ... import ...：直接导入名称 这种方式将模块中的指定名称直接导入到当前命名空间，无需通过模块名前缀来访问。
```
from fibo import fib, fib2

fib(500) # 直接调用，无需 fibo. 前缀
```
优点：代码更简洁。缺点：如果导入的名称与当前模块中的现有名称冲突，后者将被覆盖。
import ... as ...：为名称创建别名 别名在处理名称过长或避免命名冲突时非常有用。
```
import fibo as fi
from fibo import fib as fibonacci

fi.fib(100)
fibonacci(100)
```
from ... import *：导入所有名称（需谨慎使用） 这会导入模块中所有非下划线开头的公开名称。
```
from fibo import *
fib(500)
```
⚠️ 警告：这种方式极易污染当前命名空间，导致名称冲突和代码可读性下降。在生产代码中应极力避免使用。它仅在少数场合（如 Python 交互式会话或某些框架的特定模式下）有其便利性。

模块的执行与 `name`
#

首次导入与缓存机制
#

一个模块的顶层代码在首次被导入时会执行一次。这包括所有的赋值语句、函数定义、类定义等。后续对同一模块的 import 语句不会再次执行模块代码，而是直接从缓存 sys.modules 中获取已加载的模块对象。这是一种重要的性能优化。

`if name == "main":`
#

每个模块都有一个名为 __name__ 的内置变量。它的值取决于模块是如何被执行的：

作为顶层脚本直接运行：如果一个 .py 文件被直接执行（例如 python my_module.py），那么在该模块内部，__name__ 的值是字符串 '__main__'。
被其他模块导入：如果一个模块被 import 语句加载，那么 __name__ 的值是该模块的文件名（不含 .py 后缀）。

这个特性催生了 Python 中一个非常重要的编码模式，它允许一个文件既可以作为可重用的模块被导入，也可以作为独立的脚本来执行。

实践范例 (fibo.py):

# 文件: fibo.py

# --- 模块定义部分 ---
def fib(n):
    # ...
def fib2(n):
    # ...

# --- 脚本执行部分 ---
if __name__ == "__main__":
    import sys
    # 这段代码只有在 "python fibo.py 100" 这样直接运行时才会执行
    # 如果被其他模块 import，这段代码将被忽略
    print(f"Fibonacci result for {sys.argv[1]}: {fib(int(sys.argv[1]))}")

模块搜索路径
#

当执行 import spam 时，Python 解释器会按照一个明确的顺序搜索 spam 模块：

sys.modules 缓存：首先检查模块是否已经被加载。
内置模块：检查 spam 是否是一个内置模块（如 sys, os）。
sys.path 列表：按顺序遍历 sys.path 列表中的每个目录。

sys.path 是一个字符串列表，它指定了模块的搜索路径。它的内容通常包括：

当前脚本所在的目录。
环境变量 PYTHONPATH 中指定的目录列表。
Python 安装的默认路径（如 site-packages 目录，用于存放第三方库）。

你可以通过以下代码查看当前的搜索路径：

import sys
print(sys.path)

包：层次化命名空间
#

当项目变得复杂，仅靠单个模块来组织代码已然不够。**包（Packages）**提供了一种通过“带点号的模块名”来组织模块命名空间的方法。

定义：一个包就是一个包含其他模块（或子包）的目录。
结构：目录中必须包含一个 __init__.py 文件（即使为空），Python 才会将其视为一个包。
- 注：自 Python 3.3 起，引入了“命名空间包”，允许没有 __init__.py 的目录成为包的一部分。在实践中，创建 __init__.py 依然是标准做法。

示例包结构:

sound/
├── __init__.py
├── formats/
│   ├── __init__.py
│   ├── wavread.py
│   └── wavwrite.py
└── effects/
    ├── __init__.py
    ├── echo.py
    └── reverse.py

使用包
#

你可以使用点号来导入包中的模块：

import sound.effects.echo
sound.effects.echo.echofilter(...)

# 或者使用 from 语句
from sound.effects import echo
echo.echofilter(...)

`init.py` 作用
#

__init__.py 文件有三个主要作用：

标记目录为包：这是它最基本的功能。
执行包的初始化代码：当你 import sound.effects 时，sound/__init__.py 和 sound/effects/__init__.py 会依次被执行。

简化导入（可选）：可以在 __init__.py 中将子模块的接口“提升”到包的命名空间中，方便外部调用。这样，用户就可以直接这样导入：

# 在 sound/effects/__init__.py 中
from .echo import echofilter
from .reverse import reversefilter

from sound.effects import echofilter # 而不是 from sound.effects.echo import echofilter

包内导入（相对导入）
#

在同一个包的不同模块之间，可以使用相对导入来相互引用，这使得包的结构更加稳固，不易受外部路径变化的影响。

from . import spam：从同级目录导入 spam 模块。
from .. import spam：从上级目录导入 spam 模块。
from ..subpackage import spam：从上级目录的另一个子包导入。

示例 (sound/effects/echo.py):

from ..formats import wavread # 从上级的 formats 包导入 wavread

模块与标准库
#

使用 dir() 探索模块 内置函数 dir() 可以找出模块定义的所有名称（变量、函数、类等）。

import fibo
import sys
dir(fibo)   # ['__name__', 'fib', 'fib2']
dir(sys)    # 返回一个很长的列表，包含 sys 模块的所有名称

Python 标准库：“Batteries Included” Python 自带一个庞大而功能丰富的标准库，提供了大量现成的模块，用于处理各种常见任务，如文件 I/O (os), 正则表达式 (re), 网络编程 (socket), JSON 处理 (json), 日期时间 (datetime) 等。在着手编写新代码前，先查阅标准库文档，往往能发现已经有现成的解决方案。