Codex CLI Python 教程（2026）— AI 驱动的 Python 开发工作流

Python 是最适合 AI 编程助手的语言之一：生态成熟、测试工具完善、类型系统明确。Codex CLI 天然理解 Python，配合正确的配置，可以大幅提升 Python 开发效率——从自动生成 pytest 测试，到修复 mypy 类型错误，再到生成完整的 Django REST API。

本教程覆盖从项目初始化到 CI/CD 自动化的完整工作流，包含大量可直接复用的提示词模板，适用于 Django、FastAPI 等主流 Python 框架。

1. 项目初始化与 AGENTS.md 配置

为 Python 项目配置 AGENTS.md 是最重要的第一步。一份详细的 AGENTS.md 文件告诉 Codex 你的项目结构、技术栈、代码规范和安全边界，从而生成更准确、更符合项目风格的代码。

以下是一个适合 FastAPI + Poetry 项目的完整 AGENTS.md 示例：

# Python Project — AGENTS.md

## 项目信息
- Python 版本：3.12
- 依赖管理：Poetry (pyproject.toml)
- 测试框架：pytest + pytest-cov
- 代码风格：Black + isort + ruff
- 类型检查：mypy (strict 模式)
- Web 框架：FastAPI 0.111

## 代码规范
- 所有函数和方法必须有类型注解（包括返回类型）
- Docstring 使用 Google 风格
- 单个函数不超过 50 行；超过时拆分
- 使用 Pydantic v2 进行数据验证

## 允许的命令
- pytest, pytest-cov
- mypy, ruff, black, isort
- poetry add/remove/install
- alembic upgrade/downgrade

## 禁止的操作
- 不得删除 migrations/（只能新增）
- 不得修改 .env（敏感信息由 pydantic-settings 管理）
- 不得降低测试覆盖率（当前 > 85%）

AGENTS.md 对 Python 项目的核心价值

• 版本锁定：明确 Python 版本，避免生成过时或不兼容的语法
• 依赖感知：Codex 知道你用 Poetry 还是 pip，生成正确的安装命令
• 风格一致：配置 Black/isort/ruff 后，生成的代码天然符合风格要求
• 安全边界：禁止修改迁移文件或 .env，防止 AI 操作越界
• 测试门槛：设定覆盖率下限，确保 Codex 生成的代码有充分测试

2. 自动生成 pytest 测试

测试生成是 Codex CLI 在 Python 生态中最强大的应用场景之一。Codex 可以分析你的业务代码，理解函数签名和业务逻辑，自动生成覆盖正常路径、边界值和异常情况的完整测试套件。

示例 1：生成单元测试

$ codex "为 app/services/user_service.py 中的 UserService 类生成完整的 pytest 测试文件。
要求：
- 使用 pytest fixtures 和 factory_boy 生成测试数据
- 用 unittest.mock.patch 隔离数据库调用
- 每个方法至少 3 个测试：正常路径、边界值、异常情况
- 测试文件保存到 tests/services/test_user_service.py"

示例 2：提升测试覆盖率

$ codex "运行 pytest --cov=app --cov-report=term-missing，找出覆盖率低于 80% 的模块，
补充缺失的测试用例，优先覆盖核心业务逻辑路径"

示例 3：生成参数化测试

$ codex "为 app/utils/validators.py 中的 validate_email 函数生成参数化测试
（@pytest.mark.parametrize），覆盖有效邮件、无效格式、空字符串、
Unicode 字符等边界情况"

示例 4：生成 FastAPI 异步集成测试

$ codex "使用 httpx.AsyncClient 为 /api/v1/users 路由生成异步集成测试，
覆盖 GET（分页）、POST（创建，含验证错误）、PUT（更新）、DELETE（软删除）"

示例 5：Mock 外部 API 调用

$ codex "为调用 Stripe API 的 payment_service.py 编写测试，
用 pytest-mock 的 mocker.patch 模拟 stripe.PaymentIntent.create，
测试成功支付、余额不足、网络超时三种情况"

生成的测试文件结构示例（Codex 输出风格）：

import pytest
from unittest.mock import patch, MagicMock
from app.services.user_service import UserService
from tests.factories import UserFactory

class TestUserService:
    """Tests for UserService — auto-generated by Codex CLI."""

    @pytest.fixture
    def service(self, db_session):
        return UserService(db=db_session)

    def test_get_user_success(self, service):
        user = UserFactory.create()
        result = service.get_user(user.id)
        assert result.id == user.id

    def test_get_user_not_found(self, service):
        with pytest.raises(UserNotFoundError):
            service.get_user(99999)

    @pytest.mark.parametrize("invalid_id", [0, -1, None])
    def test_get_user_invalid_id(self, service, invalid_id):
        with pytest.raises(ValueError):
            service.get_user(invalid_id)

3. 类型检查与 mypy 集成

Python 的类型系统在 3.10+ 版本后愈发完善。Codex CLI 可以帮助你快速修复 mypy 错误、为历史代码添加类型注解、生成符合规范的 Pydantic 模型。

示例 1：批量修复 mypy 错误

$ codex "运行 mypy app/ --strict，找到所有类型错误并修复：
- 不得使用 Any 类型绕过检查
- Optional 字段必须正确处理 None
- 泛型类型需要完整指定（如 List[str] 而非 List）"

示例 2：为历史代码添加类型注解

$ codex "为 app/legacy/data_processor.py 添加完整的 Python 3.12 类型注解：
- 分析函数的实际使用方式推断类型
- 使用 TypeVar 处理泛型函数
- 复杂数据结构使用 TypedDict 或 dataclass"

示例 3：从数据库 Schema 生成 Pydantic 模型

$ codex "根据 PostgreSQL 数据库 schema（见 schema.sql）生成对应的 Pydantic v2 模型，包含：
- 数据库模型（SQLModel）
- API 请求/响应模型（BaseModel，分别用于创建、更新、读取）
- 字段验证器（validator/field_validator）"

Pydantic v2 模型示例（Codex 生成风格）：

from pydantic import BaseModel, EmailStr, field_validator
from typing import Optional
from datetime import datetime

class UserCreate(BaseModel):
    """Request model for user creation."""
    email: EmailStr
    username: str
    password: str

    @field_validator("password")
    @classmethod
    def validate_password(cls, v: str) -> str:
        if len(v) < 8:
            raise ValueError("Password must be at least 8 characters")
        return v

class UserRead(BaseModel):
    """Response model for user data."""
    id: int
    email: EmailStr
    username: str
    created_at: datetime

    model_config = {"from_attributes": True}

4. 代码风格自动化（Black / Ruff / isort）

Codex CLI 可以在修改代码的同时保持风格一致性，或专门用于批量整理历史代码库的风格问题。

示例 1：一键格式化与 Lint 修复

$ codex exec --approval-mode full-auto "运行以下命令修复格式问题，确保 CI 通过：
1. isort app/ tests/ --profile black
2. black app/ tests/
3. ruff check app/ tests/ --fix
然后运行 pytest 验证没有引入 Bug"

示例 2：审查历史代码库风格问题

$ codex "审查 legacy/ 目录下所有 Python 文件的代码风格问题：
1. 找出不符合 PEP 8 的命名（驼峰命名的变量/函数）
2. 找出过长的函数（> 50 行）
3. 找出缺少 docstring 的公开函数
生成一份 Markdown 格式的改进清单，按优先级排序"

5. Django 项目集成

Django 是 Python 生态中最成熟的 Web 框架。Codex CLI 完全理解 Django 的 MVT 架构、ORM 语义和约定优于配置的设计哲学。

示例 1：生成 Django Model

$ codex "为博客系统创建 Django Model：
- Post（标题、内容、作者、创建时间、状态、标签多对多）
- Comment（内容、作者、帖子、父评论可空、创建时间）
- Tag（名称、slug、使用次数）
包含 Meta 类、__str__ 方法、get_absolute_url、自定义 Manager"

示例 2：生成 DRF Serializer + ViewSet

$ codex "为 BlogPost 模型创建完整的 DRF API：
- PostSerializer（嵌套 author 和 tags）
- PostViewSet（带自定义权限：作者可以编辑、所有人可以读取）
- URL 路由注册到 api/v1/posts/"

示例 3：生成 Django Migration

$ codex "Post 模型需要新增 view_count（整数，默认 0）和 featured_image
（ImageField，可为空）字段，生成对应的 Migration 文件"

示例 4：生成管理命令

$ codex "编写 Django 管理命令 management/commands/send_digest.py：
读取过去 24 小时的新帖子，发送摘要邮件给订阅用户，支持 --dry-run 参数"

示例 5：ORM 性能优化

$ codex "分析 views.py 中的 UserListView，发现以下查询问题并修复：
- N+1 查询（用 select_related/prefetch_related 解决）
- 缺少分页
- 缺少缓存（热点数据用 Django cache framework）"

Django Model 生成示例（Codex 输出风格）：

from django.db import models
from django.contrib.auth import get_user_model
from django.urls import reverse

User = get_user_model()

class PostManager(models.Manager):
    def published(self):
        return self.filter(status="published")

class Post(models.Model):
    class Status(models.TextChoices):
        DRAFT = "draft", "草稿"
        PUBLISHED = "published", "已发布"

    title = models.CharField(max_length=255)
    content = models.TextField()
    author = models.ForeignKey(User, on_delete=models.CASCADE, related_name="posts")
    tags = models.ManyToManyField("Tag", blank=True)
    status = models.CharField(max_length=20, choices=Status.choices, default=Status.DRAFT)
    created_at = models.DateTimeField(auto_now_add=True)

    objects = PostManager()

    class Meta:
        ordering = ["-created_at"]
        verbose_name = "文章"

    def __str__(self) -> str:
        return self.title

    def get_absolute_url(self) -> str:
        return reverse("posts:detail", kwargs={"pk": self.pk})

6. FastAPI / 现代 Python Web 框架

FastAPI 凭借原生异步支持和 Pydantic 集成，已成为现代 Python API 开发的首选框架。Codex CLI 完全理解 FastAPI 的依赖注入系统、路由装饰器和异步生命周期。

示例 1：生成用户认证路由

$ codex "为用户认证系统创建 FastAPI 路由（app/api/v1/auth.py）：
- POST /register（邮件+密码，发送验证邮件）
- POST /login（返回 JWT access/refresh token）
- POST /refresh（用 refresh token 换新 access token）
- POST /logout（黑名单 refresh token）
使用 Pydantic v2、python-jose、passlib[bcrypt]"

示例 2：依赖注入系统

$ codex "创建 FastAPI 依赖项：
- get_current_user：验证 JWT，返回用户对象或抛出 401
- get_db：SQLAlchemy async session（带自动 commit/rollback）
- require_permission(perm: str)：RBAC 权限检查"

示例 3：Celery 异步任务系统

$ codex "用 Celery + Redis 实现异步任务系统：
- 发送邮件任务（带重试和指数退避）
- 图片处理任务（Pillow 压缩和 WebP 转换）
- Celery Beat 定时任务（每天凌晨 2 点清理过期 token）
包含 Dockerfile 中的 worker 启动配置"

FastAPI 依赖注入示例（Codex 生成风格）：

from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from sqlalchemy.ext.asyncio import AsyncSession
from typing import AsyncGenerator

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

async def get_db() -> AsyncGenerator[AsyncSession, None]:
    """Async database session dependency."""
    async with AsyncSessionLocal() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise

async def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: AsyncSession = Depends(get_db),
) -> User:
    """Validate JWT and return current user."""
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
    )
    payload = decode_jwt(token)
    if payload is None:
        raise credentials_exception
    user = await db.get(User, payload["sub"])
    if user is None:
        raise credentials_exception
    return user

7. Python CI/CD 自动化（GitHub Actions）

将 Codex CLI 集成到 GitHub Actions 流水线，可以在 CI 失败时自动分析问题、在代码审查阶段自动生成改进建议。

# .github/workflows/python-ci.yml
name: Python CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12"]

    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install Poetry
        run: pip install poetry

      - name: Install dependencies
        run: poetry install --with dev

      - name: Lint (ruff + mypy)
        run: |
          poetry run ruff check app/
          poetry run mypy app/ --strict

      - name: Test with coverage
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          DATABASE_URL: postgresql://postgres:postgres@localhost/testdb
        run: |
          poetry run pytest --cov=app --cov-report=xml --cov-fail-under=80

      - name: AI Test Generation (on failure)
        if: failure()
        run: |
          pip install @openai/codex
          codex exec "Analyze failing tests and suggest fixes without modifying production code"

8. 常用 Python 提示词速查

以下是 Python 开发中高频使用的 Codex 提示词模板，可直接复制并按需修改：

9. 常见问题 FAQ

Codex CLI 支持 Python 项目吗？

完全支持。Codex CLI 是语言无关的工具，天然支持 Python 项目。配合合理的 AGENTS.md 配置，可以让 Codex 了解你的 Python 版本、依赖管理工具（pip/poetry/conda）和测试框架，实现更准确的代码生成。

如何让 Codex CLI 生成符合 PEP 8 的 Python 代码？

在 AGENTS.md 中指定代码风格要求：「所有 Python 代码遵循 PEP 8，使用 Black 格式化，类型注解遵循 mypy strict 模式」。或在提示词中明确要求：「生成的函数需要添加完整的 type hint 和 docstring（Google 风格）」。也可以直接让 Codex 在生成代码后自动运行 black 和 ruff --fix 进行格式化。

Codex CLI 可以在 Python 虚拟环境中使用吗？

可以。在激活虚拟环境（venv/conda/poetry shell）后运行 codex 即可。Codex 会继承当前 shell 的环境，可以执行 pip install、pytest、mypy 等命令。建议在 AGENTS.md 的 allowed_commands 中列出允许的命令，避免 Codex 意外安装不受信任的包。

Codex CLI 可以帮助 Django 项目生成代码吗？

可以。Codex 可以生成 Django 的 Model、View、Serializer、URL 配置、Migration、管理命令等。在 AGENTS.md 中说明 Django 版本和项目结构（如 apps 目录布局），Codex 会遵循 Django 的约定和最佳实践，生成符合 Django 风格的代码。