开发与贡献

相关源文件

• .devcontainer/Dockerfile
• .devcontainer/devcontainer.json
• .github/workflows/ci.yml
• .github/workflows/create-releases.yml
• .github/workflows/publish-pypi.yml
• .github/workflows/release-doctor.yml
• .release-please-manifest.json
• CHANGELOG.md
• bin/check-release-environment
• bin/publish-pypi
• pyproject.toml
• release-please-config.json
• scripts/utils/upload-artifact.sh
• src/openai/_version.py

本文档涵盖了 OpenAI Python 库的开发环境设置、构建系统、测试框架、CI/CD 管道以及贡献指南。它为希望为代码库贡献或了解项目开发基础设施的开发人员提供了技术细节。

有关客户端架构和 API 使用的信息，请参阅核心客户端类。有关类型系统和代码生成的详细信息，请参阅数据类型和模型。

开发环境设置

OpenAI Python 库使用以 Rye 包管理器为中心的现代 Python 开发工具。该项目支持 Python 3.8+，并遵循严格的类型检查和代码质量标准。

使用 Rye 进行包管理

该项目使用 Rye 作为主要的包管理器和开发工具协调器。Rye 负责处理依赖管理、虚拟环境创建和脚本执行。

开发环境配置

开发依赖项在 [tool.rye] 部分中指定，包括

工具	目的	版本
pyright	类型检查	1.1.399（固定版本）
mypy	类型检查	最新版
ruff	Linting 和格式化	最新版
pytest	测试框架	最新版
pytest-asyncio	异步测试支持	最新版
respx	HTTP 模拟	最新版
nox	测试自动化	最新版

来源： pyproject.toml50-71

DevContainer 支持

该项目包含 DevContainer 配置，用于在不同机器和平台之间提供一致的开发环境。

DevContainer 自动安装 Rye 0.44.0，并配置带有正确路径和 VS Code 设置的 Python 环境。

来源： .devcontainer/Dockerfile1-10 .devcontainer/devcontainer.json1-43

构建系统架构

该项目使用 Hatchling 作为构建后端，并针对包结构和分发进行了特定配置。

项目配置

构建系统通过 pyproject.toml 配置，包含以下关键组件

核心依赖项

该项目的运行时依赖项最少，主要侧重于 HTTP 通信和数据验证

依赖项	版本约束	目的
httpx	>=0.23.0, <1	HTTP 客户端基础
pydantic	>=1.9.0, <3	数据验证和解析
typing-extensions	>=4.11, <5	类型系统增强
anyio	>=3.5.0, <5	异步 I/O 抽象
distro	>=1.7.0, <2	平台检测
sniffio	最新版	异步库检测
tqdm	> 4	进度条
jiter	>=0.4.0, <1	快速 JSON 迭代

来源： pyproject.toml10-19 pyproject.toml102-127

可选依赖项

该项目为特定功能定义了可选的依赖组

来源： pyproject.toml45-48

代码质量与测试

该项目通过自动化 Linting、类型检查和全面测试来强制执行严格的代码质量标准。

代码质量工具配置

用于开发的 Rye 脚本

该项目定义了多个 Rye 脚本用于常见的开发任务

脚本	命令链	目的
format	format:ruff、format:docs、fix:ruff、format:ruff	代码格式化
lint	check:ruff、typecheck、check:importable	代码质量检查
typecheck	typecheck:pyright、typecheck:mypy	类型验证

来源： pyproject.toml73-100 pyproject.toml140-148 pyproject.toml150-172

测试配置

测试框架使用 pytest，并针对异步测试和严格错误处理进行了特定配置

• 测试发现：测试文件位于 tests/ 目录中
• 异步支持：具有会话范围事件循环的自动 asyncio 模式
• 错误处理：所有警告均被视为错误 (filterwarnings = ["error"])
• 会话夹具：asyncio_default_fixture_loop_scope = "session"

来源： pyproject.toml140-148

CI/CD 流水线

持续集成和部署管道通过 GitHub Actions 实现，其中包含处理开发生命周期不同方面的多个工作流。

主要 CI 工作流

CI 作业配置

每个 CI 任务的运行超时时间为 10 分钟，并对主仓库使用 depot runners。

• 仓库检测：github.repository == 'stainless-sdks/openai-python'
• Runner 选择：主仓库使用 depot-ubuntu-24.04，分支仓库使用 ubuntu-latest
• Rye 版本：为保持一致性，固定为 0.44.0

来源： .github/workflows/ci.yml1-106

发布管道

发布过程使用 release-please 完全自动化，并包含多个工作流

发布配置

发布过程使用 release-please，并采用以下配置

• 版本控制策略：主版本前的小版本预发布
• 更新日志部分：特性、错误修复、性能、杂项、文档
• 额外文件：src/openai/_version.py 用于版本同步
• 标签格式：包含 v 前缀 (include-v-in-tag: true)

来源： .github/workflows/create-releases.yml1-40 release-please-config.json1-66 .release-please-manifest.json1-3

环境验证

发布医生工作流验证发布环境

来源： .github/workflows/release-doctor.yml1-24 bin/check-release-environment1-26

版本管理

该项目使用双源版本管理系统，pyproject.toml 和 src/openai/_version.py 之间自动同步。

版本同步

_version.py 中的版本字符串包含一个用于 release-please 跟踪的特殊注释

来源： pyproject.toml3 src/openai/_version.py4 .release-please-manifest.json2

贡献工作流程

开发工作流强调通过标准化脚本和工具进行代码质量、测试和自动化验证。

开发脚本

该项目提供了多个用于常见开发任务的实用脚本

发布流程

PyPI 发布流程通过 bin/publish-pypi 脚本进行了简化

1. 清洁构建：rye build --clean
2. 分发包创建：创建 wheel 和源分发包
3. 上传：rye publish --yes --token=$PYPI_TOKEN

来源： bin/publish-pypi1-7

产物管理

对于开发构建，该项目支持将工件上传到 Stainless 存储。

来源： scripts/utils/upload-artifact.sh1-26