📚 课程目录第2章环境准备

2. 环境准备：Python环境、Ent SDK安装、虚拟环境配置与依赖管理

在开始编写对象存储编排逻辑之前，必须搭建一个干净、可复现的 Python 开发环境。本章将指导你完成 Python 解释器安装、虚拟环境隔离、Ent SDK 集成以及依赖锁定，确保后续所有章节的代码都能在一致的环境中运行。

2.1 环境全景概览

下图展示了本地开发环境与 Ent 对象存储服务之间的核心交互层次。理解这一分层有助于后续排查 SDK 版本冲突或网络连通性问题。

版本要求：本课程所有代码均基于 Python 3.10+ 与 Ent SDK 2.x 系列。低于 3.10 的 Python 版本可能导致类型注解或异步语法不兼容。

2.2 Python 环境安装与验证

推荐使用 pyenv（macOS/Linux）或 Python 官方安装包（Windows）管理多版本。以下为安装后的验证步骤：

检查 Python 版本：打开终端，执行 python --version，确认输出为 Python 3.10.x 或更高。
检查 pip 版本：执行 pip --version，确保 pip ≥ 21.0，否则使用 pip install --upgrade pip 升级。
验证 SSL/TLS 支持：执行 python -c "import ssl; print(ssl.OPENSSL_VERSION)"，确认输出不为空。Ent SDK 依赖 HTTPS 连接。

常见陷阱：macOS 自带 Python 2 或 Python 3.8 低版本，请勿直接使用系统 Python。务必通过 pyenv 或 Homebrew 安装独立版本，避免污染系统环境。

2.3 虚拟环境配置

虚拟环境隔离项目依赖，防止不同项目间的包版本冲突。本课程统一使用 Python 内置的 venv 模块，无需额外安装。

步骤	命令	说明
1. 创建虚拟环境	`python -m venv .venv`	在当前目录生成 `.venv` 文件夹
2. 激活环境（macOS/Linux）	`source .venv/bin/activate`	提示符前出现 `(.venv)` 前缀
3. 激活环境（Windows PowerShell）	`.venv\Scripts\Activate.ps1`	如遇执行策略限制，先执行 `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`
4. 验证激活	`which python`（macOS/Linux）或 `Get-Command python`（Windows）	路径应指向 `.venv/bin/python` 或 `.venv\Scripts\python.exe`

  最佳实践：将 .venv/ 加入 .gitignore 文件，避免虚拟环境被提交到版本控制。依赖清单由 requirements.txt 或 pyproject.toml 管理。

2.4 Ent SDK 安装

激活虚拟环境后，使用 pip 安装 Ent 对象存储 SDK：

# 安装最新稳定版
pip install ent-sdk

# 安装指定版本（推荐锁定版本）
pip install ent-sdk==2.3.1

# 验证安装
python -c "import ent; print(ent.__version__)"

SDK 安装完成后，建议执行一次快速连通性测试，确保 SDK 能正确加载且无底层依赖缺失：

python -c "
from ent import Client
# 仅验证导入与类结构，不发起真实网络请求
print('Ent SDK 加载成功')
print('Client 类:', Client)
"

2.5 依赖管理与锁定

为保障团队协作与 CI/CD 环境的一致性，必须对项目依赖进行精确锁定。推荐使用 pip freeze 生成 requirements.txt：

# 生成当前环境的完整依赖清单
pip freeze > requirements.txt

# 在另一台机器上重建完全相同的环境
pip install -r requirements.txt

以下为典型的 requirements.txt 内容示例：

ent-sdk==2.3.1
httpx==0.27.0
pydantic==2.5.0
python-dotenv==1.0.0

进阶建议：对于大型项目，可改用 pipenv 或 poetry 管理依赖，它们自动生成锁定文件（Pipfile.lock / poetry.lock），并提供更严格的哈希校验。

2.6 环境验证清单

完成上述步骤后，执行以下完整验证脚本，确认所有组件就绪：

import sys
import ssl
import ent

def check_environment():
    print(f"Python 版本: {sys.version}")
    print(f"SSL 版本: {ssl.OPENSSL_VERSION}")
    print(f"Ent SDK 版本: {ent.__version__}")
    
    # 检查关键依赖
    try:
        import httpx
        print(f"httpx 版本: {httpx.__version__}")
    except ImportError:
        print("警告: httpx 未安装")
    
    print("环境验证通过！")

if __name__ == "__main__":
    check_environment()

预期输出应包含 Python 3.10+、SSL 版本号、Ent SDK 2.x 以及 httpx 版本号。任何 ImportError 或版本号缺失都表明环境未正确配置。

网络代理注意事项：如果所在网络需要 HTTP 代理，请在终端设置环境变量 HTTP_PROXY 和 HTTPS_PROXY，否则 SDK 连接 Ent 服务端时会超时。示例：export HTTPS_PROXY=http://proxy.company.com:8080。

2.7 本章小结

至此，你已经完成了以下环境准备工作：

安装并验证了 Python 3.10+ 解释器
使用 venv 创建了隔离的虚拟环境
通过 pip 安装了 Ent SDK 并验证了导入
生成了 requirements.txt 依赖锁定文件
运行了完整的环境验证脚本