py-modernize

Python 代码库现代化

遵循 Engineering Charter 原则，为 Python 项目升级现代工具、语法和模式。

目标

1. 从 pip 迁移到 uv，以加快依赖管理
2. 将 Python 语法升级到 3.13+ 的现代模式
3. 替换已弃用的 API 和模式
4. 将工具更新到当前最佳实践
5. 确保 pyproject.toml 是唯一的配置来源

必需工具

全局安装 uv（通过包管理器）：sudo zypper install uv 或 pip install --user uv 添加到 [dependency-groups] dev："pyupgrade"、"ruff"

• uv：快速的软件包安装程序（pip 的替代品）
• pyupgrade：自动将语法升级到更新的 Python 版本
• ruff：支持 UP 规则的现代代码检查工具

权限：先运行 py-quality-setup，以配置 .claude/settings.local.json 并授予所有必需的工具权限。

包管理器：pip → uv

为什么选择 uv？

• 比 pip 快 10-100 倍
• 更好的依赖解析
• 更完善的缓存
• 与 pip 兼容（可直接替换）
• 由 Astral（与 ruff 同一团队）积极开发

迁移工作流

# 1. Verify current setup
cat requirements.txt setup.py setup.cfg pyproject.toml

# 2. Install uv globally (not recommended, ask user to install via package manager)
# curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Replace venv creation
# OLD: python -m venv venv
uv venv

# 4. Replace pip install
# OLD: pip install -e ".[dev]"
uv pip install -e ".[dev]"

# 5. Replace pip install from requirements.txt
# OLD: pip install -r requirements.txt
uv pip install -r requirements.txt

# 6. Compile requirements (faster dependency resolution)
uv pip compile pyproject.toml -o requirements.txt

# 7. Sync environment (install exactly what's in requirements.txt)
uv pip sync requirements.txt

更新 CI/CD

# .github/workflows/test.yml

# BEFORE
- name: Install dependencies
  run: |
    python -m venv venv
    source venv/bin/activate
    pip install -e ".[dev]"

# AFTER
- name: Install uv
  uses: astral-sh/setup-uv@v1

- name: Install dependencies
  run: |
    uv venv
    source .venv/bin/activate
    uv pip install -e ".[dev]"

更新文档

更新 README.md：

## Development Setup

python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"


## Development Setup

# Install uv if not already installed (via package manager preferred)
# sudo zypper install uv  # openSUSE
# or: pip install --user uv

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Python 语法现代化

目标版本

在 pyproject.toml 中设置目标版本：

[project]
requires-python = ">=3.13"

[tool.pyupgrade]
target-version = "py313"

[tool.ruff]
target-version = "py313"

[tool.ruff.lint]
select = ["UP"]  # Enable pyupgrade rules

运行语法升级

# Using pyupgrade directly (modifies files in-place)
pyupgrade --py313-plus **/*.py

# Using ruff (shows what would change)
ruff check . --select UP
ruff check . --select UP --fix  # Apply fixes

# Verify changes
git diff

# Run tests to ensure functionality preserved
pytest

常见现代化改进

运行 pyupgrade --py313-plus . 或 ruff check . --select UP 以自动升级：

• 类型提示：List[str] → list[str]、Optional[int] → int | None
• 移除 __future__：导入（3.11+ 内置）
• 字符串格式化：% 或 .format() → f 字符串
• 类型联合：Union[int, str] → int | str
• 海象运算符：if x := func():（减少临时变量）
• match 语句：替换冗长的 if/elif 链（3.10+）
• Pathlib：用 Path 对象替换 os.path
• 数据类：用 @dataclass 替换手动编写的 __init__

配置现代化

将 setup.py/setup.cfg/requirements.txt 合并到 pyproject.toml。

注意：完整的 pyproject.toml 配置（包括 ruff、mypy 和 basedpyright）请参阅 py-quality-setup。

基本结构：

[project]
name = "myproject"
version = "1.0.0"
requires-python = ">=3.13"
dependencies = ["requests", "pydantic"]

[build-system]
requires = ["setuptools>=68.0"]
build-backend = "setuptools.build_meta"

之后：rm setup.py setup.cfg; uv pip install -e .; pytest

已弃用模式更新

需要修复的常见弃用项：

• collections.Iterable → collections.abc.Iterable（3.3 起弃用，3.10 移除）
• datetime.utcnow() → datetime.now(UTC)（3.12 起弃用）
• datetime.utcfromtimestamp() → datetime.fromtimestamp(ts, UTC)（3.12 起弃用）
• imp 模块 → importlib（3.12 移除）
• typing.List、typing.Dict → list、dict（3.9+）
• typing.Optional[X] → X | None（3.10+）
• typing.Union[X, Y] → X | Y（3.10+）

搜索已弃用模式：

# Find deprecated datetime usage
grep -rn "datetime.utcnow\|datetime.utcfromtimestamp" --include="*.py" .

# Find old typing imports
grep -rn "from typing import.*List\|from typing import.*Dict\|from typing import.*Optional" --include="*.py" .

# Find old collections imports
grep -rn "from collections import.*Callable\|from collections import.*Iterable" --include="*.py" .

验证清单

• 使用 uv 创建虚拟环境并安装软件包
• pyproject.toml 是唯一的配置来源（没有 setup.py/setup.cfg）
• 在 pyproject.toml 中设置了 requires-python = ">=3.13"
• ruff check . --select UP 未报告问题（或仅有已接受的例外）
• 未使用已弃用的 datetime.utcnow() 或 datetime.utcfromtimestamp()
• 没有旧式类型导入（List、Dict、Optional、Union）
• CI/CD 已更新为使用 uv
• README.md 已更新为基于 uv 的设置说明
• 现代化后所有测试均通过

示例

示例：将 pip 迁移到 uv

1. Check current setup:
   - ls -la | grep -E "setup.py|requirements.txt|pyproject.toml"
   - cat pyproject.toml

2. Install uv (if not already installed):
   - Via package manager: sudo zypper install uv  # openSUSE
   - Or as user package: pip install --user uv

3. Test uv with current project:
   - uv venv
   - source .venv/bin/activate
   - uv pip install -e ".[dev]"
   - pytest (verify all tests pass)

4. Update CI/CD:
   - Edit .github/workflows/test.yml
   - Replace pip commands with uv

5. Update README:
   - Replace pip instructions with uv

6. Commit: "Migrate from pip to uv for dependency management"

示例：将语法现代化到 Python 3.13

1. Update pyproject.toml:
   [project]
   requires-python = ">=3.13"

2. Run pyupgrade:
   pyupgrade --py313-plus **/*.py

3. Review changes:
   git diff
   # Check: List[X] → list[X], Union[X, Y] → X | Y, etc.

4. Run ruff for additional upgrades:
   ruff check . --select UP --fix

5. Verify type checking still works:
   mypy .
   basedpyright .

6. Run tests:
   pytest

7. Commit: "Modernize syntax to Python 3.13+"

示例：完整现代化

1. Migrate to uv (see Example 1)

2. Consolidate configuration:
   - Read setup.py and setup.cfg
   - Migrate all config to pyproject.toml
   - Remove setup.py and setup.cfg
   - Verify: uv pip install -e ".[dev]"

3. Modernize syntax (see Example 2)

4. Update deprecated APIs:
   - grep -r "from collections import.*Iterable" .
   - Replace with collections.abc
   - grep -r "datetime.utcnow" .
   - Replace with datetime.now(UTC)

5. Final validation:
   - ruff check . --select UP (clean)
   - pytest (all pass)
   - mypy . && basedpyright . (no errors)

6. Update documentation:
   - README reflects uv usage
   - CONTRIBUTING.md updated

7. Commit: "Modernize codebase: uv, Python 3.13 syntax, pyproject.toml"

相关技能

• 前置条件：py-quality-setup（工具配置）、py-test-quality（语法更改前的安全保障）
• 强制执行：py-git-hooks（通过 ruff UP 规则强制使用现代语法）
• 另请参阅：py-complexity（现代化通常有助于简化代码）