第 27 章 包管理与项目工程化

27.1 虚拟环境：venv

虚拟环境隔离项目依赖，避免包版本冲突：

# 创建虚拟环境
python -m venv .venv

# 激活
# Linux / macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate

# 确认激活
which python    # 应该指向 .venv 中的 python
pip list        # 只有 pip 和 setuptools

# 退出
deactivate

为什么需要虚拟环境？

项目 A 需要 requests==2.28
项目 B 需要 requests==2.31
→ 没有虚拟环境，只能装一个版本
→ 有虚拟环境，各自独立，互不影响

27.2 pip 与依赖管理

# 安装包
pip install requests
pip install requests==2.31.0        # 指定版本
pip install "requests>=2.28,<3.0"  # 版本范围
pip install -e .                    # 可编辑模式安装当前项目

# 卸载
pip uninstall requests

# 查看已安装的包
pip list
pip show requests    # 包详情

# 导出/导入依赖
pip freeze > requirements.txt
pip install -r requirements.txt

# 升级
pip install --upgrade requests
pip install --upgrade pip

requirements.txt

# requirements.txt
requests==2.31.0
numpy>=1.24,<2.0
pandas~=2.0       # 兼容版本（>=2.0, <3.0）

# 开发依赖通常放单独文件
# requirements-dev.txt
-r requirements.txt    # 包含生产依赖
pytest>=7.0
ruff>=0.1.0
mypy>=1.0

27.3 pyproject.toml 与现代项目结构

pyproject.toml 是 Python 项目的标准配置文件（PEP 518/621）：

项目结构

my-project/
├── pyproject.toml        # 项目配置（核心）
├── README.md
├── LICENSE
├── src/
│   └── mypackage/
│       ├── __init__.py
│       ├── core.py
│       └── utils.py
├── tests/
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
└── docs/

pyproject.toml

[project]
name = "mypackage"
version = "0.1.0"
description = "我的 Python 包"
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.10"
authors = [
    {name = "Alice", email = "alice@example.com"},
]
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "ruff>=0.1.0",
    "mypy>=1.0",
]

[project.scripts]
mytool = "mypackage.cli:main"

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

# 工具配置
[tool.ruff]
line-length = 88
target-version = "py312"

[tool.pytest.ini_options]
testpaths = ["tests"]

[tool.mypy]
python_version = "3.12"
strict = true

# 安装项目（含依赖）
pip install .
pip install -e .          # 可编辑模式（开发用）
pip install -e ".[dev]"   # 包括开发依赖

27.4 构建与发布包到 PyPI

构建

pip install build
python -m build
# 生成:
# dist/mypackage-0.1.0.tar.gz    (源码包)
# dist/mypackage-0.1.0-py3-none-any.whl  (wheel 包)

发布到 PyPI

pip install twine

# 上传到 TestPyPI（测试）
twine upload --repository testpypi dist/*

# 上传到 PyPI（正式）
twine upload dist/*

# 使用 API token
twine upload dist/* -u __token__ -p pypi-xxxxxxxx

发布到 TestPyPI 测试

# 从 TestPyPI 安装测试
pip install --index-url https://test.pypi.org/simple/ mypackage

27.5 uv：新一代 Python 包管理器

uv 是用 Rust 编写的超快 Python 包管理工具：

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/macOS
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

包管理

# 创建项目
uv init my-project
cd my-project

# 添加依赖
uv add requests
uv add --dev pytest ruff

# 移除依赖
uv remove requests

# 同步依赖
uv sync

# 运行命令
uv run python script.py
uv run pytest

Python 版本管理

# 安装 Python
uv python install 3.13
uv python install 3.12 3.11

# 查看已安装版本
uv python list

# 固定项目 Python 版本
uv python pin 3.13

uv 项目结构

my-project/
├── pyproject.toml
├── uv.lock          # 锁定文件（精确版本）
├── .python-version  # Python 版本
└── src/
    └── my_project/
        └── __init__.py

# uv 生成的 pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.31",
]

[dependency-groups]
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
]

uv vs pip 性能对比

# pip
time pip install django  # ~10 秒

# uv
time uv pip install django  # ~0.5 秒（快 20 倍）

uv 的优势：

• 比 pip 快 10-100 倍
• 内置虚拟环境管理
• 内置 Python 版本管理
• 锁文件确保可重现构建
• 兼容 pip 和 pyproject.toml

本章小结：现代 Python 项目以 pyproject.toml 为核心，用虚拟环境隔离依赖，用 src 布局组织代码。uv 是新一代包管理器，集 pip + venv + pyenv 于一身，速度极快。掌握这些工程化工具，你的 Python 项目就能像专业项目一样组织和分发。