包管理与发布

把脚本升级为可安装、可版本化、可复用的 Python 包，是团队协作与 CI/CD 的基础。前置 python-fundamentals 的 modules 课；Agent 项目常拆成多包，见 ai-agents-essentials；/roadmaps/python。

学习目标

• 用 pyproject.toml 声明项目元数据与依赖
• 理解 src layout 与 pip install -e . 可编辑安装
• 知道 wheel/sdist 构建与私有 PyPI 发布流程

项目结构（src layout）

lesson-tools/
├── pyproject.toml
├── README.md
├── src/
│   └── lesson_tools/
│       ├── __init__.py
│       └── stats.py
└── tests/
    └── test_stats.py

pyproject.toml

[project]
name = "lesson-tools"
version = "0.1.0"
description = "Draft lesson statistics for CodeRoadMap"
requires-python = ">=3.11"
dependencies = []

[project.optional-dependencies]
dev = ["pytest", "ruff", "mypy"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/lesson_tools"]

# src/lesson_tools/stats.py
from pathlib import Path

def count_chars(draft_dir: Path) -> dict[str, int]:
    return {
        p.name: len(p.read_text(encoding="utf-8"))
        for p in sorted(draft_dir.glob("*.md"))
    }

安装与构建

pip install -e ".[dev]"     # 可编辑模式 + 开发依赖
python -m build             # 生成 dist/*.whl 与 .tar.gz
pip install dist/lesson_tools-0.1.0-py3-none-any.whl

版本与锁文件

• 语义化版本：MAJOR.MINOR.PATCH
• 应用项目可用 pip-tools / uv lock 生成 lockfile
• 库项目保持依赖范围宽松（>=, <）

练习

• 新建 mini 包，实现 hello() 并在 REPL 中 from pkg import hello
• 运行 pip install -e . 后修改源码，确认无需重装即可生效
• 用 python -m build 生成 wheel 并检查 dist 目录

小结

packaging 让代码从「文件」变成「产品」。 下一课 typing 强化接口契约，与 pyproject 中的类型检查配置衔接。