403 lines
10 KiB
Markdown
403 lines
10 KiB
Markdown
# 第 2-1 课：模块与包
|
||
|
||
## 一、本课目标
|
||
|
||
完成本课后，你将能够：
|
||
|
||
1. 说出模块和包分别是什么；
|
||
2. 解释为什么要把较长的程序拆分成多个文件；
|
||
3. 使用 `import` 导入模块；
|
||
4. 使用 `from...import...` 导入指定内容；
|
||
5. 创建并使用自己的模块和包；
|
||
6. 理解 `if __name__ == "__main__":` 的基本作用。
|
||
|
||
## 二、前置知识
|
||
|
||
学习本课前，需要掌握：
|
||
|
||
- 变量和基本数据类型；
|
||
- 列表与字典；
|
||
- 条件判断与循环；
|
||
- 函数、参数和返回值；
|
||
- 知道 Python 代码保存在 `.py` 文件中。
|
||
|
||
本课是 Python 进阶阶段的第一课，但不会使用复杂语法。
|
||
|
||
## 三、模块是什么
|
||
|
||
模块（Module）通常就是一个保存了 Python 代码的 `.py` 文件。
|
||
|
||
前面的课程大多把函数和主程序写在同一个文件中。程序越来越大后，这种方式会产生三个问题：
|
||
|
||
1. 文件太长，不容易阅读；
|
||
2. 不同功能混在一起，不容易修改；
|
||
3. 已经写好的函数不方便在其他程序中重复使用。
|
||
|
||
把相关函数放进单独文件，可以让代码职责更清晰。例如：
|
||
|
||
```text
|
||
agent_tools.py 保存 Agent 工具相关函数
|
||
module_example.py 组织程序运行流程
|
||
```
|
||
|
||
`agent_tools.py` 就是一个自定义模块。
|
||
|
||
## 四、使用 `import` 导入模块
|
||
|
||
导入（Import）表示让当前文件能够使用另一个模块中的内容。
|
||
|
||
### 4.1 导入标准库模块
|
||
|
||
标准库（Standard Library）是安装 Python 时自带的一组模块，不需要另外下载。本课使用 `random` 模块随机选择列表元素：
|
||
|
||
```python
|
||
import random
|
||
|
||
tools = ["搜索", "终端", "计算器"]
|
||
recommended_tool = random.choice(tools)
|
||
print(recommended_tool)
|
||
```
|
||
|
||
这里：
|
||
|
||
- `import random` 导入整个模块；
|
||
- `random.choice()` 表示调用 `random` 模块中的 `choice()` 函数；
|
||
- 函数会从列表中随机选择一个元素，因此每次结果可能不同。
|
||
|
||
### 4.2 导入自己的模块
|
||
|
||
课程目录中的 `agent_tools.py` 定义了函数和变量。在同一目录的 `module_example.py` 中可以这样使用：
|
||
|
||
```python
|
||
import agent_tools
|
||
|
||
tool_count = agent_tools.get_tool_count(agent_tools.DEFAULT_TOOLS)
|
||
print(tool_count)
|
||
```
|
||
|
||
导入时不写 `.py`，因此使用的是 `import agent_tools`，不是 `import agent_tools.py`。
|
||
|
||
通过 `模块名.名称` 可以清楚看出这个变量或函数来自哪里。
|
||
|
||
## 五、使用 `from...import...`
|
||
|
||
如果当前文件只需要模块中的少量内容，可以导入指定名称：
|
||
|
||
```python
|
||
from agent_tools import build_agent_description
|
||
|
||
description = build_agent_description("代码助手", "gpt-5")
|
||
print(description)
|
||
```
|
||
|
||
导入后可以直接写函数名，不再需要添加 `agent_tools.`。
|
||
|
||
两种写法都正确：
|
||
|
||
```python
|
||
import agent_tools
|
||
agent_tools.build_agent_description("代码助手", "gpt-5")
|
||
```
|
||
|
||
```python
|
||
from agent_tools import build_agent_description
|
||
build_agent_description("代码助手", "gpt-5")
|
||
```
|
||
|
||
入门阶段建议优先使用清晰、容易看出来源的写法。不要使用 `from agent_tools import *`，因为星号会一次导入许多名称，容易造成重名和阅读困难。
|
||
|
||
## 六、导入模块时会发生什么
|
||
|
||
第一次导入模块时，Python 会从上到下执行模块中的代码。函数定义只是创建函数，不会自动调用函数；但直接写在文件最外层的 `print()` 会立即执行。
|
||
|
||
为了区分“直接运行文件”和“把文件作为模块导入”，可以使用：
|
||
|
||
```python
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
|
||
`__name__` 是 Python 自动提供的特殊变量：
|
||
|
||
- 直接运行当前文件时，`__name__` 的值是 `"__main__"`；
|
||
- 当前文件被其他文件导入时，`__name__` 的值是模块名。
|
||
|
||
因此，可以把模块的测试代码放进 `main()`，再通过入口判断调用：
|
||
|
||
```python
|
||
def main():
|
||
print("正在测试模块。")
|
||
|
||
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
|
||
这样直接运行模块时会执行测试，导入模块时不会意外输出测试文字。
|
||
|
||
## 七、包是什么
|
||
|
||
包（Package）是用于组织多个模块的文件夹。
|
||
|
||
本课示例结构如下：
|
||
|
||
```text
|
||
agent_package/
|
||
├── __init__.py
|
||
└── status_text.py
|
||
```
|
||
|
||
`__init__.py` 用来明确表示这个目录是一个 Python 包。本课暂时不在其中编写功能，只保留说明注释。
|
||
|
||
从包中的模块导入函数：
|
||
|
||
```python
|
||
from agent_package.status_text import get_status_text
|
||
|
||
status_text = get_status_text(True)
|
||
print(status_text)
|
||
```
|
||
|
||
可以把导入路径从左到右理解为：
|
||
|
||
```text
|
||
agent_package 包 → status_text 模块 → get_status_text 函数
|
||
```
|
||
|
||
## 八、示例文件
|
||
|
||
本课包含以下示例：
|
||
|
||
```text
|
||
02_python进阶/2_1_模块与包/
|
||
├── README.md
|
||
├── module_example.py
|
||
├── agent_tools.py
|
||
├── practice.py
|
||
└── agent_package/
|
||
├── __init__.py
|
||
└── status_text.py
|
||
```
|
||
|
||
- `module_example.py`：完整主程序；
|
||
- `agent_tools.py`：自己编写的模块；
|
||
- `agent_package/`：自己编写的简单包；
|
||
- `practice.py`：课堂练习。
|
||
|
||
## 九、运行方法
|
||
|
||
打开 PowerShell，进入项目根目录：
|
||
|
||
```powershell
|
||
cd F:\PyCharm\PythonLearn
|
||
```
|
||
|
||
运行完整示例：
|
||
|
||
```powershell
|
||
python .\02_python进阶\2_1_模块与包\module_example.py
|
||
```
|
||
|
||
直接运行自定义模块的测试：
|
||
|
||
```powershell
|
||
python .\02_python进阶\2_1_模块与包\agent_tools.py
|
||
```
|
||
|
||
完成练习后运行：
|
||
|
||
```powershell
|
||
python .\02_python进阶\2_1_模块与包\practice.py
|
||
```
|
||
|
||
## 十、运行结果
|
||
|
||
运行 `module_example.py` 时，会看到类似结果：
|
||
|
||
```text
|
||
一、标准库模块
|
||
随机推荐工具：搜索
|
||
==============================
|
||
二、自定义模块
|
||
默认工具：['搜索', '终端']
|
||
默认工具数量：2
|
||
代码助手 使用 gpt-5 模型
|
||
==============================
|
||
三、自定义包
|
||
Agent 状态：启用
|
||
```
|
||
|
||
第一部分使用了随机选择，因此也可能显示“终端”或“计算器”，这不是错误。
|
||
|
||
运行 `agent_tools.py` 时，预期看到：
|
||
|
||
```text
|
||
正在测试 agent_tools 模块。
|
||
默认工具数量：2
|
||
```
|
||
|
||
## 十一、关键代码执行顺序
|
||
|
||
运行 `module_example.py` 时，Python 大致按照以下顺序工作：
|
||
|
||
1. 执行文件顶部的导入语句；
|
||
2. 找到并加载标准库模块 `random`；
|
||
3. 找到同一目录中的 `agent_tools.py`；
|
||
4. 找到 `agent_package` 包中的 `status_text.py`；
|
||
5. 创建当前文件中定义的函数；
|
||
6. 执行文件末尾的程序入口判断；
|
||
7. 因为当前文件是直接运行的，所以调用 `main()`；
|
||
8. `main()` 依次调用三个演示函数并输出结果。
|
||
|
||
导入 `agent_tools.py` 时，它的入口判断不成立，所以不会自动执行 `show_module_test()`。
|
||
|
||
## 十二、常见错误
|
||
|
||
### 12.1 导入时写了 `.py`
|
||
|
||
错误写法：
|
||
|
||
```python
|
||
import agent_tools.py
|
||
```
|
||
|
||
正确写法：
|
||
|
||
```python
|
||
import agent_tools
|
||
```
|
||
|
||
模块名不包含文件扩展名 `.py`。
|
||
|
||
### 12.2 文件名与导入名不一致
|
||
|
||
如果文件名是 `agent_tools.py`，就应使用 `import agent_tools`。少写字母或使用不同名称，会出现：
|
||
|
||
```text
|
||
ModuleNotFoundError: No module named 'agent_tool'
|
||
```
|
||
|
||
中文解释：Python 没有找到名为 `agent_tool` 的模块。请检查文件名、导入名和运行目录。
|
||
|
||
### 12.3 导入整个模块后直接调用函数
|
||
|
||
如果使用：
|
||
|
||
```python
|
||
import agent_tools
|
||
```
|
||
|
||
就要通过模块名调用：
|
||
|
||
```python
|
||
agent_tools.get_tool_count([])
|
||
```
|
||
|
||
直接写 `get_tool_count([])` 会出现名称未定义错误。
|
||
|
||
### 12.4 自定义模块名与标准库重名
|
||
|
||
不要把自己的文件命名为 `random.py`，否则 `import random` 可能导入自己的文件，而不是 Python 标准库模块。
|
||
|
||
### 12.5 导入模块时出现意外输出
|
||
|
||
如果测试用的 `print()` 直接写在模块最外层，导入模块时也会执行。把测试代码放进 `main()`，再使用程序入口判断。
|
||
|
||
### 12.6 包或模块不在预期位置
|
||
|
||
本课请保持示例目录结构不变，并从项目根目录执行讲义中的命令。目录位置错误会导致 Python 找不到需要导入的内容。
|
||
|
||
## 十三、课堂练习
|
||
|
||
打开 `practice.py`，按照注释依次完成五部分：
|
||
|
||
1. 创建 `calculator.py` 模块；
|
||
2. 分别使用两种方式导入加法函数；
|
||
3. 为模块添加安全的测试入口；
|
||
4. 创建 `text_package` 包；
|
||
5. 从包中的模块导入文本处理函数。
|
||
|
||
建议先独立完成。如果遇到困难，先检查文件名、目录位置和导入语句是否一致。
|
||
|
||
## 十四、参考答案
|
||
|
||
请先独立练习，再展开查看。
|
||
|
||
<details>
|
||
<summary>查看参考答案</summary>
|
||
|
||
`calculator.py`：
|
||
|
||
```python
|
||
def add(first, second):
|
||
"""返回两个数字相加的结果。"""
|
||
return first + second
|
||
|
||
|
||
def main():
|
||
"""测试当前模块的加法功能。"""
|
||
print("正在测试计算模块。")
|
||
|
||
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
|
||
`text_package/__init__.py`：
|
||
|
||
```python
|
||
# 这个文件表示 text_package 是一个 Python 包。
|
||
```
|
||
|
||
`text_package/text_tools.py`：
|
||
|
||
```python
|
||
def make_title(text):
|
||
"""为文本添加标题装饰。"""
|
||
return f"=== {text} ==="
|
||
```
|
||
|
||
`practice.py` 中需要补充的核心代码：
|
||
|
||
```python
|
||
import calculator
|
||
from calculator import add
|
||
from text_package.text_tools import make_title
|
||
|
||
|
||
result = calculator.add(10, 20)
|
||
print(f"计算结果：{result}")
|
||
|
||
new_result = add(5, 8)
|
||
print(f"新的计算结果：{new_result}")
|
||
|
||
title = make_title("Python 学习")
|
||
print(title)
|
||
```
|
||
|
||
</details>
|
||
|
||
## 十五、本课小结
|
||
|
||
- 模块通常是一个 `.py` 文件；
|
||
- 模块可以拆分功能，并让代码在多个程序中重复使用；
|
||
- `import 模块名` 会导入整个模块；
|
||
- `from 模块名 import 名称` 会导入指定内容；
|
||
- `if __name__ == "__main__":` 可以避免导入模块时自动执行测试或主程序；
|
||
- 包是用于组织多个模块的文件夹；
|
||
- 可以使用点号表示“包、模块、名称”之间的层级关系。
|
||
|
||
## 十六、验收标准
|
||
|
||
完成本课时，应满足以下条件：
|
||
|
||
- 可以成功运行 `module_example.py`；
|
||
- 可以解释模块与包的区别；
|
||
- 可以使用两种方式导入模块内容；
|
||
- 可以创建并导入自己的 `.py` 模块；
|
||
- 可以解释入口判断的基本作用；
|
||
- 可以创建包含 `__init__.py` 的简单包；
|
||
- 可以完成 `practice.py` 中的五部分练习；
|
||
- 运行练习时得到 `30`、`13` 和 `=== Python 学习 ===`；
|
||
- 导入 `calculator` 时不会自动输出模块测试文字。
|