DevX: Migrate from Poetry to uv for faster dependency management

[dougborg]

Summary

Migrate the project's build and dependency management from Poetry to uv, a significantly faster Python package installer and resolver written in Rust.

Motivation

Performance Improvements:

• uv is 10-100x faster than pip/Poetry for dependency resolution
• Dramatically reduces CI/CD build times
• Faster local development environment setup
• Near-instant virtual environment creation

Developer Experience:

• Simpler, more reliable dependency management
• Better compatibility with standard Python tooling
• Drop-in replacement for pip/Poetry commands
• Single tool for multiple Python versions

Real-World Impact:

• Current Poetry install time: ~60-120s in CI
• Expected uv install time: ~5-15s in CI
• Saves 45-105s per CI run across all Python versions
• For PR Add static file infrastructure for generated clients #125 (5 Python versions): saves 4-9 minutes per CI run

Proposed Changes

1. Project Files

Replace pyproject.toml Poetry-specific sections with standard PEP 621:

[project]
name = "openapi-python-generator"
version = "0.x.x"
dependencies = [
    "pydantic>=2.0",
    # ... existing deps
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=23.0",
    # ... existing dev deps
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Remove:

• poetry.lock (replaced by uv.lock)
• Poetry-specific [tool.poetry] sections

Add:

• uv.lock (generated by uv)
• .python-version (for uv Python version management)

2. GitHub Actions Workflow

Before (.github/workflows/test.yml):

- name: Install Poetry
  run: pipx install poetry
  
- name: Install dependencies
  run: poetry install
  
- name: Run tests
  run: poetry run pytest

After:

- name: Install uv
  run: curl -LsSf https://astral.sh/uv/install.sh | sh
  
- name: Install dependencies
  run: uv sync
  
- name: Run tests
  run: uv run pytest

3. Developer Workflow

Before:

poetry install
poetry run pytest
poetry add some-package

After:

uv sync
uv run pytest
uv add some-package

4. Documentation Updates

• Update README.md with uv installation instructions
• Update CONTRIBUTING.md with new developer workflow
• Add migration notes for existing contributors

Implementation Plan

• Phase 1: Setup

  • Install uv in CI workflows
  • Add uv.lock to repository
  • Convert pyproject.toml to PEP 621 format

• Phase 2: CI Migration

  • Update .github/workflows/test.yml
  • Update .github/workflows/publish.yml (if exists)
  • Verify all CI jobs pass with uv

• Phase 3: Documentation

  • Update README.md installation instructions
  • Update CONTRIBUTING.md developer setup
  • Add migration guide for existing developers

• Phase 4: Cleanup

  • Remove poetry.lock
  • Remove Poetry-specific configurations
  • Archive Poetry documentation in MIGRATION.md

Backwards Compatibility

• No impact on generated code - Only affects development workflow
• No impact on published package - Package distribution unchanged
• Contributors need to install uv - One-time setup change

Benefits Summary

✅ 10-100x faster dependency resolution
✅ 4-9 minutes saved per PR CI run (5 Python versions)
✅ Simpler workflow - fewer commands, clearer output
✅ Standard Python - PEP 621 compliant, better interoperability
✅ Future-proof - uv is actively developed by Astral (ruff creators)

Resources

• uv Documentation
• uv Installation
• Migration from Poetry
• PEP 621 - Python project metadata standard

Related Issues

• Improves CI performance for all PRs (including Design: Enhanced Error Handling for Generated Clients (#100) #124, Add static file infrastructure for generated clients #125)
• Complements pre-commit hooks (#TBD)
• Reduces contributor setup friction

Labels

• enhancement
• devx (developer experience)
• ci