migrate-component-to-uv（将组件迁移到 uv）

Migrate Keboola Component to uv Build System

You are an expert at migrating Keboola Python packages from legacy setup.py + pip to modern pyproject.toml + uv build system. You understand PEP 517/518/639 standards, GitHub Actions workflows, and Keboola's established migration patterns.

When to Use This Skill

Use this skill when:

• Migrating a Keboola Python package from setup.py to pyproject.toml
• Modernizing build system to use uv instead of pip
• Adding deterministic dependency management with uv.lock
• Updating CI/CD workflows to use uv
• Following Keboola's python-http-client and python-component patterns

Prerequisites Check

Before starting, verify:

• [ ] Repository uses setup.py and/or requirements.txt
• [ ] Package has test suite with pytest
• [ ] Git repository with clean working tree
• [ ] Access to GitHub secrets configuration
• [ ] PyPI and Test PyPI accounts available

Migration Philosophy

Flexible Commit Strategy

Guideline (not dogma): Use 3 logical commits

1. Linting baseline - Fix linting first to avoid noise in migration diffs
2. Package metadata - Migrate to pyproject.toml
3. CI/CD workflows - Update to uv + generate lock file

Why this works:

• Clean diffs: Linting fixes don't pollute actual migration changes
• Reviewable: Each commit has clear, focused purpose
• Flexible: Could be 2 commits (combine lint+pyproject) or 4 (separate workflows)

Key principle: Logical, reviewable chunks that make sense independently

Lint-First Principle

Always fix linting BEFORE migrating metadata:

• Establishes clean baseline
• Reveals code quality issues early
• Prevents attribution confusion (linting vs migration changes)
• Makes review significantly easier

Version Strategy

Testing phase: Use next minor version

• Example: Current 1.6.13 → Test as 1.7.0, 1.7.1, 1.7.2

Production release: Use following minor version

• Example: After testing 1.7.x → Release 1.8.0

Flexibility: Could use 1.7.0a1, 1.7.0a2 instead - pattern matters, not exact format

Step-by-Step Migration Guide

Phase 1: Analysis

1. Check current state:

# What's in setup.py?
cat setup.py

# What's in requirements.txt?
cat requirements.txt

# What's the current version?
# Check PyPI or setup.py

1. Identify Python version support:

# From setup.py python_requires
# Determine: min_version = max(3.8, current_requires_python)

1. Check for docs generation:

# Does push_main.yml exist with pdoc?
cat .github/workflows/push_main.yml 2>/dev/null | grep pdoc

Phase 2: Commit 1 - Linting Baseline

Purpose: Establish clean linting baseline

Steps:

1. Rename and update flake8 config:

# Rename to standard name
mv flake8.cfg .flake8  # if it exists

# Use cookiecutter template standard:
cat > .flake8 << 'EOF'
[flake8]
exclude = __pycache__, .git, .venv, venv, docs
ignore = E203,W503
max-line-length = 120
EOF

1. Run flake8 and fix ALL errors:

# Install flake8
uv add --dev flake8

# Run and fix errors
flake8 src/ tests/

Common fixes:

• F403/F405: Replace star imports with explicit imports
• F841: Remove unused variables
• E501: Break long lines
• E231: Add missing whitespace
• E123: Fix bracket indentation
• CRLF→LF: Normalize line endings (expected, good cleanup)

1. Commit:

git add .flake8 src/ tests/
git commit -m "flake8 config consistent with cookiecutter template 🍪"

Phase 3: Commit 2 - Package Metadata

Purpose: Migrate to modern pyproject.toml

Steps:

1. Create pyproject.toml (see templates/pyproject.toml.template):

Key points:

• version = "0.0.0" - replaced by git tags in CI
• Extract dependencies from setup.py install_requires
• Extract dev dependencies from setup.py setup_requires and tests_require
• Add pdoc3 to dev if docs workflow exists
• requires-python = ">=MIN_VERSION" (≥3.8)
• Remove License :: OSI Approved :: MIT License classifier (PEP 639)
• Keep license = "MIT" field
• Add TestPyPI index configuration

1. Delete old files:

git rm setup.py requirements.txt

1. Update LICENSE copyright year:

# Update to current year (2026)
sed -i 's/Copyright (c) 20[0-9][0-9]/Copyright (c) 2026/' LICENSE

1. Commit:

git add pyproject.toml LICENSE
git commit -m "migrate package configuration to pyproject.toml 📦"

Phase 4: Commit 3 - uv Workflows

Purpose: Update CI/CD to use uv

Steps:

1. Update all 3-4 workflows (see references/workflow-templates.md):

- push_dev.yml - Testing on dev branches - deploy.yml - Production PyPI deployment - deploy_to_test.yml - Test PyPI deployment - push_main.yml - Docs generation (OPTIONAL - only if docs exist)

Key changes per workflow:

• Update action versions: @v4 → @v5, @v6
• Add uv installation: uses: astral-sh/setup-uv@v6
• Add ruff action: uses: astral-sh/ruff-action@v3 (blocking, no continue-on-error)
• Change: pip install → uv sync --all-groups --frozen
• Change: flake8 --config=... → uv run flake8
• Change: pytest tests → uv run pytest tests
• Add version replacement: uv version $TAG_VERSION
• Update secrets: UV_PUBLISH_TOKEN, UV_PUBLISH_TOKEN_TEST_PYPI
• Python matrix: [MIN_VERSION, "3.13", "3.14"] (min + 2 latest)

1. Generate uv.lock:

uv sync --all-groups

1. Verify build works:

uv build
# Should create dist/*.tar.gz and dist/*.whl

uv version 1.7.0 --dry-run
# Should show: package-name 0.0.0 => 1.7.0

1. Commit:

git add .github/workflows/*.yml uv.lock
git commit -m "uv 💜"

Phase 5: Testing on Test PyPI

1. Push branch:

git push origin BRANCH_NAME

1. Create test tag:

git tag 1.7.0
git push origin 1.7.0

1. Manually trigger Test PyPI workflow:

- Go to GitHub Actions → "Build & Upload Python Package To Test PyPI" - Click "Run workflow" - Select branch or tag - Click "Run workflow"

1. Verify on Test PyPI:

- Check: https://test.pypi.org/project/PACKAGE_NAME/ - Verify version appears

1. Test installation:

cd /tmp && mkdir test_install && cd test_install
uv init
uv add --index-url https://test.pypi.org/simple/ \
       --extra-index-url https://pypi.org/simple/ \
       --index-strategy unsafe-best-match \
       PACKAGE_NAME==1.7.0
uv run python -c "import PACKAGE; print('✅ Works!')"
cd .. && rm -rf test_install

Phase 6: Production Release

1. Create PR (see templates/pr-description.md.template)

1. Get approval and merge to main

1. Create production release:

- Go to: https://github.com/ORG/REPO/releases/new - Tag: 1.8.0 - Target: main - Title: 1.8.0 - Description: Migration summary - Click "Publish release"

1. Workflow auto-triggers → Publishes to PyPI

1. Verify production:

cd /tmp && mkdir test_prod && cd test_prod
uv init
uv add PACKAGE_NAME==1.8.0
uv run python -c "import PACKAGE; print('✅ Production works!')"
cd .. && rm -rf test_prod

Python Matrix Strategy

Smart matrix logic:

python-version: [
  "MIN_SUPPORTED",  # max(3.8, current_requires_python)
  "3.13",           # Second-latest stable
  "3.14"            # Latest stable
]

Examples:

• Package supports ≥3.8 → ["3.8", "3.13", "3.14"]
• Package supports ≥3.10 → ["3.10", "3.13", "3.14"]
• Package supports ≥3.12 → ["3.12", "3.13", "3.14"]

Rationale: Test minimum (compatibility floor) + 2 latest (future-proofing)

Docs Workflow Handling

Detection:

# Check if push_main.yml exists AND contains pdoc
if [ -f .github/workflows/push_main.yml ] && grep -q pdoc .github/workflows/push_main.yml; then
    # Include docs workflow in migration
    # Add pdoc3 to [dependency-groups] dev
fi

Migration for docs:

• Old: pip install --user pdoc3 (ad-hoc)
• New: Add pdoc3 to [dependency-groups] dev + use uv run pdoc
• Improvement: Tracked dependency instead of ad-hoc install

Secret Configuration

Required GitHub secrets:

1. UV_PUBLISH_TOKEN - Production PyPI token

- Create at: https://pypi.org/manage/account/token/ - Scope: Entire account or specific project - Add at: GitHub repo → Settings → Secrets → UV_PUBLISH_TOKEN

1. UV_PUBLISH_TOKEN_TEST_PYPI - Test PyPI token

- Create at: https://test.pypi.org/manage/account/token/ - Scope: Entire account - Add at: GitHub repo → Settings → Secrets → UV_PUBLISH_TOKEN_TEST_PYPI

Note: uv automatically uses __token__ as username when UV_PUBLISH_TOKEN env var is set

Workflow Trigger Strategy

Test PyPI: on: workflow_dispatch (manual)

• Allows testing any version without tag naming constraints
• Full control over when to test

Production PyPI: on: push: tags: ['*'] (automatic)

• Triggers automatically when tag pushed to main
• Simpler workflow: git tag X.Y.Z && git push origin X.Y.Z

Common Issues & Solutions

See references/troubleshooting.md for detailed troubleshooting guide.

Quick fixes:

1. License classifier conflict

- Error: License classifiers have been superseded - Fix: Remove License :: OSI Approved :: MIT License from classifiers

1. CRLF line endings

- Symptom: Huge diffs in unchanged files - Status: Expected and correct (CRLF → LF normalization)

1. Test PyPI installation fails

- Error: No solution found - Fix: Add --index-strategy unsafe-best-match

1. uv version command not found

- Fix: Ensure uv ≥ 0.5.0

Modern Tooling Requirements

100% modern uv - ZERO pip mentions:

✅ CORRECT:

• uv add PACKAGE - Add production dependency
• uv add --dev PACKAGE - Add dev dependency
• uv sync --all-groups --frozen - Install from lock
• uv run COMMAND - Run command in environment
• uv build - Build package
• uv publish - Publish to PyPI

❌ NEVER USE:

• pip install - OLD
• pip - OLD
• uv pip install - WRONG uv usage

References

• references/migration-guide.md - Complete step-by-step guide
• references/workflow-templates.md - All 4 workflow YAML files
• references/troubleshooting.md - Common issues and solutions
• references/examples.md - python-http-client and python-component migrations
• templates/pyproject.toml.template - Template pyproject.toml
• templates/flake8.template - Template .flake8
• templates/pr-description.md.template - PR description template

Questions to Ask User

Before starting:

1. What's the current latest version on PyPI?
2. Do you have access to configure GitHub secrets?
3. What Python versions should we support? (check setup.py)
4. Does the package generate HTML docs with pdoc?
5. Any custom build requirements or special dependencies?

Success Criteria

Migration complete when:

• ✅ All tests pass with uv locally
• ✅ Package builds successfully (uv build)
• ✅ Test PyPI release installable and functional
• ✅ Production PyPI release installable and functional
• ✅ CI/CD workflows green on main branch
• ✅ Documentation updated (if needed)
• ✅ Team notified

Remember: This is a build system migration, NOT an API change. End users should see no difference except faster installs and more reliable dependency resolution.