Python 中文知识库

本页承担 README 职责：介绍知识库定位、目标读者、版本基线、安装运行、完整目录、分阶段学习路线、统一示例项目、验证流程、维护规则与检索增强生成（Retrieval-Augmented Generation，RAG）使用建议。

一、知识库简介

这是一套系统、准确、可验证、可持续维护的 Python 中文知识库。它不只罗列语法与应用程序接口（Application Programming Interface，API），而是解释语言设计、对象模型、类型语义、运行机制、工程取舍、适用边界、错误用法与验证方法。

内容组织遵循"一个首页 + 一个术语表 + 多个主题目录"的形式，每篇文档聚焦一个可独立检索的问题，天然适配按章节切分后的 RAG 检索。

在涉及并发、异步、内存、性能与解释器等话题时，本库严格区分五个层次，避免把实现细节当成语言的永久保证：

二、目标读者与前置知识

读者	使用方式	建议起点
零基础学习者	从第 01 章按序学习	01 → 02 → 03 → 04
应用 / 后端开发者	速查类型、对象模型、并发、Web、数据库	03、05、07、08、10-12、17、18
数据工程师	关注 I/O、数据处理、性能	15、19、21、22
测试工程师	关注测试与验证方法	09、20
初级架构师	关注项目设计、打包、部署、可观测性	23、24、26、27

前置知识：具备基础计算机与命令行知识即可，不要求有其他编程语言经验。若你熟悉 Java、C++ 或 Go，请注意本库会显式提示这些语言的对象、并发与类型语义不能机械套用到 Python。

三、版本、解释器与平台基线

• 默认解释器：CPython（Python 官方参考实现）。
• 默认版本：以当前受支持的稳定版本 Python 3.14 为主，同时标注仍在官方支持周期内的次新版本（3.13 / 3.12 / 3.11）差异。
• 核验环境：CPython 3.12.14 与 3.14.6，macOS 26.6.2（arm64），核验日期 2026-09-07。
• 示例平台：默认运行于 Linux 与 macOS；存在 Windows 差异时单独说明（如虚拟环境路径 .venv\Scripts\python.exe）。
• 构建元数据：项目统一使用 pyproject.toml 描述构建系统与项目元数据。
• 虚拟环境：默认使用标准库 venv；第三方工具仅在有明确收益时引入并说明。

版本纪律：涉及随版本变化的语法、类型系统、标准库、命令参数与 CPython 行为时，正文会标注首次支持版本、当前行为、弃用状态与迁移注意事项。无法确认者标记为"待验证"，并给出官方资料路径或最小验证程序。

四、安装与运行

# 1. 确认解释器版本
python3 --version

# 2. 为学习/示例创建隔离虚拟环境
python3 -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate

# 3. 升级 pip
python -m pip install --upgrade pip

# 4. 运行统一示例项目（见第七节）
cd docs/development/python/principles/example-project
python -m pip install -e ".[dev]"
python -m tasklib demo

五、完整目录

标注 ✅ 的章节已生成正文；标注 🚧 的章节尚在分批生成中。

已完成（第一、二批）

• 术语表（glossary） ✅
• 01 简介与安装 ✅
  • 章节导览
  • Python 是什么、定位与设计理念
  • 安装、解释器、REPL 与开发工具
  • 虚拟环境与第一个程序
• 02 程序结构、模块与导入 ✅
  • 章节导览
  • 脚本、模块、包与命名空间
  • 导入系统与 __main__
  • 基础包管理：venv、pip 与 pyproject
• 03 变量、对象、基础类型与可变性 ✅
  • 章节导览
  • 名字绑定、对象、身份与相等性
  • 数值、布尔、字符串、字节与 None
  • 可变与不可变、浅拷贝与深拷贝
• 04 集合、控制流程与函数 ✅
  • 章节导览
  • 列表、元组、字典、集合与迭代协议
  • 控制流程：if/for/while/match 与异常
  • 函数、参数、闭包与装饰器基础
• 05 类型提示与数据建模 ✅
  • 章节导览
  • 类型提示、泛型、协议与类型缩窄
  • dataclass、TypedDict、NamedTuple 与枚举
• 06 面向对象编程 ✅
  • 章节导览
  • 类、实例、组合、继承与 MRO
  • 属性查找、描述符、魔术方法与抽象设计
• 07 异常与资源管理 ✅
  • 章节导览
  • 异常层次、异常链、错误边界与重试
  • with、contextlib 与异常安全
• 08 并发与多线程 ✅
  • 章节导览
  • 线程、GIL 与并发模型选择
  • 同步原语、线程池与并发故障
• 09 多进程 ✅
  • 章节导览
  • 进程模型、启动方式与 IPC
  • 进程池、序列化、关闭与测试
• 10 asyncio ✅
  • 章节导览
  • 协程、任务、Future 与事件循环
  • 结构化并发、取消、超时与背压
• 11 CPython、内存与运行时 ✅
  • 章节导览
  • CPython 执行模型、代码对象与字节码
  • 引用计数、循环 GC、弱引用与内存诊断
• 12 常用标准库 ✅
  • 章节导览
  • collections、itertools、functools 与 heapq
  • 正则、时间、精确数值与随机数
  • 日志、命令行、配置、子进程与信号
• 13 I/O、文件与序列化 ✅
  • 章节导览
  • pathlib、文件系统与原子写入
  • 文本、二进制、编码、缓冲与大文件
  • JSON、CSV、XML、pickle、压缩与哈希
• 14 网络编程 ✅
  • 章节导览
  • Socket、TCP/UDP、DNS 与协议分帧
  • TLS 与 HTTP 客户端工程实践
• 15 Web 开发 ✅
  • 章节导览
  • WSGI、ASGI 与请求生命周期
  • 路由、中间件、认证、错误与生产边界
• 16 数据库 ✅
  • 章节导览
  • DB-API、参数化查询与事务
  • 连接池、锁、ORM、迁移与测试
• 17 数据处理 ✅
  • 章节导览
  • 数据摄取、Schema、缺失值与质量
  • 分块、向量化、性能与可复现性
• 18 测试 ✅
  • 章节导览
  • pytest、fixture、参数化与异步测试
  • Mock、性质测试、集成测试、覆盖率与稳定性
• 19 调试与性能分析 ✅
  • 章节导览
  • 调试工作流、pdb、Traceback 与故障现场
  • timeit、cProfile、tracemalloc 与基准纪律
• 20 性能优化 ✅
  • 章节导览
  • 优化方法、复杂度、数据结构与缓存
  • CPU、内存、I/O、并发与批处理优化
• 21 打包与依赖管理 ✅
  • 章节导览
  • pyproject、构建后端、sdist 与 Wheel
  • 依赖、锁文件、供应链安全与发布
• 22 项目设计 ✅
  • 章节导览
  • src 布局、分层、依赖倒置与组合根
  • 配置、公共 API、演进与质量门禁
• 23 安全 ✅
  • 章节导览
  • 威胁建模、输入校验、注入与反序列化
  • SSRF、XSS、CSRF、认证与授权
  • 密码、Token、密钥、依赖与制品安全
• 24 可观测性 ✅
  • 章节导览
  • 结构化日志、关联 ID、上下文与脱敏
  • 指标、分布式 Trace、SLI/SLO 与健康检查
• 25 部署与运维 ✅
  • 章节导览
  • 应用服务器、进程模型与容器镜像
  • 信号、健康检查、请求排空与优雅退出
  • 滚动发布、回滚、迁移与生产运维
• 26 故障排查 ✅
  • 章节导览
  • 语法、类型、导入与依赖故障
  • 运行时、并发、内存与性能故障
  • 生产故障响应与发布问题排查
• 27 版本差异与迁移 ✅
  • 章节导览
  • Python 3.11-3.14 核心差异矩阵
  • 弃用、兼容层与能力探测
  • 生产迁移 Runbook 与回归矩阵
• 28 综合项目、练习与面试题 ✅
  • 章节导览
  • 综合项目需求、架构与风险模型
  • 综合项目实现、测试、交付与验收
  • 分级练习、代码审查题与参考要点
  • 场景化面试题、答案与评分标准

生成状态

• ✅ 01-28 全部计划章节已生成并接入导航。

章节按复杂度将 Prompt 建议的 31 个主题目录做了合并归类（例如 concurrency 与 threading 合并、multiprocessing 独立成章），核心主题无遗漏，编号与本目录一致。

六、分阶段学习路线

• 零基础路线：01 → 02 → 03 → 04 → 05 → 07 → 06
• 后端工程师速查：03、05、07、08、10、15、16、23
• 数据工程师路线：13、17、19、20
• 测试工程师路线：07、09、18
• 性能工程师路线：11、19、20、08、10

七、统一示例项目与数据模型

全库复用一个可运行的示例项目 tasklib（极简任务管理库 + 命令行工具），确保示例可独立复现、命名一致。它采用 src 布局，仅依赖标准库，覆盖数据建模、运行时诊断、安全、可观测性、生命周期、故障快照、I/O、网络、并发、命令行入口与单元测试。

核心数据模型（详见 示例项目 README）：

元素	类型	说明
Task	@dataclass(slots=True)	任务记录，__post_init__ 校验标题不变量
TaskStatus	StrEnum	todo / doing / done
Priority	IntEnum	LOW=1 / MEDIUM=2 / HIGH=3
TaskRepository	类（上下文管理器）	内存仓储，with 退出时释放资源
TaskService	类	注入仓储（依赖倒置），编排创建/完成/待办排序
TaskError 层次	异常	ValidationError / TaskNotFoundError

八、代码、测试、类型与安全验证流程

除专门展示错误的示例外，代码必须通过：语法编译 → 格式 → Lint → 类型检查 → 单元测试。统一命令：

.venv/bin/python -m compileall -q src tests   # 语法编译
.venv/bin/ruff format --check .                # 格式
.venv/bin/ruff check .                         # Lint
.venv/bin/mypy src tests                       # 类型检查（strict）
.venv/bin/pytest                               # 单元测试

第七批完成后的累计验证结果（核验日期 2026-09-07，CPython 3.12.14 / 3.14.6）：

检查项	工具	结果
语法编译	compileall	✅ 通过
格式	ruff format --check 0.16.6	✅ 53 files already formatted
Lint	ruff check 0.16.6	✅ All checks passed
类型检查	mypy 2.3.1（strict）	✅ no issues found in 52 source files
单元测试	pytest 9.1.1	✅ 97 passed
隔离构建	PyPA build + Hatchling 1.32.0	✅ sdist + Wheel
静态安全扫描	Bandit 1.9.4	✅ 无未抑制问题
依赖漏洞审计	pip-audit 2.10.1	✅ 当前开发环境无已知漏洞
异步诊断	PYTHONASYNCIODEBUG=1	✅ 无未等待协程、遗留任务或未关闭资源告警
命令行运行	python -m tasklib demo	✅ 输出与文档一致

1、第二批覆盖矩阵

主题	正文	可执行证据
类型提示、泛型、协议、缩窄	05-01	typing_models.py + 4 tests
dataclass、TypedDict、NamedTuple、Enum	05-02	models.py / typing_models.py
类、组合、继承、MRO	06-01	oop.py + MRO 实验
描述符、魔术方法、ABC、元类	06-02	PositiveInt + 6 tests
异常链、错误边界、重试	07-01	ConfigError.__cause__ 测试
with、contextlib、异常安全	07-02	提交/回滚/恢复 4 tests
线程、GIL、同步原语、线程池	08-01/02	Barrier/Lock/Queue 4 tests
多进程、IPC、进程池、启动方式	09-01/02	spawn/Pool/Pipe 2 tests
协程、Task、Future、事件循环	10-01	asyncio_examples.py
取消、超时、背压、TaskGroup	10-02	asyncio debug 下 3 tests

2、第三批覆盖矩阵

主题	正文	可执行证据
CPython 执行模型、字节码、导入缓存	11-01	runtime_examples.py
引用计数、循环 GC、弱引用、tracemalloc	11-02	5 runtime tests
容器、迭代器、缓存与堆	12-01	stdlib_examples.py
正则、时区、Decimal、安全随机数	12-02	stdlib tests
日志、配置、子进程、信号	12-03	安全 subprocess 测试
pathlib、路径约束、原子写入	13-01	io_examples.py
编码、缓冲、流式大文件	13-02	分块哈希测试
JSON/CSV/XML/pickle/压缩/哈希	13-03	JSON Lines + SHA-256 tests
Socket、TCP/UDP、DNS、协议分帧	14-01	socketpair tests
TLS、HTTP、重试、SSRF	14-02	本地 HTTP server tests

3、第四批覆盖矩阵

主题	正文	可执行证据
WSGI/ASGI、请求生命周期	15-01	WSGI/ASGI callable tests
路由、中间件、认证、错误模型	15-02	Bearer 与错误响应 tests
DB-API、参数化、事务	16-01	SQLite 事务 tests
连接池、锁、ORM、迁移	16-02	工程边界与集成策略
Schema、缺失值、质量	17-01	CSV 参数化坏行 tests
分块、向量化、可复现性	17-02	分块聚合 tests
pytest、fixture、异步测试	18-01	全项目测试体系
Mock、性质/集成测试、覆盖率	18-02	63 tests + 严格门禁

4、第五批覆盖矩阵

主题	正文	可执行证据
pdb、Traceback、faulthandler	19-01	调试命令与故障流程
timeit、cProfile、tracemalloc	19-02	profiling_examples.py
复杂度、结构、缓存	20-01	optimization_examples.py
CPU、内存、I/O、并发优化	20-02	有界批处理 tests
pyproject、sdist、Wheel	21-01	隔离构建 + Wheel 内容检查
锁文件、哈希、供应链与发布	21-02	pip secure install 流程
src 布局、分层、依赖注入	22-01	settings.py 组合根
配置、API 演进、质量门禁	22-02	配置参数化 tests

5、第六批覆盖矩阵

主题	正文	可执行证据
输入校验、注入、路径与反序列化	23-01	Bandit + 既有边界 tests
SSRF、XSS、CSRF、认证与授权	23-02	重定向与 Web 边界 tests
密码、Token、密钥与供应链	23-03	security_examples.py + pip-audit
结构化日志、关联 ID 与脱敏	24-01	observability_examples.py
指标、Trace、SLI/SLO 与 Probe	24-02	基数/健康检查 tests
服务器、Worker 与容器	25-01	构建/部署边界
信号、排空与优雅退出	25-02	operations_examples.py
发布、回滚、迁移与运维	25-03	发布状态与 Runbook
语法、类型、导入与依赖排障	26-01	模块来源/包版本快照
运行时、内存、并发与性能排障	26-02	Profile/内存/并发证据链
生产事件与发布故障	26-03	脱敏 runtime snapshot

6、第七批覆盖矩阵

主题	正文	可执行证据
Python 3.11-3.14 核心差异	27-01	runtime_capabilities()
弃用、兼容层与能力探测	27-02	supports_syntax() + 5 tests
生产迁移与回归矩阵	27-03	版本窗口与制品验证
综合项目架构与风险	28-01	capstone.py
综合实现、交付与验收	28-02	4 capstone tests + Wheel
分级练习与代码审查	28-03	9 组练习 + 3 组审查题
场景化面试与评分	28-04	20 题 + 系统设计题

安全扫描只能发现规则库已知模式，不覆盖业务授权、未知漏洞、运行时配置或基础设施权限；仍需人工审查、威胁建模和按风险选择渗透测试。

九、术语、代码与写作规范

• 语言：所有解释、注释与用户可见文本使用中文；标识符、API、命令与协议字段保留原文。
• 术语：首次出现重要术语时附英文名称或缩写，例如全局解释器锁（Global Interpreter Lock，GIL）、类型提示（Type Hints）；全库术语归一见 术语表。
• 代码风格：遵循 PEP 8；示例默认加类型标注并通过 ruff + mypy 检查；以清晰、惯用、可测试为优先，不为展示设计模式制造不必要抽象。
• 层次标注：区分"规范保证 / 标准库契约 / CPython 实现细节 / 其他实现差异 / 环境差异"，性能结论必须附环境与方法。
• 失败路径：示例尽量给出异常类型、原因与资源清理方式。

十、官方资料引用规范

版本、语言语义、标准库、类型、构建工具、发布说明与安全公告优先查询官方资料，来源优先级：

1. Python Language Reference 与 Python Data Model。
2. Python 官方标准库文档。
3. Python Packaging User Guide 与 PyPA 项目官方文档。
4. PEP 原文、Python Release Notes 与 Security 页面。
5. CPython 官方源码、Issue 与开发者指南。
6. 所用框架、数据库驱动与数据工具的官方文档。
7. 经过交叉验证的高质量工程资料。

十一、内容维护、版本升级与弃用规则

1. 版本纪律：版本敏感内容说明首次支持版本、当前行为、弃用状态与迁移注意事项。
2. 不臆造：不编造语法、标准库 API、PEP、命令参数、类型规则或解释器配置；无法确认者标注"待验证"并给出验证方法。
3. 不静默覆盖：过期内容保留适用版本或迁移链接，不直接删除历史结论。
4. 风险显式化：生产变更、数据删除、权限修改与外部调用必须显式说明风险与安全替代方案。
5. 交叉引用完整：新增章节需回填相关章节的"关联章节"，避免断链。

十二、RAG 切分与检索建议

• 按文档切分：每篇主题文档是一个自包含知识单元，长文按二级或三级标题切分。
• 保留上下文：每个切片保留标题路径、Python 版本、平台、前置知识与来源；代码、输出、解释与警告尽量不跨切片。
• 利用 frontmatter：title / slug / category / python_versions / verified_at / keywords 可作为过滤与召回增强字段。
• 版本过滤：检索时用 python_versions 字段按目标版本过滤，避免召回不适用的版本行为。
• 术语归一：结合 术语表 做同义词归一（如"协程 / Coroutine"），提升召回率。

十三、检索关键词

Python 知识库、Python 教程、CPython、类型提示、数据模型、可变性、asyncio、GIL、多进程、打包、pyproject、pytest、性能分析、安全编码、RAG 知识源。