2. 环境搭建：Python虚拟环境创建、依赖管理（pip/poetry）与项目初始化

金融特征回放评审对依赖版本一致性要求极高——回放结果若因依赖偏差而不可复现，评审便失去意义。本章从零搭建隔离、可复现的Python开发环境，覆盖虚拟环境创建、依赖锁定与项目骨架初始化。

2.1 为什么需要虚拟环境

金融项目通常同时依赖多个数据科学库（pandas、numpy、scikit-learn）与回放框架（backtrader、zipline-reloaded），不同项目可能要求同一库的不同版本。虚拟环境将每个项目的依赖隔离在独立目录中，避免全局site-packages冲突。

场景	无虚拟环境	有虚拟环境
项目A需pandas 1.5.3	全局安装后影响其他项目	仅项目A环境生效
项目B需pandas 2.0.0	必须降级或升级全局	独立版本，互不干扰
回放评审复现	依赖版本不确定	requirements.txt/pyproject.toml锁定

2.2 使用 venv 创建虚拟环境

Python 3.3+ 内置 venv 模块，无需额外安装。以下为金融特征回放项目的标准创建流程：

1. 创建环境：在项目根目录执行 python -m venv .venv，生成 .venv/ 文件夹。
2. 激活环境：
   • Windows (PowerShell)：.venv\Scripts\Activate.ps1
   • macOS/Linux (bash)：source .venv/bin/activate
3. 验证激活：终端提示符前出现 (.venv) 前缀，which python 指向 .venv/bin/python。

# 创建虚拟环境（项目根目录）
python -m venv .venv

# 激活（macOS/Linux）
source .venv/bin/activate

# 验证
(.venv) $ python --version
Python 3.11.5

2.3 依赖管理：pip + requirements.txt

pip 是 Python 官方包管理器，配合 requirements.txt 可实现基础依赖锁定。适用于小型团队或快速原型阶段。

2.3.1 安装依赖

# 安装核心金融库
pip install pandas==1.5.3 numpy==1.24.3 scikit-learn==1.3.0

# 安装回放框架
pip install backtrader==1.9.78.123

# 安装开发工具
pip install pytest black flake8

2.3.2 导出与复现

# 导出当前环境所有依赖（含子依赖）
pip freeze > requirements.txt

# 在新环境中复现
pip install -r requirements.txt

命令	用途	注意事项
pip freeze	导出精确版本列表	包含所有子依赖，可能冗余
pip list --format=freeze	同上，格式兼容	推荐用于生成 requirements.txt
pip install -r	从文件批量安装	确保 Python 版本一致

2.4 依赖管理进阶：Poetry

Poetry 提供更完善的依赖解析、锁定与打包功能，适合金融特征回放评审这类需要严格版本管控的中大型项目。

2.4.1 安装 Poetry

# 官方推荐安装方式（macOS/Linux）
curl -sSL https://install.python-poetry.org | python3 -

# Windows PowerShell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

# 验证安装
poetry --version
Poetry (version 1.7.1)

2.4.2 初始化项目

# 交互式初始化
poetry init

# 或直接创建新项目骨架
poetry new feature-replay-toolkit

poetry init 会生成 pyproject.toml 文件，这是 Poetry 的核心配置文件。以下为金融回放项目的典型配置：

[tool.poetry]
name = "feature-replay-toolkit"
version = "0.1.0"
description = "金融特征回放评审工具链"
authors = ["QuantTeam <quant@example.com>"]

[tool.poetry.dependencies]
python = "^3.11"
pandas = "^1.5.3"
numpy = "^1.24.3"
scikit-learn = "^1.3.0"
backtrader = "^1.9.78"

[tool.poetry.dev-dependencies]
pytest = "^7.4"
black = "^23.7"
flake8 = "^6.1"

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

2.4.3 安装与锁定

# 安装所有依赖（自动解析冲突）
poetry install

# 仅安装生产依赖
poetry install --only main

# 添加新依赖
poetry add matplotlib

# 添加开发依赖
poetry add --dev jupyter

# 更新锁定文件
poetry lock

2.5 项目初始化：标准目录结构

金融特征回放评审项目建议采用以下目录结构，兼顾可读性与可扩展性：

feature-replay-toolkit/
├── .venv/                  # 虚拟环境（不提交Git）
├── src/
│   └── feature_replay/     # 主包
│       ├── __init__.py
│       ├── core/           # 核心回放引擎
│       ├── features/       # 特征定义与计算
│       ├── backtest/       # 回放执行逻辑
│       └── utils/          # 工具函数
├── tests/                  # 单元测试
│   ├── test_core/
│   └── test_features/
├── notebooks/              # Jupyter 探索笔记本
├── data/                   # 样本数据（小文件）
├── docs/                   # 文档
├── pyproject.toml          # Poetry 配置
├── poetry.lock             # 依赖锁定
├── .gitignore
└── README.md

2.6 环境搭建全流程SVG

下图展示从创建虚拟环境到依赖锁定、项目初始化的完整链路：

2.7 环境验证清单

完成搭建后，执行以下验证确保环境正确：

# 1. 确认虚拟环境激活
(.venv) $ which python
/Users/quant/feature-replay-toolkit/.venv/bin/python

# 2. 确认核心库可导入
(.venv) $ python -c "import pandas; print(pandas.__version__)"
1.5.3

# 3. 确认回放框架可用
(.venv) $ python -c "import backtrader; print(backtrader.__version__)"
1.9.78.123

# 4. 确认测试框架正常
(.venv) $ pytest --version
pytest 7.4.0