py-modernize

Python コードベースのモダナイゼーション

エンジニアリング憲章の原則に従い、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：os.path を Path オブジェクトに置き換えます
• データクラス：手書きの __init__ を @dataclass に置き換えます

設定のモダナイゼーション

setup.py/setup.cfg/requirements.txt の設定を pyproject.toml に統合します。

注：ruff、mypy、basedpyright を含む pyproject.toml の完全な設定については、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（モダナイゼーションによって簡素化できることがよくあります）