migrate-to-uv

uv ビルドシステムへの移行

Keboola コンポーネント（Docker ベース、ECR にデプロイ）を、requirements.txt + pip から pyproject.toml + uv に移行し、ruff によるリンティングを導入します。

利用可能なツールを使って、すべての手順を自分で実行してください。他のエージェント（component-builder、develop-component など）への委任や起動はしないでください。ただし、Phase 6 の component-developer:component-defaults は例外です。

以下の手順をすべて完了してください。どの手順も省略しないでください。ファイルが存在しない場合は、何もせず次に進んでください。

---

ステップ 0：現在の状態を確認する

cat requirements.txt
grep "FROM python:" Dockerfile
cat .github/workflows/push.yml

---

コミット 1：pyproject.toml に移行 📦

pyproject.toml を作成する

メタデータと ruff の設定を含む最小限の pyproject.toml を作成します。ただし、依存関係はまだ追加しません。依存関係は次に uv add で追加します。

• 常に requires-python = "~=3.13.0" と target-version = "py313" を使用してください
• dependencies = [] はこの時点では空のままにしてください

次に、uv を使って requirements.txt から依存関係を追加します。

# Add all main deps at once
uv add -r requirements.txt

# Move test-only deps to the dev group (common ones: pytest, mock, freezegun, responses)
# For each test dep found in requirements.txt:
uv remove <test-dep>
uv add --group dev <test-dep>

uv add は固定バージョンを >= の範囲指定に自動変換し、uv.lock をその場で更新します。手動で変換する必要はありません。

ファイルを削除する

rm -f requirements.txt
rm -f .flake8 flake8.cfg
rm -f scripts/build_n_run.ps1 scripts/run.bat scripts/run_kbc_tests.ps1
rm -f scripts/update_dev_portal_properties.sh
rm -rf docs/imgs/
rm -f component_config/configuration_description.md component_config/stack_parameters.json

（rm -f は、ファイルが存在しない場合は何もせず、エラーも発生せず処理も停止しません。）

component_config/ の URL を入力する（ファイルが現在空の場合）

component_config/documentationUrl.md  → https://github.com/keboola/REPO/blob/master/README.md
component_config/licenseUrl.md        → https://github.com/keboola/REPO/blob/master/LICENSE.md
component_config/sourceCodeUrl.md     → https://github.com/keboola/REPO

.gitignore を更新する

以下の行がなければ追加してください。

*.egg-info/
.venv/
.DS_Store
/data

単独の data/ を /data に置き換えます。重複する .vscode/ のエントリを削除します。

コミットする

git add -u                                          # stages all deletions
git add pyproject.toml uv.lock .gitignore component_config/
git commit -m "migrate to pyproject.toml 📦"

---

コミット 2：uv 💜

Dockerfile を更新する

マルチステージビルドのパターンを使用してください。 base ステージは test と production の両方で共有します。これにより、本番イメージを軽量に保ちます（開発用依存関係やテストファイルは含めません）。

FROM python:3.13-slim AS base
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# apt-get installs MUST come before uv sync
# RUN apt-get update && apt-get install -y <packages>  ← keep if already present

WORKDIR /code/
COPY pyproject.toml uv.lock ./
ENV UV_PROJECT_ENVIRONMENT="/usr/local/"
RUN uv sync --no-dev --frozen

COPY src/ src/
COPY scripts/ scripts/
COPY deploy.sh .

FROM base AS test
RUN uv sync --all-groups --frozen
COPY tests/ tests/
RUN uv run ruff check src/ tests/
CMD ["uv", "run", "pytest", "tests/", "-v"]

FROM base AS production
CMD ["python", "-u", "/code/src/component.py"]

注意事項：

• base は本番用依存関係のみをインストールし（--no-dev）、test ではその上に開発用依存関係を追加します
• Ruff チェックは test ステージのイメージビルド時に実行し、問題があればすぐに失敗させます
• ENV KEY="value" 構文を使用してください（従来の ENV KEY value ではありません）
• pip install は一切使用しないでください
• apt-get のブロックはすべて、RUN uv sync より前に配置してください

scripts/build_n_test.sh を更新する

#!/bin/sh
set -e

ruff check
python -m pytest tests/ --tb=short -q

tests/__init__.py を更新する

古い os.path のパターンを置き換えます。

import sys
from pathlib import Path
sys.path.append(str(Path(__file__).resolve().parent.parent / "src"))

.github/workflows/push.yml を更新する

標準の push.yml は、マルチステージ Dockerfile に対応するマルチジョブパイプラインを使用します。個々のステップを修正するのではなく、ファイル全体を標準テンプレート（Phase 6 / component-defaults から）に置き換え、このコンポーネントの env: ブロックだけを更新してください。

env:
  KBC_DEVELOPERPORTAL_APP: "vendor.component-id"   # full component ID from Developer Portal
  KBC_DEVELOPERPORTAL_VENDOR: "vendor"              # your vendor name
  DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }}
  KBC_DEVELOPERPORTAL_USERNAME: ${{ vars.KBC_DEVELOPERPORTAL_USERNAME }}
  DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
  KBC_DEVELOPERPORTAL_PASSWORD: ${{ secrets.KBC_DEVELOPERPORTAL_PASSWORD }}
  KBC_TEST_PROJECT_CONFIGS: ""
  KBC_STORAGE_TOKEN: ${{ secrets.KBC_STORAGE_TOKEN }}

新しいパイプライン構成（標準テンプレートの内容をそのまま維持してください）：

• push_event_info — ブランチ／タグの判定、is_deploy_ready 出力（デフォルトブランチとセマンティックタグが必要）
• build-test — --target test ステージをビルドし、*-test.tar アーティファクトをアップロード
• tests — テストアーティファクトをダウンロードしてコンテナーを実行（デフォルトの CMD は pytest。ruff はビルド時に実行済み）
• tests-kbc — KBC_TEST_PROJECT_CONFIGS とトークンが設定されている場合に KBC 統合テストを実行
• build-production — すべてのテストの合格後に --target production ステージをビルドし、*.tar アーティファクトをアップロード
• push — 本番用アーティファクトを読み込み、ECR にプッシュ
• deploy — is_deploy_ready == true の場合にのみ、Developer Portal でタグを設定
• update_developer_portal_properties — scripts/developer_portal/update_properties.sh を実行

ロックファイルを生成／検証する

uv add はコミット 1 で uv.lock をすでに更新しています。完全に整合していることを確認するため、これを実行してください。

uv sync --all-groups

コミットする

git add Dockerfile scripts/ tests/ .github/workflows/
git commit -m "uv 💜"

---

コミット 3：ruff によるリンティングのベースライン 🎨

ruff format .
ruff check --fix .

ファイルに変更があればコミットします。

git add src/ tests/
git commit -m "ruff linting baseline 🎨"

フェーズ 6：Cookiecutter との整合性チェック

Task ツールを使って、標準テンプレートファイルを読み込みます：

• subagent_type: component-developer:component-defaults
• prompt: "Return the canonical Keboola component template files."

次の各ファイルを、返された標準バージョンと比較します：

コンポーネントファイル	標準
Dockerfile	component-defaults から
.github/workflows/push.yml	component-defaults から
scripts/build_n_test.sh	component-defaults から
docker-compose.yml	component-defaults から
.pre-commit-config.yaml	component-defaults から

構造上の違いを修正します。コンポーネント固有の追加項目（カスタム apt パッケージ、SSL 証明書など）は維持します。 不足しているファイルは標準バージョンから作成します（古いコンポーネントには .pre-commit-config.yaml がないことがよくあります）。

git add Dockerfile scripts/ .github/workflows/ docker-compose.yml .pre-commit-config.yaml
git commit -m "align with cookiecutter template 🍪"

---

検証

# Build and run tests (ruff runs at build time inside the test stage)
docker build --target test -t test-component .
docker run test-component

# Optionally verify the production image builds cleanly
docker build --target production -t prod-component .

---

よくあるパターン

依存関係の変換：

requirements.txt          pyproject.toml
keboola.component==1.4.4  "keboola-component>=1.4.4"
mock                      "mock>=5.2.0"  (in dev group)

Ruff 設定（pyupgrade には常に "UP" を使用します）：

[tool.ruff]
line-length = 120
target-version = "py313"

[tool.ruff.lint]
extend-select = ["I", "UP"]