跳转至

Python 学习仓库:三天地基(9/5–9/7)+ 一个月进阶(9/8–10/7)

给一名已经会"变量 / 循环 / if"的高中生。第一阶段(三天):能不看资料、独立写出 100–300 行结构清晰的小程序。第二阶段(一个月):语言进阶、工程规范、类型系统、Pydantic、日志/正则/文件/SQLite、asyncio、httpx、FastAPI、测试进阶、架构与封装——为之后开发 LLM agent 打好全部 Python 底子(agent 本身归 learn-agent 仓库,本仓库只讲 Python)。

环境基准:Windows + Python 3.14(本机 3.14.4;最新补丁 3.14.7,无需升级)+ uv + VS Code + ruff + pytest。所有事实以 2026-09-05 的调研为准,见 research/

导航:三天计划从下面第 0 节开始读;一个月进阶从 plan/month-overview.md 开始读(日历、20 个模块、与 learn-agent 的对应关系、并行时的最低配置)。


0. 先读这一页(5 分钟)

三天的时间盘子:周六、周日各约 10 小时有效学习(钟点 09:00–22:00,含吃饭休息),周一约 5 小时。合计 25 小时有效学习

三条铁律(违反任何一条,三天效果减半):

  1. 代码必须自己敲。看到示例代码 → 合上 → 自己默写 → 对照。复制粘贴 = 没学。
  2. AI 是导师不是外包。卡住先做"8 分钟自检",再用 ai-guide.md 里的固定提示词问;绝不让 AI 直接给完整答案;拿到提示后自己重写。
  3. 每天睡够 8 小时,晨起先闭卷测验。睡眠是记忆巩固的一部分,熬夜补进度是负收益。

每块的节奏(50 分钟 + 10 分钟休息)

分钟 做什么 说明
0–10 读 + 预测 读计划里的知识点和示例,先在纸上写出示例的输出,再运行验证
10–20 追踪 + 改写 把示例改 2–3 处再运行;引用/作用域类的问题贴到 Python Tutor 看动画
20–45 独立编码 打开 exercises/dayN/xx.py 完成 TODO,运行到全部 [OK]
45–50 复盘 在文件顶部写 2 行"我学到的"+ 1 条踩到的坑
50–60 离开屏幕 站起来、喝水、看远处,不看手机

每天结构:上午 3 块 → 午饭 + 20–30 分钟闭眼 → 下午 3 块 → 加餐散步 → 晚上 2 块 → 复盘日志 → 睡觉。每天"从零写代码"的高负荷时间控制在 4.5 小时左右,其余是读、追踪、找 bug、测验,这是刻意练习研究给出的生理上限(见 research/05)。


1. 目录结构与用法

learn-python/
├── README.md              ← 本文件:总览、知识地图、用法
├── ai-guide.md            ← AI 使用规则 + 5 个提示词模板 + 学习日志模板
├── checklist.md           ← 三天打卡 + 三档知识点自评表
├── plan/
│   ├── day1.md  day2.md  day3.md      ← 三天地基(逐块计划)
│   ├── month-overview.md              ← 一个月进阶总览:日历、20 个模块、learn-agent 对应、并行最低配置
│   ├── week1.md … week4.md            ← 每周逐日计划:知识点分档、预测代码、练习规格、小项目、周测
│   └── capstone.md                    ← 综合项目 Notebook Service 规格与验收
├── exercises/
│   ├── day1/ day2/ day3/              ← 三天练习骨架(自测式)
│   ├── week1/ … week4/  final/        ← 每周练习骨架 + pytest 测试 + 周测;final/ 结业测验
│   └── solutions/                     ← 全部参考答案(做完再看;看完合上重写一遍)
├── project/README.md                  ← 三天收尾项目:3 个候选
├── projects/                          ← 一个月的小项目(uv workspace 成员,`uv run kb` / `uv run aggregator`)
│   ├── kb/                            ← 第 2 周:知识库 CLI
│   ├── aggregator/                    ← 第 3 周:并发抓取聚合器
│   └── notebook/                      ← 收官:Notebook Service(自己从 uv init --package 开始搭)
├── research/              ← 13 份调研报告(01–06 三天地基,07–13 一个月进阶)+ 00-index.md 索引
├── deploy.md              ← 网站版:如何构建(Zensical)与上传到 Cloudflare Pages
├── zensical.toml          ← 网站配置(导航、主题、Markdown 扩展)
├── docs/                  ← 网站"薄包装页":只写 --8<-- 引入上面的原文件,由 tools/gen_site_pages.py 生成
├── tools/gen_site_pages.py
├── site/                  ← `uv run zensical build` 的输出(已 gitignore),拖到 Cloudflare Pages 即可
├── pyproject.toml         ← uv 项目配置:pytest + ruff + zensical 已配好
└── .python-version        ← 3.14

网站版:同样的内容有一个带导航、全文搜索、代码高亮和深浅色切换的静态网站。本地预览 uv run zensical serve -o;构建 uv run zensical build --clean 后把 site/ 拖到 Cloudflare Pages。细节见 deploy.md。网站是只读的,打卡仍在本地 checklist.md 里做。

常用命令(在 learn-python 目录下的 VS Code 终端里执行;uv run 会自动准备虚拟环境,不需要手动激活 .venv):

uv sync                                   # 第一次:创建 .venv,安装 pytest 与 ruff
uv run python exercises/day1/01_types_and_fstrings.py   # 运行一个练习(看 [OK]/[FAIL])
uv run python                             # 进入交互式 REPL(3.14 彩色、多行编辑,输入 exit 退出)
uv run pytest exercises/day2              # 运行 Day 2 的 pytest 测试(周计划同理:exercises/week1)
uv run kb --help                          # 第 2 周起的小项目直接以命令形式可用
uv run ruff check exercises               # 代码检查
uv run ruff format exercises              # 自动格式化

注意:不带路径直接运行 uv run pytest 会把所有还没实现的练习测试(包括 projects/kbprojects/aggregator 的骨架)都跑进来,一片红是正常的;请按上面的写法指定目录。

维护工具tools/,学生不需要用,但想"把项目重置回骨架"时会用到):

uv run python tools/verify_solutions.py all       # 把全部参考答案与练习测试组合到临时目录运行,验证答案能过
uv run python tools/kb_skeleton.py                # 把 projects/kb 重置为骨架;加 --solution 装回参考答案
uv run python tools/aggregator_skeleton.py        # 同上,针对 projects/aggregator
uv run python tools/gen_site_pages.py             # 重新生成网站薄包装页(新增练习文件后运行)

一个月进阶怎么用

  1. 先读 plan/month-overview.md(日历、20 个模块、与 learn-agent 的对应关系),再读当周的 plan/weekN.md
  2. 每天按计划页的"块"推进:读知识点表 → 做"预测练习" → 打开 exercises/weekN/wN_0M_*.pyTODO 换成实现 → uv run pytest exercises/weekN/test_wN_0M_*.py -q 到全绿 → 对照 exercises/solutions/weekN/ 后合上重写。
  3. 第 2、3 周的小项目在 projects/kbprojects/aggregator:骨架与测试已给,README 写明了要实现哪些函数、验收标准;uv run kb --helpuv run aggregator --help 随时可用。
  4. 每周日:周测(exercises/weekN/quiz_weekN.md,闭卷 40 分钟)→ 对答案 → 填 checklist.md 第五部分 → 周日志。
  5. 10/2 起做综合项目(plan/capstone.md,从零搭 projects/notebook),10/7 结业测验 exercises/final/quiz_final.md

2. 三天总览

主题 产出(可验证)
Day 1 周六 09:00–22:00 环境与命令行 → 基础类型与 f-string → 字符串 → 列表/元组 → 字典/集合 → 函数与作用域 → 调试与找 bug → 综合小程序 8 个练习文件全部 [OK];07_mini_project_grades.py(60–80 行成绩单分析)能跑;VS Code 里打过断点单步过
Day 2 周日 09:00–21:30 晨测 → 异常 → 文件/pathlib/UTF-8/JSON/CSV → 模块与标准库 → OOP 与 dataclass → 推导式/生成器/match/类型注解 → pytest 与 ruff → 成绩单 v2 7 组练习全部 [OK];uv run pytest exercises/day2 全绿;ruff check 零警告;亲手复现并修复过一次 UnicodeDecodeError
Day 3 周一 约 5h 联合晨测 → 3 小时收尾项目(project.py + test_project.py + README.md)→ AI 评审与重构 → 结业闭卷测验 → 三档自评 → 后续路线 一个 120–200 行、≥5 个 pytest 测试、ruff 零警告、有 README 的完整小项目

每天的详细时间表、每块的知识点、阅读材料、练习规格、陷阱反例见 plan/dayN.md


3. 知识点地图(三档)

  • A 必须掌握:不看资料能默写、能调通。三天结束时用 checklist.md 闭卷自评。
  • B 了解会用:理解概念,看着文档/速查表能用。
  • C 知道存在:知道它解决什么问题、该搜什么关键词;不占用练习时间。

3.1 环境与工具链(Day 1 Block 0)

知识点 备注
在终端运行脚本:uv run python xxx.py;REPL:uv run pythonexit 退出 A 3.13+ 新 REPL:彩色、多行编辑、方向键翻历史、F1 帮助
cdls/dir、Tab 补全、Ctrl+C 中断死循环 A
VS Code:打开文件夹、选择解释器(.venv)、运行、断点 / F10 单步 / F11 进入 / 变量面板 A(断点)/ B(Watch) print 调试更能建立"程序是一步步执行的"心智模型
uv:uv inituv add 包uv add --dev pytestuv runuv syncpyproject.toml 是什么 B 不学 venv 激活与 pip,只需知道它们是 uv 之前的老方法
ruff:ruff check 找错、ruff format 排版 B 保存即格式化
Windows 坑:商店 python 别名劫持、Activate.ps1 被执行策略拦(我们不激活所以不会碰到)、路径反斜杠、默认编码 GBK A(编码)/ B(其他) research/02 速查表
Git 版本控制 C 三天不学,之后第一周学

3.2 基础类型与运算(Day 1 Block 1)

知识点
int(任意精度,1_000_000)、float0.1 + 0.2 != 0.3 的原因)、boolstrNone A
+ - * / // % **/ 永远得 float;// 向下取整;% 取余(负数时的行为知道即可) A
int() float() str() 转换;input() 永远返回字符串 A
比较 == != < <= > >=,链式比较 0 < x < 10and / or / not 与短路(返回的是操作数本身) A
真值:0""[]{}None 为假 A
f-stringf"{x}"f"{x:.2f}"f"{x:>8}"f"{x=}"(调试)、3.12 起可在花括号里用同种引号 A
round()abs()min/max/sumdivmod() A
% 格式化与 .format():能读懂老代码即可 C
复数、位运算 C

3.3 字符串(Day 1 Block 2)

知识点
索引、负索引、切片 s[a:b:c]s[::-1]不可变s[0] = "x" 报错) A
lenin+*、for 遍历字符 A
strip/split/join/replace/upper/lower/startswith/endswith/find/count/isdigit/isalpha A
转义 \n \t \\ \"、原始字符串 r"C:\new"、三引号多行 A
ord()/chr()、Unicode 与 UTF-8 的关系(中文一个字符 ≠ 一个字节) B
字符串方法返回新串而不修改原串(s.upper() 不改 s A(陷阱)
正则 re C(周一后学)

3.4 列表与元组(Day 1 Block 3)

知识点
创建、索引、切片、lenin、嵌套列表 grid[r][c] A
append/extend/insert/pop/remove/index/count/clearsort() 原地返回 None vs sorted() 返回新列表;reverse() vs reversed() A
for x in lst / for i, x in enumerate(lst) / for a, b in zip(xs, ys)range(start, stop, step) 左闭右开 A
别名与拷贝b = a 是同一个对象;a.copy() / a[:] 浅拷贝;copy.deepcopy A(别名)/ B(深拷贝)
元组:不可变、(1,)、解包 a, b = b, a、函数多返回值本质是元组 A
遍历时修改列表会出错 → 用新列表或推导式 A(陷阱)
[[0] * 3] * 3 三行是同一个对象 B(陷阱)
列表推导式 [f(x) for x in xs if cond] A(Day 2 深化)

3.5 字典与集合(Day 1 Block 4)

知识点
{k: v}d[k]d[k] = vdel d[k]k in dlen A
d.get(k, default)KeyErrorkeys/values/items 三种遍历;for k, v in d.items() A
计数模式 d[k] = d.get(k, 0) + 1;分组模式 d.setdefault(k, []).append(x) A
键必须可哈希(不可变):字符串、数字、元组可以,列表不行 A
嵌套结构:列表里装字典("一行一条记录")、字典里装列表 A
集合 {1, 2}set()add/remove/discardin| & - ^、去重 set(lst) B
collections.Counterdefaultdict B
字典推导式 {k: v for ...}、集合推导式 B
3.7+ 字典保持插入顺序 B

3.6 函数与作用域(Day 1 Block 5)

知识点
def、形参/实参、return(无 returnNone)、多值返回、docstring A
位置参数、关键字参数、默认值;可变默认参数陷阱 def f(x, lst=[]) → 用 None A
作用域:局部 vs 全局,LEGB 查找;函数里给全局变量赋值需要 global尽量不用,改成传参 + 返回 A
类型注解 def f(x: int, name: str = "") -> float:list[int]dict[str, int]int | None B(写)/ A(读)
*args**kwargs* 解包传参、仅关键字参数 def f(a, *, b) B
lambda(配合 sorted(key=...))、函数是对象可以当参数传 B
把一个 50 行程序拆成 4–6 个函数:每个函数只做一件事、名字是动词 A
闭包、装饰器、递归 C(递归:知道有终止条件即可)

3.7 调试与读报错(Day 1 Block 6)

知识点
读 Traceback:从最后一行看异常名和信息,再往上找自己文件的行号 A
常见异常含义:NameErrorTypeErrorValueErrorIndexErrorKeyErrorZeroDivisionErrorAttributeErrorIndentationErrorSyntaxError A
3.14 报错会给拼写建议("Did you mean: ...")、彩色 traceback A
print(f"{x=}") 快速调试;VS Code 断点 + 单步 + 变量面板 A
assert 条件, "信息" 自测 B

3.8 异常处理(Day 2 Block 1)

知识点
try / except ValueError:except (A, B):as eelsefinally A
输入校验循环:while True: try: ... break except ValueError: 提示 A
raise ValueError("原因");何时抛、何时捕 A
except: 是坏习惯(会吞掉 Ctrl+C);只捕获你能处理的异常 A(陷阱)
自定义异常 class InvalidScoreError(ValueError): pass B
3.14 允许 except A, B: 不带括号 —— 我们统一写带括号 C
异常组 except*finallyreturn 会被 3.14 警告 C

3.9 文件、路径、JSON、CSV(Day 2 Block 2)

知识点
with open(path, "r", encoding="utf-8") as f:;模式 r / w / aread / readlines / for line in f / write A
Windows 默认编码是 GBK:不写 encoding="utf-8" 迟早 UnicodeDecodeError;Python 3.15(2026-10)起默认 UTF-8 A
pathlib.PathPath("data") / "a.txt"exists()read_text(encoding=)write_text()mkdir(parents=True, exist_ok=True)glob("*.py").name / .suffix / .stem A(前四个)/ B(其余)
json.load / json.dump(data, f, ensure_ascii=False, indent=2)json.loads / dumps;JSON 只有 dict/list/str/数字/bool/null A
csv.DictReader / DictWriternewline="" B
文件不存在时 FileNotFoundError → 用默认值恢复 A
os.path、手动 f.close() C(能读懂老代码)
3.14 新增 Path.copy() / move() C

3.10 模块、包与标准库(Day 2 Block 3)

知识点
import math / from random import randint / import x as yif __name__ == "__main__": 的作用 A
自己写一个模块并 import(同目录);模块名不要和标准库重名(random.py 会坑死你) A
randomrandint / choice / shuffle / sample / seed A
mathsqrt / floor / ceil / pi / gcd A
datetimedate.today()datetime.now()strftime("%Y-%m-%d")timedelta B
collections.Counter / defaultdictstatistics.mean / median B
sys.argvsys.exit()time.sleep() B
uv add rich 安装第三方库并 from rich import print B
from x import * 的危害 A(陷阱)
itertoolsfunctoolsreargparselogging C

3.11 面向对象(Day 2 Block 4)

知识点
"一切皆对象":"a".upper()[].append() 都是方法调用 A
class__init__self、实例属性、方法、创建对象、调用方法 A
@dataclass:自动生成 __init__/__repr__/__eq__field(default_factory=list) B(强推)
__str__ / __repr____eq__ B
继承 class B(A):super().__init__()、方法重写 B
组合(一个类持有另一个类的列表)优先于继承 B
类属性 vs 实例属性、@property B
多重继承、MRO、__slots__、元类、抽象基类 C

3.12 Pythonic 写法、迭代与类型(Day 2 Block 5)

知识点
列表/字典/集合推导式(含条件、嵌套一层) A
sorted(xs, key=lambda s: s.score, reverse=True)min/max(key=) A
any / allzip / enumeratesum(生成器表达式) A
生成器函数 yield、生成器表达式 (x for x in ...);迭代器 iter / next B
match 语句(字面值、case [a, b]case {"k": v}case _ B
海象 := C
类型注解全套:list[int]dict[str, list[int]]X | Nonetuple[int, str];旧的 typing.List / Optional 只需能读 B
f-string 3.12 增强;t-string(3.14)只知道存在 B / C

3.13 测试与代码质量(Day 2 Block 6)

知识点
pytest:test_*.pydef test_xxx(): assert ...uv run pytest -q、读 ./F/E 输出 B(强推)
pytest.raises(ValueError)@pytest.mark.parametrize B
可测试的设计:把"算"和"打印/输入"分开,纯函数返回值 A
PEP 8 要点:snake_case、常量 UPPER_CASE、4 空格、每行 ≤ 88、有意义的名字 A
ruff check / ruff format B
文档字符串、# 注释解释为什么而不是做什么 B

3.14 只需"知道存在"的 Python 世界(不占课时,README 一句话)

主题 一句话 搜什么
异步 asyncioasync/await 单线程内并发处理大量 I/O 等待 "python asyncio tutorial"
多线程 / 多进程 / free-threading(3.13 实验、3.14 正式支持的无 GIL 构建) CPU 并行;默认安装仍带 GIL "python free-threading PEP 703"
JIT(3.13+ 实验) 运行时编译加速,默认关闭 "CPython JIT PEP 744"
子解释器 concurrent.interpreters(3.14) 同一进程多个隔离解释器 "PEP 734"
t-strings t"..."(3.14) 给库作者安全拼接 SQL/HTML 的模板字符串 "PEP 750"
注解延迟求值(3.14)、annotationlib 类型注解不再立刻求值 "PEP 649"
Python 3.15(2026-10-01 发布):UTF-8 默认、lazy importfrozendict 之后 encoding="utf-8" 可省,但现在必须写 "What's New in Python 3.15"
打包发布:pyproject.tomluv build、PyPI 把项目变成别人可 pip install 的包 "uv publish"
常见库版图 requests/httpx(网络)、numpy/pandas/matplotlib(数据)、pygame(游戏)、FastAPI/Flask(Web)、rich/typer(命令行)、pytest(测试) 按方向搜
Git / GitHub 版本控制与协作,三天后第一周学 "git 入门"

4. 老写法 → 现代写法(看老教程时对照)

老教程常见 现在这样写
"%s 今年 %d 岁" % (name, age)"{}".format(x) f"{name} 今年 {age} 岁"
os.path.join(a, b)os.path.exists(p) Path(a) / bPath(p).exists()
f = open(p); ...; f.close();不写编码 with open(p, encoding="utf-8") as f:
from typing import List, Dict, Optional list[int]dict[str, int]int | None
python -m venv .venv → 激活 → pip install x uv add xuv run python main.py
print "hi"raw_input()xrange() Python 2 遗留,直接关掉那个教程
except: except ValueError: / except (A, B) as e:
if x == 1: ... elif x == 2: 值很多时可用 match x: case 1: ...

5. 阅读资料怎么用(详见 research/03

用途 资源
中文主线(每块 10 分钟) 廖雪峰 Python 教程 https://liaoxuefeng.com/books/python/introduction/index.html
英文主线 / 练习题(练英文阅读) Automate the Boring Stuff 第 3 版(2025,免费在线)https://automatetheboringstuff.com/
官方对照(每块 3–5 分钟"官方怎么说") 官方教程中文版(3.14.7)https://docs.python.org/zh-cn/3/tutorial/;标准库 https://docs.python.org/zh-cn/3/library/
可视化引用/作用域 Python Tutor https://pythontutor.com/(列表别名、函数栈帧、可变默认参数三处必用)
补充练习 Exercism Python(146 题免费)https://exercism.org/tracks/python;Codewars 8kyu 热身
基础没懂时补课 futurecoder(免费、中文)https://futurecoder.io/
三天后 CS50P(免费十周)https://cs50.harvard.edu/python/;Think Python 3e(免费)https://allendowney.github.io/ThinkPython/

不要用:仍写 print "x" / raw_input() 的教程;未标 Python 版本的"全套视频";让你先装 Anaconda 的基础教程。


6. 三天之后(后续路线,通用版)

  • D+1(周二):15 分钟闭卷重写周一项目里最难的那个函数。
  • D+3(周四):45 分钟:让 AI 按 ai-guide.md 模板 5 出一套 10 题交错测验并限时完成。
  • D+7(下周日):1.5 小时:不看旧代码,重写一个不同的候选项目(比如周一做了待办,就做 CSV 分析)。
  • 第 2–4 周(每周 5–8 小时):CS50P 第 4–9 周材料 + 每周一个 Exercism 概念;学 Git(init/add/commit/log,推到 GitHub)。
  • 第 5–8 周:按兴趣选一条线:数据(pandas + matplotlib)/ 游戏(pygame)/ 自动化(requests + 文件批处理)/ Web(FastAPI)。每条线先做一个 300 行项目再学下一个库。
  • D+30:2 小时独立完成一个结合字典 + 文件 + 类 + 测试的新项目,对照 checklist.md 复评三档。

7. 调研报告索引

文件 内容 对计划的影响
research/00-index.md 索引与各报告一句话结论、采纳/未采纳说明
research/01-python-version-and-new-features.md 3.14.7 最新、3.15 十月发布、3.12–3.14 特性分级、过时写法对照 教学基准 3.14;t-string 等只点名
research/02-toolchain-windows-uv-ruff-vscode.md uv/VS Code/ruff 用法、Day 1 环境 45 分钟清单、Windows 8 大坑 Block 0 直接照抄
research/03-learning-resources-zh-en.md 中英文资源核实、知识点 → 章节映射、过时资源黑名单 第 5 节
research/04-core-knowledge-map-and-pitfalls.md 8 套大纲对照、知识点三档清单、25 条陷阱含代码 第 3 节知识地图;每块的"陷阱反例"
research/05-learning-science-and-ai-usage.md 检索练习/PRIMM/Parsons/刻意练习上限、2024–26 AI 学习研究、提示词模板 50+10 节奏、晨测、AI 七条规则
research/06-exercises-projects-and-testing.md CS50P/Exercism 题库、6 种练习模式、3 个项目规格、uv+pytest+ruff 最小用法 练习设计;project/README.md