# Python 虚拟环境与包管理

**学习目标**：掌握 Python 虚拟环境的创建与使用，理解包管理的最佳实践，学会使用现代工具链管理项目依赖。

---

## 1. 为什么需要虚拟环境

### 1.1 依赖冲突问题

```
项目 A 需要 Django 3.2
项目 B 需要 Django 4.2
                    ↓
        全局环境只能装一个版本 → 冲突！

解决方案：每个项目使用独立的虚拟环境
```

### 1.2 虚拟环境的作用

- **隔离依赖**：每个项目有独立的包环境
- **版本锁定**：避免全局包版本升级导致兼容问题
- **可重现性**：确保不同机器上运行环境一致
- **干净卸载**：删除虚拟环境即可清除所有依赖

---

## 2. venv（标准库）

### 2.1 创建与激活

```bash
# 创建虚拟环境（Python 3.3+ 内置）
python -m venv myenv

# 激活虚拟环境
# macOS / Linux
source myenv/bin/activate

# Windows (CMD)
myenv\Scripts\activate.bat

# Windows (PowerShell)
myenv\Scripts\Activate.ps1

# 退出虚拟环境
deactivate
```

### 2.2 目录结构

```
myenv/
├── bin/              ← macOS/Linux（Windows 为 Scripts/）
│   ├── activate      ← 激活脚本
│   ├── pip           ← 包管理器
│   └── python        ← Python 解释器
├── lib/
│   └── python3.11/
│       └── site-packages/  ← 安装的第三方包
├── include/          ← C 头文件
└── pyvenv.cfg        ← 配置文件
```

### 2.3 常用操作

```bash
# 查看当前虚拟环境的 Python 路径
which python
# /path/to/myenv/bin/python

# 查看已安装的包
pip list

# 安装包
pip install requests

# 安装指定版本
pip install django==4.2

# 升级包
pip install --upgrade requests

# 卸载包
pip uninstall requests

# 导出依赖
pip freeze > requirements.txt

# 从文件安装依赖
pip install -r requirements.txt
```

---

## 3. requirements.txt

### 3.1 基本格式

```txt
# requirements.txt
# 直接指定版本
Django==4.2.7

# 版本范围
requests>=2.25.0,<3.0.0

# 最小版本
celery>=5.0.0

# 不指定版本（不推荐）
flask

# 从 Git 安装
# git+https://github.com/user/repo.git@branch#egg=package

# 从本地路径安装
# ./my-local-package

# 包含额外依赖
uvicorn[standard]==0.24.0
```

### 3.2 分层管理

```txt
# requirements.txt - 生产环境
-r requirements/base.txt
gunicorn==21.2.0
psycopg2-binary==2.9.9
whitenoise==6.6.0

# requirements/base.txt - 基础依赖
Django==4.2.7
djangorestframework==3.14.0
python-dotenv==1.0.0

# requirements/dev.txt - 开发环境
-r requirements.txt
pytest==7.4.3
pytest-django==4.7.0
flake8==6.1.0
black==23.11.0
```

```bash
# 安装开发依赖
pip install -r requirements/dev.txt

# 安装生产依赖
pip install -r requirements.txt
```

---

## 4. pip 高级用法

### 4.1 配置文件

```ini
# pip.ini (Windows: %APPDATA%\pip\pip.ini)
# pip.conf (macOS/Linux: ~/.pip/pip.conf 或 ~/.config/pip/pip.conf)

[global]
# 使用国内镜像源
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
# 超时设置
timeout = 120
# 信任主机
trusted-host = pypi.tuna.tsinghua.edu.cn

[install]
# 不缓存下载
no-cache-dir = true
```

### 4.2 常用镜像源

```bash
# 临时使用镜像
pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple

# 国内常用镜像
# 清华:    https://pypi.tuna.tsinghua.edu.cn/simple
# 阿里云:  https://mirrors.aliyun.com/pypi/simple
# 中科大:  https://pypi.mirrors.ustc.edu.cn/simple
# 腾讯云:  https://mirrors.cloud.tencent.com/pypi/simple
```

### 4.3 其他实用命令

```bash
# 查看包信息
pip show django

# 查看过期的包
pip list --outdated

# 下载包（不安装）
pip download django -d ./packages/

# 离线安装
pip install --no-index --find-links=./packages/ django

# 检查依赖冲突
pip check

# 升级所有包（谨慎使用）
pip list --outdated --format=freeze | grep -v '^\-e' | cut -d = -f 1 | xargs -n1 pip install -U
```

---

## 5. Poetry（现代包管理）

### 5.1 安装与初始化

```bash
# 安装 Poetry
curl -sSL https://install.python-poetry.org | python3 -

# 或通过 pip
pip install poetry

# 初始化项目
poetry init

# 或从现有项目创建
poetry new my-project
```

### 5.2 项目结构

```
my-project/
├── pyproject.toml       ← 项目配置和依赖
├── poetry.lock          ← 锁定文件（精确版本）
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py
```

### 5.3 pyproject.toml

```toml
[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "A sample project"
authors = ["Your Name <you@example.com>"]
readme = "README.md"
packages = [{include = "my_project"}]

[tool.poetry.dependencies]
python = "^3.11"
django = "^4.2"
requests = "^2.31"
psycopg2-binary = "^2.9"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
black = "^23.11"
flake8 = "^6.1"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
```

### 5.4 常用命令

```bash
# 安装依赖（自动创建虚拟环境）
poetry install

# 仅安装生产依赖（不含 dev 组）
poetry install --without dev

# 添加依赖
poetry add requests
poetry add "django>=4.2,<5.0"

# 添加开发依赖
poetry add pytest --group dev

# 移除依赖
poetry remove requests

# 更新依赖
poetry update
poetry update requests  # 仅更新某个包

# 查看依赖树
poetry show --tree

# 在虚拟环境中运行命令
poetry run python script.py
poetry run pytest

# 激活虚拟环境
poetry shell

# 构建包
poetry build

# 发布到 PyPI
poetry publish
```

---

## 6. uv（超快包管理器）

### 6.1 安装与基本使用

```bash
# 安装 uv（Rust 编写，极快）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境
uv venv

# 激活
source .venv/bin/activate

# 安装包（比 pip 快 10-100 倍）
uv pip install requests
uv pip install -r requirements.txt

# 从 pyproject.toml 同步
uv sync
```

### 6.2 项目管理

```bash
# 初始化项目
uv init my-project

# 添加依赖
uv add django
uv add pytest --dev

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

# 锁定依赖
uv lock
```

---

## 7. conda（数据科学环境）

### 7.1 基本操作

```bash
# 创建环境
conda create -n myenv python=3.11

# 激活环境
conda activate myenv

# 退出环境
conda deactivate

# 安装包
conda install numpy pandas scikit-learn

# 从 conda-forge 安装
conda install -c conda-forge django

# 列出环境
conda env list

# 导出环境
conda env export > environment.yml

# 从文件创建环境
conda env create -f environment.yml

# 删除环境
conda env remove -n myenv
```

### 7.2 environment.yml

```yaml
name: myenv
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.11
  - numpy=1.24
  - pandas=2.0
  - scikit-learn
  - pip
  - pip:
    - django==4.2
    - djangorestframework
```

---

## 8. 工具对比

| 工具 | 速度 | 功能 | 适用场景 |
|------|------|------|----------|
| venv + pip | 标准 | 基础 | 通用、学习 |
| Poetry | 快 | 全功能（构建/发布） | 库开发、中大型项目 |
| uv | 极快 | 兼容 pip | 追求速度的项目 |
| pipenv | 中等 | 全功能 | 中型项目 |
| conda | 慢 | 科学计算生态 | 数据科学、ML |

### 选型建议

```
场景？
├── 学习 / 简单项目 → venv + pip
├── 库 / 包开发     → Poetry
├── 追求极速        → uv
├── 数据科学 / ML   → conda
└── 企业级项目      → Poetry 或 uv
```

---

## 9. .gitignore 配置

```gitignore
# .gitignore
# 虚拟环境
myenv/
.venv/
venv/
env/

# Python
__pycache__/
*.py[cod]
*$py.class
*.so

# 分发/打包
build/
dist/
*.egg-info/
*.egg

# 测试
.pytest_cache/
.coverage
htmlcov/

# IDE
.vscode/
.idea/
*.swp

# 环境变量
.env
.env.local

# 不忽略
!requirements.txt
!pyproject.toml
```

---

## 10. 最佳实践

```python
"""
项目依赖管理最佳实践

1. 锁定版本
   - 生产环境使用精确版本 (==)
   - 开发环境可使用范围版本 (>=)

2. 分层管理
   - requirements/base.txt   基础依赖
   - requirements/dev.txt    开发工具
   - requirements/prod.txt   生产依赖

3. 使用锁文件
   - poetry.lock / uv.lock 确保可重现

4. 定期更新
   - 检查安全更新
   - 逐步升级大版本

5. CI/CD 集成
   - 自动安装依赖
   - 运行 pip check 验证
   - 使用锁文件确保一致性
"""
```

---

## 11. 小结

| 概念 | 工具 | 要点 |
|------|------|------|
| 虚拟环境 | venv / conda | 隔离项目依赖 |
| 包安装 | pip / uv | 安装第三方库 |
| 依赖声明 | requirements.txt / pyproject.toml | 记录依赖 |
| 版本锁定 | poetry.lock / uv.lock | 确保可重现 |
| 现代管理 | Poetry / uv | 全功能工具链 |

---

## 12. 练习题

1. 使用 venv 创建虚拟环境，安装 Django 并导出 requirements.txt。
2. 使用 Poetry 创建一个新项目，添加依赖并生成锁文件。
3. 对比 pip 和 uv 安装同一组依赖的速度差异。
4. 为你的项目设计分层 requirements 文件结构。

---

> **下节预告**：我们将学习 pytest 测试框架，掌握编写高质量单元测试的方法。