Migrate to poetry or uv for dependency management

[arkid15r]

The Open World Holidays Framework currently manages dependencies using requirements.txt. To improve dependency management, we should consider migrating to either Poetry or UV, both of which offer modern, streamlined dependency management with built-in lock files. This task requires evaluating the pros and cons of Poetry and UV, deciding on the most suitable tool, and updating the project accordingly.

Why Migrate?

Migrating to a modern dependency management tool will:

• Provide built-in lock file support for reproducible builds.
• Simplify dependency management (adding/removing packages).
• Improve security through built-in hash verification.
• Streamline dependency updates and resolution processes.

Steps to Complete This Task

1. Evaluate Poetry vs UV

• Research and document the pros and cons of Poetry and UV, specifically considering:

  • Ease of use and learning curve.
  • Build and packaging capabilities.
  • Virtual environment management.
  • Compatibility with our existing infrastructure (e.g., CI pipelines).
  • Speed of dependency resolution and installation.
  • Support for hash-locked dependencies.
  • Community adoption and long-term maintenance.

• Reference materials:

  • Poetry: https://python-poetry.org/docs/
  • UV: https://github.com/astral-sh/uv

• Add a short summary of the comparison in the comments of this GitHub issue.

2. Decide on the Tool

• Based on the pros/cons comparison, decide whether to use Poetry or UV.
• Justify the choice in the comments section for visibility and future reference.

3. Update the Project

• If Poetry is selected:

  • Create a pyproject.toml file.
  • Run:

    poetry init
    poetry add <all-dependencies>
    poetry lock
    

  • Update the CI pipeline to use:

    poetry install
    

  • Remove requirements.txt and replace it with a lock file (poetry.lock).

• If UV is selected:

  • Create a pyproject.toml file.
  • Run:

    uv pip compile --all-extras
    uv pip install -r requirements.txt
    

  • Update the CI pipeline to use:

    uv pip install -r requirements.txt
    

  • Retain requirements.txt with hash checksums for compatibility but remove manual dependency management.

4. Verify Dependency Installation

• Test local development setup using the new tool.
• Ensure that pip install -r requirements.txt still works (if applicable).
• Verify that the Dockerfile (if any) or deployment environments still function correctly.

5. Update Documentation

• Update the README.md or CONTRIBUTING.md with instructions for managing dependencies using the new tool.
• Clearly document:
  • How to add/remove dependencies.
  • How to update lock files.
  • How to install dependencies in development or production.

6. Update CI Pipeline

• Modify GitHub Actions or any existing CI pipelines to use the new dependency manager.
• Ensure the pipeline uses lock files for reproducible builds.

Acceptance Criteria

• A clear comparison of Poetry vs UV with a decision documented in the issue comments.
• Migration to either Poetry or UV is complete.
• All dependencies are managed through a pyproject.toml file.
• The lock file ensures reproducible builds with hash verification.
• CI pipelines are updated to reflect the new dependency management approach.
• Documentation is updated accordingly.

Notes

• Avoid breaking existing deployment pipelines.
• Minimize disruption for contributors by providing clear upgrade instructions.
• If unsure about any migration step, ask for feedback in the issue comments.

[RedK22]

Can I work on this?

[shreyanshVIT23]

/assign

[PPsyrius]

@arkid15r see above

[shreyanshVIT23]

Poetry vs UV Comparison Summary

Core Functionality & Purpose

• Poetry: A full-featured package lifecycle manager that handles dependencies, building, and publishing
• UV: A fast dependency manager that acts as a direct pip replacement, focused on speed and compatibility

Key Strengths

Poetry

• Comprehensive all-in-one solution for packaging, publishing, and dependency management
• Built-in version management and virtual environment handling
• Well-established with large user base and community support since 2018
• Strong documentation and consistent command structure

UV

• Extremely fast (10-100x faster than pip, 50-80% CI time reduction)
• Drop-in replacement for pip with minimal workflow changes
• Compatible with existing requirements.txt files and build systems
• Rust-based implementation for consistent cross-platform performance

Project Integration Considerations

• For projects already built around pip workflows, UV offers less disruptive adoption
• Projects requiring full package lifecycle management benefit more from Poetry
• Multiple requirements files are better supported by UV
• Complex CI/CD pipelines with diverse testing matrices perform better with UV

For this specific project Open World Holidays Framework, UV is recommended because it could integrate with the existing pip-based structure, preserve the multi-file requirements approach, maintain compatibility with current build systems, and significantly improve CI testing performance across multiple platforms and Python versions without disrupting established contributor workflows.