4. Python 环境准备：版本选择、虚拟环境与依赖管理

配置漂移证据报告自动生成工具依赖 Python 生态。本章将指导你完成从版本选择、虚拟环境搭建到依赖管理的全流程配置，确保开发环境可复现、可隔离、可交付。

4.1 Python 版本选择

本课程推荐使用 Python 3.10+。原因如下：

版本 支持状态 本课程推荐度 说明
3.8 安全维护期 不推荐 缺少 match 语句、zoneinfo 等现代特性
3.9 安全维护期 可选 可运行，但部分依赖已开始放弃 3.9
3.10 稳定版 强烈推荐 结构模式匹配、精确错误提示、类型联合语法
3.11 最新稳定 推荐 性能提升约 10-25%，兼容性良好
3.12+ 前沿 谨慎 部分第三方库可能尚未完全适配
版本检查命令： 
python --version
# 或
python3 --version

如果输出低于 3.10，请先升级 Python 或使用 pyenv 管理多版本。

4.2 虚拟环境搭建

虚拟环境隔离项目依赖，避免全局污染。本课程提供两种方案：venv（内置）和 conda（科学计算场景）。

方案一：使用 venv（推荐）

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

# 激活虚拟环境（Linux/macOS）
source .venv/bin/activate

# 激活虚拟环境（Windows PowerShell）
.venv\Scripts\Activate.ps1

# 验证激活
which python   # Linux/macOS
where python   # Windows

方案二：使用 conda（可选）

# 创建环境并指定 Python 版本
conda create -n drift-report python=3.10 -y

# 激活环境
conda activate drift-report
常见陷阱： 不要将虚拟环境放在项目目录之外；不要将 .venv 提交到 Git 仓库——务必在 .gitignore 中添加 .venv/。

4.3 依赖管理：pip 与 poetry

依赖管理工具决定了项目可复现性。本课程对比两种主流方案：

特性 pip + requirements.txt poetry
锁定文件 需手动生成 requirements.txt 自动生成 poetry.lock
依赖解析 线性安装，可能冲突 解析器自动解决依赖树
虚拟环境 需手动创建 自动创建与管理
发布支持 无 内置 PyPI 发布
学习曲线 低 中

使用 pip 管理依赖

# 安装依赖
pip install pyyaml jinja2 paramiko

# 导出依赖清单
pip freeze > requirements.txt

# 从清单安装（新环境）
pip install -r requirements.txt

使用 poetry 管理依赖（推荐）

# 安装 poetry
pip install poetry

# 初始化项目
poetry init

# 添加依赖
poetry add pyyaml jinja2 paramiko

# 安装所有依赖
poetry install

# 进入虚拟环境
poetry shell
本课程采用 poetry 作为默认依赖管理工具。 所有示例代码和配置均基于 pyproject.toml 组织。如果你更习惯 pip，课程也提供对应的 requirements.txt 作为备选。

4.4 IDE 推荐与配置

合适的 IDE 能显著提升开发效率。本课程推荐以下两种：

IDE 适用场景 关键插件/配置
VS Code 轻量、跨平台、插件丰富 Python、Pylance、Jupyter、GitLens
PyCharm 专业 Python 开发、重构、调试 内置数据库工具、Docker 支持、远程解释器

VS Code 快速配置

# 安装 Python 扩展后，选择解释器
# 快捷键: Ctrl+Shift+P → Python: Select Interpreter
# 选择 .venv 中的解释器路径

# 推荐 settings.json 配置
{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "editor.formatOnSave": true
}

PyCharm 快速配置

# 打开项目后，配置项目解释器
# File → Settings → Project → Python Interpreter
# 选择 Existing environment → 指向 .venv/bin/python

# 推荐插件
# - .ignore（Git 忽略文件支持）
# - Rainbow Brackets（括号着色）
# - CSV Plugin（查看报告数据）
IDE 无关建议： 无论使用哪种 IDE，都建议开启 自动格式化（Black 或 Ruff）和 类型检查（mypy 或 Pyright），这能提前发现配置漂移报告生成逻辑中的类型错误。

4.5 环境验证与架构总览

完成上述配置后，运行以下命令验证环境是否就绪：

# 验证 Python 版本
python --version
# 输出示例: Python 3.10.12

# 验证虚拟环境激活
which python
# 输出应包含 .venv 路径

# 验证核心依赖
python -c "import yaml, jinja2, paramiko; print('All dependencies OK')"

下图展示了本课程推荐的 Python 开发环境整体架构：

Python 开发环境架构 IDE 层：VS Code / PyCharm 依赖管理层：poetry / pip + requirements.txt 虚拟环境层：.venv / conda env Python 3.10+ 解释器 隔离项目依赖 不污染全局环境
环境就绪检查清单：
  • ✅ Python 3.10+ 已安装并加入 PATH
  • ✅ 项目虚拟环境已创建并激活
  • ✅ 核心依赖（pyyaml、jinja2、paramiko）已安装
  • ✅ IDE 已配置正确的 Python 解释器路径
  • ✅ .gitignore 已排除 .venv/ 和 __pycache__/
← 上一章 📖 返回目录 下一章 →