build(uv): switch from poetry to uv for project management (#1749)

Co-authored-by: Wei Lee <[email protected]>
Co-authored-by: Benedikt Ziegler <[email protected]>

Author: 3 people

.github/pull_request_template.md

@@ -14,7 +14,7 @@ Please fill in the following content to let us know better about this change.
 ### Code Changes
 
 - [ ] Add test cases to all the changes you introduce
-- [ ] Run `poetry all` locally to ensure this change passes linter check and tests
+- [ ] Run `uv run poe all` locally to ensure this change passes linter check and tests
 - [ ] Manually test the changes:
   - [ ] Verify the feature/bug fix works as expected in real-world scenarios
   - [ ] Test edge cases and error conditions
@@ -24,10 +24,10 @@ Please fill in the following content to let us know better about this change.
 
 ### Documentation Changes
 
-- [ ] Run `poetry doc` locally to ensure the documentation pages renders correctly
+- [ ] Run `uv run poe doc` locally to ensure the documentation pages renders correctly
 - [ ] Check and fix any broken links (internal or external) in the documentation
 
-> When running `poetry doc`, any broken internal documentation links will be reported in the console output like this:
+> When running `uv run poe doc`, any broken internal documentation links will be reported in the console output like this:
 >
 > ```text
 > INFO    -  Doc file 'config.md' contains a link 'commands/bump.md#-post_bump_hooks', but the doc 'commands/bump.md' does not contain an anchor '#-post_bump_hooks'.

.github/workflows/docspublish.yml

@@ -15,17 +15,16 @@ jobs:
           token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
           fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.x"
       - name: Install dependencies
         run: |
-          python -m pip install -U pip poetry poethepoet
-          poetry --version
-          poetry install --only main,script
+          uv --version
+          uv sync --locked --group script
       - name: Update CLI screenshots
         run: |
-          poetry doc:screenshots
+          uv run poe doc:screenshots
       - name: Commit and push updated CLI screenshots
         run: |
           git config --global user.name "github-actions[bot]"
@@ -51,14 +50,13 @@ jobs:
         run: |
           git pull origin master
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.x"
       - name: Install dependencies
         run: |
-          python -m pip install -U pip poetry poethepoet
-          poetry --version
-          poetry install --no-root --only documentation
+          uv --version
+          uv sync --locked --only-group documentation
       - name: Generate Sponsors 💖
         uses: JamesIves/github-sponsors-readme-action@v1
         with:
@@ -69,7 +67,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          poetry doc:build
+          uv run poe doc:build
       - name: Deploy 🚀
         uses: JamesIves/github-pages-deploy-action@v4
         with:

.github/workflows/homebrewpublish.yml

@@ -14,12 +14,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.x"
       - name: Install dependencies
-        run: |
-          python -m pip install -U commitizen
+        run: uv pip install -U commitizen
       - name: Set Project version env variable
         run: |
           echo "project_version=$(cz version --project)" >> $GITHUB_ENV

.github/workflows/pythonpackage.yml

@@ -19,19 +19,18 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
-          python -m pip install -U pip poetry poethepoet
-          poetry --version
-          poetry install --only main,linters,test
+          uv --version
+          uv sync --locked --dev --group test --group linters
       - name: Run tests and linters
         run: |
           git config --global user.email "[email protected]"
           git config --global user.name "GitHub Action"
-          poetry ci
+          uv run poe ci
         shell: bash
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5

.github/workflows/pythonpublish.yml

@@ -14,15 +14,10 @@ jobs:
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
           fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.x"
-      - name: Install dependencies
-        run: |
-          python -m pip install -U pip poetry
-          poetry --version
+      - name: Build
+        run: uv build
       - name: Publish
-        env:
-          POETRY_HTTP_BASIC_PYPI_USERNAME: ${{ secrets.PYPI_USERNAME }}
-          POETRY_HTTP_BASIC_PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
-        run: poetry publish --build
+        run: uv publish

.pre-commit-config.yaml

@@ -29,6 +29,14 @@ repos:
         args: [ '--unsafe' ] # for mkdocs.yml
       - id: detect-private-key
 
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.9.18
+    hooks:
+      - id: uv-lock
+      - id: uv-sync
+        args: [ --locked, --all-groups ]
+        stages: [ pre-commit, post-checkout, post-merge, post-rewrite ]
+
   - repo: https://github.com/asottile/blacken-docs
     rev: 1.19.1
     hooks:
@@ -63,15 +71,15 @@ repos:
   - repo: local
     hooks:
       - id: format
-        name: Format Python code via Poetry
+        name: Format Python code
         language: system
         pass_filenames: false
-        entry: poetry format
+        entry: uv run poe format
         types: [ python ]
 
       - id: linter and test
-        name: Linters via Poetry
+        name: Linters
         language: system
         pass_filenames: false
-        entry: poetry lint
+        entry: uv run poe lint
         types: [ python ]

docs/contributing.md

@@ -16,7 +16,7 @@ If you're a first-time contributor, please check out issues labeled [good first
 
 1. **Python Environment**
     - Python `>=3.10`
-    - [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer) `>=2.2.0`
+    - [uv](https://docs.astral.sh/uv/getting-started/installation/) `>=0.9.0`
 2. **Version Control & Security**
     - Git
     - Commitizen
@@ -38,13 +38,13 @@ If you're a first-time contributor, please check out issues labeled [good first
     ```bash
     git remote add upstream https://github.com/commitizen-tools/commitizen.git
     ```
-4. Set up the development environment (nix users go to [nix section](#nix)):
+4. Set up the development environment:
     ```bash
-    poetry install
+    uv sync --dev
     ```
 5. Set up pre-commit hooks:
     ```bash
-    poetry setup-pre-commit
+    uv run poe setup-pre-commit
     ```
 
 ## Development Workflow
@@ -61,15 +61,15 @@ If you're a first-time contributor, please check out issues labeled [good first
     - Update documentation if needed
     - Follow the existing code style
 3. **Testing**
-    - Run the full test suite: `poetry all`
+    - Run the full test suite: `uv run poe all`
     - Ensure test coverage doesn't drop (we use [CodeCov](https://app.codecov.io/gh/commitizen-tools/commitizen))
-    - For documentation changes, run `poetry doc` to check for warnings/errors
+    - For documentation changes, run `uv run poe doc` to check for warnings/errors
 4. **Committing Changes**
     - Use Commitizen to make commits (we follow [conventional commits](https://www.conventionalcommits.org/))
     - Example: `cz commit`
 5. **Documentation**
     - Update `docs/README.md` if needed
-    - For CLI help screenshots: `poetry doc:screenshots`
+    - For CLI help screenshots: `uv run poe doc:screenshots`
     - Prefer [Google style documentation](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings), which works well with editors like VSCode and PyCharm
     - **DO NOT** update `CHANGELOG.md` (automatically generated)
     - **DO NOT** update version numbers (automatically handled)
@@ -154,16 +154,3 @@ flowchart TD
     --modification-received-->
     review
 ```
-
-## Nix
-
-If you have installed poetry globally, the project won't work because it requires `poethepoet` for command management.
-
-You'll have to install poetry locally.
-
-```sh
-python -m venv .venv
-. .venv/bin/activate
-pip install -U pip && pip install poetry
-poetry install
-```

docs/contributing_tldr.md

@@ -3,7 +3,7 @@ Feel free to send a PR to update this file if you find anything useful. 🙇
 ## Environment
 
 - Python `>=3.10`
-- [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer) `>=2.2.0`
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) `>=0.9.0`
 
 ## Useful commands
 
@@ -12,14 +12,14 @@ Please check the [pyproject.toml](https://github.com/commitizen-tools/commitizen
 ### Code Changes
 
 ```bash
-# Ensure you have the correct dependencies, for nix user's see below
-poetry install
+# Ensure you have the correct dependencies
+uv sync --dev
 
 # Make ruff happy
-poetry format
+uv run poe format
 
 # Check if ruff and mypy are happy
-poetry lint
+uv run poe lint
 
 # Check if mypy is happy in python 3.10
 mypy --python-version 3.10
@@ -33,16 +33,5 @@ pytest -n auto <test_suite>
 
 ```bash
 # Build the documentation locally and check for broken links
-poetry doc
-```
-
-### Nix Users
-
-If you are using Nix, you can install poetry locally by running:
-
-```sh
-python -m venv .venv
-. .venv/bin/activate
-pip install -U pip && pip install poetry
-poetry install
+uv run poe doc
 ```