feat: migrate to uv

[jorgeparavicini]

No description provided.

[claude]

Pull Request Review: Migration to uv

Overview

This PR migrates the project from Poetry to uv for dependency management and build tooling. This is a significant infrastructure change that affects CI/CD workflows, dependency management, and publishing processes.

✅ Strengths

1. Modernization

• Moving to uv is a good choice - it's significantly faster than Poetry and has better performance characteristics
• Proper use of .python-version file for consistent Python version management across environments
• Updated to latest GitHub Actions versions (e.g., actions/setup-python@v6)

2. Clean Migration

• Proper removal of poetry.lock and addition of uv.lock
• Consistent updates across all workflow files
• Good use of uv's official setup action (astral-sh/setup-uv@v7)

3. Workflow Improvements

• Using --frozen flag in workflows to ensure reproducible builds
• Using python-version-file parameter instead of hardcoding Python version
• Simplified workflow steps (fewer commands needed with uv)

⚠️ Critical Issues

1. Release Workflow Bug 🔴

File: .github/workflows/release_and_publish.yml:32-36

The version bump commands are incorrect - uv version shows uv's own version NOT the project version. This workflow will fail.

Fix needed: Use a Python script or sed to bump version in pyproject.toml

2. Missing Publishing Token Configuration ⚠️

File: .github/workflows/release_and_publish.yml:79-80

The uv publish command needs the PyPI token to be configured. Unlike Poetry which has poetry config pypi-token.pypi, uv uses environment variables or command-line flags.

Fix needed: Use --token flag or UV_PUBLISH_TOKEN environment variable

3. Documentation Workflow Issue ⚠️

File: .github/workflows/docs_gh_pages.yml:18

Parameter name is incorrect - should be python-version-file not python-version

🎯 Recommendations

High Priority (Must Fix Before Merge)

1. Fix the version bumping logic in release_and_publish.yml
2. Fix the PyPI token configuration for uv publish
3. Fix the python-version-file parameter in docs_gh_pages.yml

Medium Priority

4. Verify test workflows are updated (if they exist)
5. Add a test run to verify the migration works
6. Update developer documentation about switching from Poetry to uv

Summary

This is a solid migration effort with good modernization benefits. However there are critical bugs in the release workflow that must be fixed before merging. The version bumping and publishing logic needs to be corrected to work with uv's command structure.

Recommendation: Do not merge until the critical issues are addressed.

[claude]

Pull Request Review: Migration to uv

This PR migrates the project from Poetry to uv as the package manager. Overall, this is a solid modernization effort that should improve build times and developer experience.

Critical Issues

1. Release Workflow - Incorrect Version Command
Location: .github/workflows/release_and_publish.yml:32-34

The commands 'uv version --short' display the uv tool version, NOT the project version. This will break releases.

Fix: Use 'grep' to read from pyproject.toml or use 'uv run hatch version' with hatchling.

2. Build Backend Configuration
Location: pyproject.toml

'hatchling>=1.28.0' is listed as a runtime dependency but should ONLY be in [build-system]. Build tools should not be runtime dependencies.

High Priority Issues

3. Dependency Version Constraints Tightened

• authlib: ^1.5.1 → ==1.6.5 (exact pinning may cause conflicts)
• httpx: ^0.28.1 → >=0.28.1,<0.29 (more restrictive)

Consider using more flexible constraints unless there's a specific reason.

4. Missing Test Workflow
The repository has tests but no test workflow was updated. Verify if one exists.

Medium Priority

5. Documentation Workflow Redundancy
The docs build runs twice unnecessarily. mkdocs --clean already removes site/.

6. Black Version Jump
Black updated from ^24.8.0 to >=25.11.0 (major version). Run formatting check.

Strengths

• Comprehensive migration across all workflows
• Proper use of PEP 621 format
• Added .python-version file
• Updated to latest GitHub Actions versions
• Correct use of dependency-groups

Security

No security concerns identified. Token handling remains secure.

Summary

Must fix before merge: Issues #1 and #2
Should address: Issues #3 and #4
Overall: Well-structured migration with critical workflow bug that must be fixed.

[claude]

Pull Request Review: Migration to uv

Overview

This PR migrates the project from Poetry to uv for dependency management and builds. Overall, this is a solid modernization effort that should improve build times and simplify the toolchain.

---

🔴 Critical Issues

1. Incorrect uv commands in release workflow

Location: .github/workflows/release_and_publish.yml:43-47

The workflow uses uv version --short and uv version <part> commands, but these are not valid uv commands. The uv tool does not have a version subcommand for bumping versions.

Current code:

old_version=$(uv version --short)
uv version ${{ github.event.inputs.version_part }}
new_version=$(uv version --short)

Issue: This will cause the release workflow to fail when triggered.

Suggested fix: You need to either:

• Use a separate tool like bump2version or bump-my-version to handle version bumping
• Manually parse and update the version in pyproject.toml using a Python script
• Use uv run with a versioning tool

Example solution:

# Read current version from pyproject.toml
old_version=$(grep "^version = " pyproject.toml | cut -d\" -f2)

# Use Python to bump the version
python << 'EOF'
import re

with open('pyproject.toml', 'r') as f:
    content = f.read()

# Extract current version
current = re.search(r'version = "([^"]+)"', content).group(1)
major, minor, patch = map(int, current.split('.'))

# Bump based on input (you would use the workflow input here)
# This is just an example
patch += 1
new_version = f"{major}.{minor}.{patch}"

# Update the file
content = re.sub(r'version = "[^"]+"', f'version = "{new_version}"', content)
with open('pyproject.toml', 'w') as f:
    f.write(content)
EOF

# Read new version
new_version=$(grep "^version = " pyproject.toml | cut -d\" -f2)

---

⚠️ Major Concerns

2. Missing pyproject.toml build configuration validation

The pyproject.toml now uses hatchling as the build backend instead of Poetry's built-in build system. While this is fine, there are some concerns:

• The pyproject.toml:26 includes "hatchling>=1.28.0" as a runtime dependency, which is unusual. Hatchling is typically only needed as a build-time dependency (in build-system.requires). This will unnecessarily bloat installed packages.

Recommendation: Remove hatchling from the dependencies list at line 26, as it's already specified in build-system.requires at line 65.

3. Python version specification

The .python-version file specifies 3.10 without a patch version. While uv should handle this correctly, it's more explicit and reproducible to specify a full version (e.g., 3.10.15).

Current: 3.10
Recommended: 3.10.15 (or latest 3.10.x)

4. Dependency groups vs extras

The migration changes from Poetry's groups to uv's dependency-groups. The [tool.uv] section sets default-groups = ["dev", "docs"], which means these will be installed by default with uv sync.

Concern: This might not be desired behavior for end users installing the package. Typically, only core dependencies should be installed by default, with dev/docs dependencies being optional.

Recommendation: Consider whether default-groups should be empty or only include groups that are truly needed for normal package usage.

---

✅ Positive Aspects

1. Consistent workflow updates: All three workflow files have been properly updated to use uv
2. Lock file generation: The uv.lock file has been properly generated with comprehensive platform-specific wheels
3. Build backend modernization: Moving to hatchling provides a standards-compliant build system
4. Version pinning: Good use of --frozen flag in deploy_doc.yml to ensure reproducible builds

---

📋 Minor Suggestions

5. Pyright configuration

In .github/workflows/pyright-type-checking.yml:20, the PATH manipulation has been removed. Verify that pyright can still find the installed packages. You might need to use uv run pyright instead of relying on PATH.

6. Documentation updates

Consider updating the README.md or adding a CONTRIBUTING.md file to document:

• How to set up the development environment with uv
• Migration notes for existing contributors using Poetry
• New commands for common tasks

7. Testing the release workflow

Given the critical issues in the release workflow, I strongly recommend:

• Testing the version bumping logic manually before merging
• Consider adding a test workflow that validates the version bumping without actually publishing

---

🔒 Security Considerations

No security concerns identified. The migration does not introduce any vulnerable dependencies or insecure practices.

---

🧪 Test Coverage

The PR does not include any test files or test execution in the workflows. Consider adding:

• A CI workflow that runs uv run pytest (if tests exist)
• Verification that the built package can be installed and imported correctly

---

Summary & Recommendation

Status: ❌ NEEDS CHANGES - Critical issue in release workflow must be fixed

Priority fixes:

1. Fix the uv version command issue in release_and_publish.yml (CRITICAL)
2. Remove hatchling from runtime dependencies (MAJOR)
3. Review default-groups configuration (MAJOR)

Before merging:

• Test the release workflow with the corrected version bumping logic
• Verify that uv build produces correct wheel and sdist files
• Test installation from the built artifacts

Once these issues are addressed, this migration will significantly improve the development experience! 🚀

[claude]

PR Review: Migration from Poetry to uv

Summary: This PR migrates from Poetry to uv for dependency management, updating workflows, replacing poetry.lock with uv.lock, and converting to dependency groups.

---

Critical Issues

1. BROKEN: uv version command (release_and_publish.yml:43-47)

The workflow uses uv version --short and uv version but these commands DO NOT EXIST in uv. The uv version command only shows uv's own version, not the project version. This will BREAK ALL FUTURE RELEASES.

RECOMMENDED FIX - Use hatch for version management:

• Add step: uv pip install hatch
• Use: hatch version (to read version)
• Use: hatch version patch/minor/major (to bump version)

2. Authlib version changed from 1.6.0 to 1.6.5 (pyproject.toml:19)
Was this intentional? The PR description does not mention dependency updates.

3. Lock file mismatch risk
The uv.lock was generated fresh and may have pulled newer dependency versions than what was in poetry.lock. Review changes carefully and test thoroughly.

---

Warnings

4. Tight authlib version pin (==1.6.5) prevents security patch updates. Consider using >=1.6.5,<2 instead.

5. Missing documentation updates - check README.md and any CONTRIBUTING docs that reference Poetry.

6. Verify all dependency groups migrated correctly (dev, docs).

---

Minor Issues

7. Pyright version pinned to old v1.1.396 in workflow, but pyproject.toml has 1.1.407. Consider updating.

8. Extra whitespace in deploy_doc.yml:42 - double space after run:

9. Python 3.10 is now standard via .python-version file (this is good for consistency).

---

Strengths

• Modern tooling: uv is significantly faster than Poetry
• Comprehensive migration: all workflows updated consistently
• Updated GitHub Actions to latest versions
• Added .python-version for consistency

---

Security & Performance

• No security vulnerabilities introduced
• All GitHub Actions from trusted sources
• uv is 10-100x faster than Poetry - expect major CI/CD speedups

---

Action Items

MUST FIX BEFORE MERGE:

1. Fix the uv version command issue (critical - will break releases)
2. Verify authlib 1.6.5 change was intentional
3. Review dependency version changes between locks

SHOULD FIX:
4. Update documentation to reflect uv migration
5. Update pyright version in workflow
6. Fix double space formatting

CONSIDER:
7. Loosen authlib version constraint
8. Add migration notes to PR description

---

Overall Assessment

• Code Quality: Good (comprehensive and consistent migration)
• Risk Level: HIGH (broken release workflow)
• Testing Needs: Critical (must test release workflow)
• Merge Recommendation: DO NOT MERGE until uv version issue is fixed

The migration to uv is excellent for performance and developer experience, but the critical bug in the release workflow MUST be fixed first to prevent broken releases.