Switch to uv

[snejus]

I think we've had enough of poetry so I let Claude Code migrate the code base to uv. Let's see.

Fixes: #5783

[github-actions]

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.17%. Comparing base (37d60dd) to head (764ae7e).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #6535   +/-   ##
=======================================
  Coverage   71.17%   71.17%           
=======================================
  Files         150      150           
  Lines       19176    19176           
  Branches     3085     3085           
=======================================
  Hits        13649    13649           
  Misses       4867     4867           
  Partials      660      660           

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

PR switch project from Poetry to uv for dependency manage + build.

Changes:

• Move pyproject.toml from [tool.poetry] to PEP 621 [project], switch build backend to hatchling, add dependency-groups.
• Update docs to tell people use uv sync instead of poetry install.
• Update GitHub Actions workflows to install uv and run uv sync.

Reviewed changes

Copilot reviewed 9 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pyproject.toml	Replace Poetry config with PEP 621 project metadata, hatchling build config, uv dependency groups/extras.
extra/release.py	Read version from [project].version instead of Poetry table.
docs/faq.rst	Update “bleeding edge” install instructions to use uv sync.
docs/dev/plugins/index.rst	Remove Poetry mention/link in packaging tools note.
CONTRIBUTING.rst	Update contributor setup steps from Poetry to uv.
.github/workflows/ci.yaml	Replace Poetry install with uv sync in test matrix.
.github/workflows/lint.yaml	Replace Poetry install with uv sync, swap lockfile trigger to uv.lock.
.github/workflows/integration_test.yaml	Replace Poetry install with uv sync.
.github/workflows/make_release.yaml	Replace Poetry install with uv sync in release automation.

Comments suppressed due to low confidence (6)

.github/workflows/integration_test.yaml:31

• grug see deps install is uv sync, but workflow later run poe test and poe check-docs-links. need venv on PATH (use uv run poe ... or activate .venv). also linkcheck need docs extra; add --extra docs (or separate sync) so sphinx installed.

      - name: Install dependencies
        run: uv sync

      - name: Test
        env:
          INTEGRATION_TEST: 1
        run: poe test

      - name: Check external links in docs
        run: poe check-docs-links

.github/workflows/lint.yaml:72

• grug see uv sync --only-group lint then run poe check-format. if uv install into .venv, ruff binary not on PATH for poe task. please run uv run poe check-format (or activate .venv) so task find ruff.

      - name: Install dependencies
        run: uv sync --only-group lint

      - name: Check code formatting
        # the job output will contain colored diffs with what needs adjusting
        run: poe check-format

.github/workflows/lint.yaml:93

• grug see uv sync --only-group lint then run poe lint .... same venv PATH problem: poe spawn ruff, but shell not in .venv. run via uv run poe lint ... (or activate .venv).

      - name: Install dependencies
        run: uv sync --only-group lint

      - name: Lint code
        run: poe lint --output-format=github ${{ needs.changed-files.outputs.changed_python_files }}

.github/workflows/lint.yaml:115

• grug see uv sync --only-group typing then run mypy via poe check-types .... if mypy installed into .venv, poe need run inside venv or mypy not found. please use uv run (or activate .venv) for this step.

      - name: Install dependencies
        run: uv sync --only-group typing

      - name: Type check code
        uses: liskin/gh-problem-matcher-wrap@v3
        with:
          linters: mypy
          run: poe check-types --show-column-numbers --no-error-summary .

.github/workflows/lint.yaml:145

• grug see docs job do uv sync --no-dev --extra docs, then run poe format-docs (uses docstrfmt) and poe lint-docs. --no-dev likely skip lint group where docstrfmt live, so step fail. also poe should run inside venv (uv run poe ... or activate .venv).

      - name: Install dependencies
        run: uv sync --no-dev --extra docs

      - name: Add Sphinx problem matchers
        run: |
          echo "::add-matcher::.github/problem-matchers/sphinx-build.json"
          echo "::add-matcher::.github/problem-matchers/sphinx-lint.json"

      - name: Check docs formatting
        run: poe format-docs --check

      - name: Lint docs
        run: poe lint-docs

.github/workflows/make_release.yaml:76

• grug see build job install deps then run poe docs / poe changelog / poe build. same story: if uv create .venv, poe tasks not see sphinx/pandoc helpers unless run inside env. please switch these to uv run poe ... (or activate .venv) in this step.

      - name: Install dependencies
        run: uv sync --no-group test --no-group lint --no-group typing --extra docs

      - name: Install pandoc
        run: sudo apt update && sudo apt install pandoc -y

      - name: Obtain the changelog
        id: generate_changelog
        run: |
          poe docs
          {
            echo 'changelog<<EOF'
            poe --quiet changelog
            echo EOF
          } >> "$GITHUB_OUTPUT"

      - name: Build a binary wheel and a source tarball
        run: poe build

[semohr]

We might want to consider migrating to workspaces and separating beetsplug and beets.

[snejus]

We might want to consider migrating to workspaces and separating beetsplug and beets.

Hm, it may not apply to our use case?

Inspired by the Cargo concept of the same name, a workspace is "a collection of one or more packages, called workspace members, that are managed together."

Workspaces organize large codebases by splitting them into multiple packages with common dependencies. Think: a FastAPI-based web application, alongside a series of libraries that are versioned and maintained as separate Python packages, all in the same Git repository.

[snejus]

Just attempted to build the package to see whether it suffers from the same issue (#5770):

$ uv build
Building source distribution...
Building wheel from source distribution...
Successfully built dist/beets-2.9.0.tar.gz
Successfully built dist/beets-2.9.0-py3-none-any.whl
$ tar -vtf dist/beets-2.9.0.tar.gz | head -10
-rw-r--r-- 0/0            1631 2020-02-02 00:00 beets-2.9.0/beets/__init__.py
-rw-r--r-- 0/0             825 2020-02-02 00:00 beets-2.9.0/beets/__main__.py
-rw-r--r-- 0/0            4643 2020-02-02 00:00 beets-2.9.0/beets/config_default.yaml
-rw-r--r-- 0/0             646 2020-02-02 00:00 beets-2.9.0/beets/context.py
-rw-r--r-- 0/0            6766 2020-02-02 00:00 beets-2.9.0/beets/logging.py
-rw-r--r-- 0/0            1021 2020-02-02 00:00 beets-2.9.0/beets/mediafile.py
-rw-r--r-- 0/0           15166 2020-02-02 00:00 beets-2.9.0/beets/metadata_plugins.py
-rw-r--r-- 0/0           23681 2020-02-02 00:00 beets-2.9.0/beets/plugins.py
-rw-r--r-- 0/0               0 2020-02-02 00:00 beets-2.9.0/beets/py.typed
-rw-r--r-- 0/0            1540 2020-02-02 00:00 beets-2.9.0/beets/autotag/__init__.py

It does not use the last file modification dates but AT LEAST it doesn't go back to 1970 like utterly useless poetry>2:

$ uvx poetry'>2' build
Installed 45 packages in 143ms
Building beets (2.9.0)
Building sdist
  - Building sdist
  - Built beets-2.9.0.tar.gz
Building wheel
  - Building wheel
  - Built beets-2.9.0-py3-none-any.whl
$ tar -vtf dist/beets-2.9.0.tar.gz | head -10
-rw-r--r-- 0/0            1080 1970-01-01 01:00 beets-2.9.0/LICENSE
-rw-r--r-- 0/0            5316 1970-01-01 01:00 beets-2.9.0/README.rst
-rw-r--r-- 0/0            1631 1970-01-01 01:00 beets-2.9.0/beets/__init__.py
-rw-r--r-- 0/0             825 1970-01-01 01:00 beets-2.9.0/beets/__main__.py
-rw-r--r-- 0/0            1540 1970-01-01 01:00 beets-2.9.0/beets/autotag/__init__.py
-rw-r--r-- 0/0           18987 1970-01-01 01:00 beets-2.9.0/beets/autotag/distance.py
-rw-r--r-- 0/0           22492 1970-01-01 01:00 beets-2.9.0/beets/autotag/hooks.py
-rw-r--r-- 0/0           13618 1970-01-01 01:00 beets-2.9.0/beets/autotag/match.py
-rw-r--r-- 0/0            4643 1970-01-01 01:00 beets-2.9.0/beets/config_default.yaml
-rw-r--r-- 0/0             646 1970-01-01 01:00 beets-2.9.0/beets/context.py

The issue was that zipfile.ZipInfo does not support dates before 1980.

[amogus07]

fyn is another option, now that Astral (the company behind uv) was bought by OpenAI. It also has real-world benefits compared to uv like a task runner (which would replace poethepoet I suppose) as well as a shell command.

How about using that instead?

[snejus]

fyn is another option, now that Astral (the company behind uv) was bought by OpenAI. It also has real-world benefits compared to uv like a task runner (which would replace poethepoet I suppose) as well as a shell command.

How about using that instead?

It hasn't been adopted as widely as uv. I've been resisting the migration to uv until now for the exact same reason.

[semohr]

We might want to consider migrating to workspaces and separating beetsplug and beets.

Hm, it may not apply to our use case?

Inspired by the Cargo concept of the same name, a workspace is "a collection of one or more packages, called workspace members, that are managed together."

Workspaces organize large codebases by splitting them into multiple packages with common dependencies. Think: a FastAPI-based web application, alongside a series of libraries that are versioned and maintained as separate Python packages, all in the same Git repository.

I think we could make it work. For example, we could split the core, database, and UI layers into separate packages. That would give us clearer boundaries and enforce a more explicit separation of responsibilities, though it might introduce some additional complexity in terms of packaging and coordination.

[snejus]

I'd be interested to see how would it work and what benefits it may bring - but of course not as part of this PR but rather a separate piece of work that builds on this.

[semohr]

but of course not as part of this PR but rather a separate piece of work that builds on this.

Agreed!