Python 学习路线
目标
最低目标：了解 Python、能看懂代码。 能读懂 examples/agent/minimal_agent.py 这类百行脚本：说出每行在做什么、数据如何流动、出错时能定位到哪一行。
不在本路线范围：Web 框架、数据分析、并发编程、打包发布等方向性内容。
使用方式
- 按阶段顺序学习；每阶段学完对应课程（或读一份官方文档）并完成一个小练习即可前进。
- 主教材为本项目课程（课程大纲，正文在
docs/课程/）：每阶段下的“课程”列出对应课，含可运行示例与自动判题练习。 - 官方 Python 教程（中文） 作为延伸阅读，各阶段“延伸阅读”链接均指向其中对应章节。
- 练习统一在本项目内运行：
uv run python（交互式）或uv run 文件.py。练习文件放practice/（可自建，按阶段命名，如practice/03_函数.py）。
阶段总览
| # | 阶段 | 达成标志 | 课程 |
|---|---|---|---|
| 1 | 环境与工具 | 能用 uv 运行脚本、进入解释器 | 导读 |
| 2 | 基础语法与数据类型 | 认识数字、字符串、布尔、None 与变量赋值 | 导读 |
| 3 | 控制流与函数 | 读懂 if / for / while / def | 导读 |
| 4 | 容器 | 读懂 list / dict / set / tuple 及推导式 | 导读 |
| 5 | 模块与包 | 读懂各种 import 写法 | 导读 |
| 6 | 异常 | 读懂报错信息与 try / except | 导读 |
| 7 | 类与对象 | 读懂 class、self、属性与方法 | 导读 |
| 8 | 常用标准库 | 认识 os / pathlib / json / datetime 等 | 导读 |
| 9 | 类型注解 | 读懂 def f(x: int) -> str | 导读 |
| 10 | 读代码技巧 | 掌握一套读陌生代码的方法 | 导读 |
| 11 | 简单项目 | 逐行讲清 minimal_agent.py | 导读 |
1. 环境与工具
- 目标：在本项目中运行 Python 代码，理解“项目环境”与“系统 Python”的区别。
- 核心概念：解释器、虚拟环境
.venv、pyproject.toml、uv.lock、uv run/uv add、交互式解释器（REPL）。 - 课程：1.1 运行 Python 代码 · 1.2 uv 项目与依赖（阶段导读）
- 延伸阅读：Python 概览与环境（本项目）；使用 Python 解释器；uv 项目工作流。
- 练习：执行
uv run python --version与python3 --version，解释两者为何可能不同；在uv run python中输入import this。
2. 基础语法与数据类型
- 目标：认识最基本的值和运算。
- 核心概念：
int/float/str/bool/None；变量赋值；算术与比较运算；字符串索引与切片；f-string（f"{name}"）；print()；注释#与文档字符串"""..."""；缩进。 - 课程：2.1 语法骨架与变量 · 2.2 数字、布尔与 None · 2.3 字符串 · 2.4 f-string 与格式化（阶段导读）
- 延伸阅读：Python 速览；格式化字符串字面值；内置类型。
- 练习：定义
city = "上海"、temp = 22，用 f-string 输出上海：晴，22°C；再试"1" + 1，读懂报错。
3. 控制流与函数
- 目标：读懂程序“走哪条路、重复几次、把什么封装成函数”。
- 核心概念：
if/elif/else；for+range()；while；break/continue；循环的else子句；def与return；位置参数与关键字参数；默认参数；*args/**kwargs及调用时的**解包。 - 课程：3.1 条件与循环 · 3.2 函数定义与调用 · 3.3 参数进阶与解包 · 3.4 作用域、闭包与 lambda（阶段导读）
- 延伸阅读：更多控制流工具（重点：循环的 else 子句、解包实参列表）。
- 练习：写
def get_weather(city): ...，分别用get_weather("北京")、get_weather(city="北京")、get_weather(**{"city": "北京"})调用，确认三者结果相同。
4. 容器：list / dict / set / tuple
- 目标：读懂数据如何被组织和遍历——这是读懂真实代码的关键。
- 核心概念：列表
[]（有序、可变，append）；字典{k: v}（键值映射，d[k]、d.get(k)）；集合{a, b}（去重）；元组(a, b)（不可变）；嵌套结构（列表里放字典）；列表推导式[x for x in xs if 条件]；in判断。 - 课程：4.1 列表、元组与切片 · 4.2 字典 · 4.3 集合 · 4.4 推导式与解包（阶段导读）
- 延伸阅读：数据结构（重点：列表推导式、字典）。
- 练习：给定
blocks = [{"type": "text", "text": "你好"}, {"type": "tool_use", "name": "get_weather"}]，用列表推导式取出所有type == "text"的text。
5. 模块与包
- 目标：读懂代码依赖了什么、名字从哪里来。
- 核心概念：模块（一个
.py文件）与包（含模块的目录）；import x、from x import y、import x as z；标准库 vs 第三方包（需uv add）；if __name__ == "__main__":。 - 课程：5.1 模块与 import · 5.2 包与项目结构（阶段导读）
- 延伸阅读：模块。
- 练习：新建
practice/tools.py定义get_weather，在另一个文件中用两种import写法调用它。
6. 异常
- 目标：看懂报错（Traceback），并读懂错误处理代码。
- 核心概念：Traceback 从下往上读（最后一行是错误类型与原因）；常见异常
KeyError/TypeError/NameError/ModuleNotFoundError；try/except/finally；raise。 - 课程：6.1 读懂 Traceback · 6.2 try / except / raise · 6.3 with 与上下文管理器（阶段导读）
- 延伸阅读：错误和异常。
- 练习：运行
LLM_PROVIDER=foo uv run examples/agent/minimal_agent.py，从 Traceback 定位到出错行并说明原因。
7. 类与对象
- 目标：读懂 SDK 风格代码中的对象、属性与方法调用。
- 核心概念：
class；__init__与self；实例属性obj.attr；方法obj.method()；链式属性访问（如client.messages.create(...)）；继承（了解即可）。 - 课程：7.1 类与实例 · 7.2 继承与特殊方法 · 7.3 dataclass 与枚举（阶段导读）
- 延伸阅读：类。
- 练习：写一个
class Tool，含name属性和run(**kwargs)方法，用它包装get_weather。
8. 常用标准库
- 目标：认识高频标准库，读代码时知道它们大致做什么。
- 核心概念：
os（环境变量os.getenv）、pathlib（路径）、json（JSON 读写）、datetime（时间）、sys、re（正则）、logging（日志）。 - 课程：8.1 pathlib 与文件 · 8.2 json · 8.3 os、sys 与环境变量 · 8.4 datetime · 8.5 collections 与 itertools · 8.6 logging（阶段导读）
- 延伸阅读：标准库简介；标准库索引。
- 练习：用
json.dumps(..., ensure_ascii=False)把阶段 4 的blocks转成字符串打印，再用json.loads还原。
9. 类型注解
- 目标：读懂现代 Python 代码中的类型标注（运行时不强制检查）。
- 核心概念：参数与返回值注解
def f(city: str) -> str；变量注解；list[str]、dict[str, int]；X | None；typing模块中的常用类型。 - 课程：9.1 类型注解基础 · 9.2 typing 进阶（阶段导读）
- 延伸阅读：函数注解；typing 模块；PEP 484。
- 练习：为
get_weather补上类型注解，并说明传入整数时为什么程序仍能运行。
10. 读代码技巧
- 目标：形成读陌生代码的固定步骤。
- 方法：
- 先看入口与整体：文件头文档字符串、
import、顶层常量、主流程（循环或main）。 - 跟踪核心数据：找出关键变量（如
messages），记录它在哪些行被创建、修改、读取。 - 遇到不认识的名字：判断来自内置、标准库还是第三方包，再查对应文档；在
uv run python中用help(对象)、type(值)、dir(对象)实验。 - 不确定就运行：加
print()观察中间值，或缩小成最小片段在解释器里试。
- 先看入口与整体：文件头文档字符串、
- 课程：10.1 迭代器与生成器 · 10.2 装饰器 · 10.3 读陌生代码的方法 · 10.4 读第三方 SDK 代码（阶段导读）
- 延伸阅读：术语对照表；PEP 8 代码风格（了解命名约定，如全大写表示常量）。
- 练习：不看注释，画出
minimal_agent.py中messages在两轮循环后的结构。
11. 简单项目：读懂 minimal_agent.py
- 目标：综合运用阶段 2–10，逐行讲清一个真实可运行的 Agent 循环。
- 课程：11.1 minimal_agent.py 逐行精读 · 11.2 改造与自测（阶段导读）
- 延伸阅读：读懂 minimal_agent.py（本项目）；示例说明见 examples/agent/README.md。
- 练习：新增一个工具
get_time(city)，同时修改tools与TOOL_FUNCTIONS，把提问改为“上海现在几点、天气如何？”，运行并观察模型如何调用两个工具（可能在同一轮并行请求，也可能分多轮）。
达成检查
完成后应能做到：
- [ ] 用
uv run运行项目脚本，知道依赖声明在哪里 - [ ] 读懂 list / dict 嵌套结构，并说出其中任意值的访问路径
- [ ] 读懂函数定义与调用，包括关键字参数和
**解包 - [ ] 读懂 Traceback 并定位到出错行
- [ ] 不看注释，复述
minimal_agent.py的执行流程