Replace setup.py packaging by Poetry (#5266)

Migrate `beets` package configuration to Poetry which nowadays seems to be the gold standard. I have been using Poetry since 2019 and I have mostly been happy a happy user: it makes local dev setup easy and has the tools I need to maintain python packages day to day, including reliable dependency resolution, versioning and publishing to Pypi. It's a user-friendly tool, so it should make it more straightforward for contributors to setup and navigate the codebase, and ultimately, hopefully facilitate more frequent releases! Since poetry manages local virtual environment, we do not have much need for tox any more. Therefore, it was replaced by a task runner `poethepoet`. Type `poe` in the project directory to see the available commands. - [x] Documentation. (If you've added a new command-line flag, for example, find the appropriate page under `docs/` to describe it.) - [x] Changelog. (Add an entry to `docs/changelog.rst` to the bottom of one of the lists near the top of the document.) - [x] Tests. (Very much encouraged but not strictly required.)
beetbox · Jun 12, 2024 · d7bf28d · d7bf28d
2 parents b4003c3 + 0507f6f
commit d7bf28d
Show file tree

Hide file tree

Showing 38 changed files with 3,446 additions and 616 deletions.
diff --git a/.github/flake8-problem-matcher.json b/.github/flake8-problem-matcher.json
diff --git a/.github/sphinx-problem-matcher.json b/.github/sphinx-problem-matcher.json
@@ -1,18 +1,15 @@
 {
-    "problemMatcher": [
+  "problemMatcher": [
+    {
+      "owner": "sphinx",
+      "pattern": [
         {
-            "owner": "sphinx",
-            "pattern": [
-                {
-                    "regexp": "^Warning, treated as error:$"
-                },
-                {
-                    "regexp": "^(.*?):(\\d+):(.*)$",
-                    "file": 1,
-                    "line": 2,
-                    "message": 3
-                }
-            ]
+          "regexp": "^([^:]+):(\\d+): (WARNING: )?(.+)$",
+          "file": 1,
+          "line": 2,
+          "message": 4
         }
-    ]
+      ]
+    }
+  ]
 }
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -1,104 +1,56 @@
-name: ci
+name: Test
 on:
-  push:
-    branches:
-      - master
   pull_request:
+  push:
     branches:
       - master
+env:
+  PY_COLORS: 1
+
 jobs:
   test:
-    runs-on: ${{ matrix.platform }}
+    name: Run tests
     strategy:
+      fail-fast: false
       matrix:
         platform: [ubuntu-latest, windows-latest]
-        python-version: ["3.8", "3.9", "3.x"]
-
+        python-version: ["3.8", "3.9"]
+    runs-on: ${{ matrix.platform }}
     env:
-      PY_COLORS: 1
-
+      IS_MAIN_PYTHON: ${{ matrix.python-version == '3.8' && matrix.platform == 'ubuntu-latest' }}
     steps:
-      - uses: actions/checkout@v2
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - name: Install Python tools
+        uses: BrandonLWhite/pipx-install-action@v0.1.1
+      - name: Setup Python with poetry caching
+        # poetry cache requires poetry to already be installed, weirdly
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: poetry
 
-      - name: Install base dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install tox sphinx
-
-      - name: Install optional dependencies
-        if: matrix.platform != 'windows-latest'
+      - name: Install PyGobject dependencies on Ubuntu
+        if: matrix.platform == 'ubuntu-latest'
         run: |
           sudo apt update
-          sudo apt install ffmpeg  # For replaygain
-
-      - name: Test older Python versions with tox
-        if: matrix.python-version != '3.x'
-        run: |
-          tox -e py-test
+          sudo apt install ffmpeg gobject-introspection libgirepository1.0-dev
+          poetry install --extras replaygain
 
-      - name: Upload code coverage
-        if: matrix.python-version == '3.8' && matrix.platform == 'ubuntu-latest'
-        run: |
-          pip install codecov || true
-          codecov || true
-
-      - name: Test latest Python version with tox and mypy
-        if: matrix.python-version == '3.x'
-        # continue-on-error is not ideal since it doesn't give a visible
-        # warning, but there doesn't seem to be anything better:
-        # https://github.com/actions/toolkit/issues/399
-        continue-on-error: true
-        run: |
-          tox -vv -e py-mypy
+      - name: Install Python dependencies
+        run: poetry install --only=main,test
 
-  test-docs:
-    runs-on: ubuntu-latest
+      - if: ${{ ! env.IS_MAIN_PYTHON }}
+        name: Test without coverage
+        run: poe test --no-cov
 
-    env:
-      PY_COLORS: 1
-
-    steps:
-      - uses: actions/checkout@v2
-
-      - name: Set up Python 3.x
-        uses: actions/setup-python@v2
+      - if: ${{ env.IS_MAIN_PYTHON }}
+        name: Test with coverage
+        uses: liskin/gh-problem-matcher-wrap@v3
         with:
-          python-version: "3.x"
-
-      - name: Install base dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install tox sphinx
-
-      - name: Add problem matcher
-        run: echo "::add-matcher::.github/sphinx-problem-matcher.json"
-
-      - name: Build and check docs using tox
-        run: tox -e docs
-
-  lint:
-    runs-on: ubuntu-latest
+          linters: pytest
+          run: poe test
 
-    steps:
-      - uses: actions/checkout@v2
-
-      - name: Set up Python 3.x
-        uses: actions/setup-python@v2
-        with:
-          python-version: "3.x"
-
-      - name: Install base dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install tox sphinx
-
-      - name: Add problem matcher
-        run: echo "::add-matcher::.github/flake8-problem-matcher.json"
-
-      - name: Lint with flake8
-        run: tox -e py-lint
+      - if: ${{ env.IS_MAIN_PYTHON }}
+        name: Upload code coverage
+        continue-on-error: true
+        run: poetry run codecov
diff --git a/.github/workflows/formatting_check.yml b/.github/workflows/formatting_check.yml
diff --git a/.github/workflows/integration_test.yaml b/.github/workflows/integration_test.yaml
@@ -2,34 +2,29 @@ name: integration tests
 on:
   workflow_dispatch:
   schedule:
-    - cron: '0 0 * * SUN'  # run every Sunday at midnight
+    - cron: "0 0 * * SUN" # run every Sunday at midnight
 jobs:
   test_integration:
     runs-on: ubuntu-latest
-
-    env:
-      PY_COLORS: 1
-
     steps:
-      - uses: actions/checkout@v2
-
-      - name: Set up latest Python version
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - name: Install Python tools
+        uses: BrandonLWhite/pipx-install-action@v0.1.1
+      - uses: actions/setup-python@v5
         with:
-          python-version: 3.9-dev
+          python-version: 3.8
+          cache: poetry
 
-      - name: Install base dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install tox sphinx
+      - name: Install dependencies
+        run: poetry install
 
-      - name: Test with tox
-        run: |
-          tox -e int
+      - name: Test
+        env:
+          INTEGRATION_TEST: 1
+        run: poe test
 
       - name: Check external links in docs
-        run: |
-          tox -e links
+        run: poe check-docs-links
 
       - name: Notify on failure
         if: ${{ failure() }}

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -0,0 +1,128 @@
+name: Lint check
+run-name: Lint code
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+env:
+  PYTHON_VERSION: 3.8
+
+jobs:
+  changed-files:
+    runs-on: ubuntu-latest
+    name: Get changed files
+    outputs:
+      any_docs_changed: ${{ steps.changed-doc-files.outputs.any_changed }}
+      any_python_changed: ${{ steps.changed-python-files.outputs.any_changed }}
+      changed_doc_files: ${{ steps.changed-doc-files.outputs.all_changed_files }}
+      changed_python_files: ${{ steps.changed-python-files.outputs.all_changed_files }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Get changed docs files
+        id: changed-doc-files
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            docs/**
+      - name: Get changed python files
+        id: changed-python-files
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            **.py
+
+  format:
+    if: needs.changed-files.outputs.any_python_changed == 'true'
+    runs-on: ubuntu-latest
+    name: Check formatting
+    needs: changed-files
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Python tools
+        uses: BrandonLWhite/pipx-install-action@v0.1.1
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: poetry
+
+      - name: Install dependencies
+        run: poetry install --only=format
+
+      - name: Check code formatting
+        # the job output will contain colored diffs with what needs adjusting
+        run: poe check-format
+
+  lint:
+    if: needs.changed-files.outputs.any_python_changed == 'true'
+    runs-on: ubuntu-latest
+    name: Check linting
+    needs: changed-files
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Python tools
+        uses: BrandonLWhite/pipx-install-action@v0.1.1
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: poetry
+
+      - name: Install dependencies
+        run: poetry install --only=lint
+
+      - name: Lint code
+        uses: liskin/gh-problem-matcher-wrap@v3
+        with:
+          linters: flake8
+          run: poe lint ${{ needs.changed-files.outputs.changed_python_files }}
+
+  mypy:
+    if: needs.changed-files.outputs.any_python_changed == 'true'
+    runs-on: ubuntu-latest
+    name: Check types with mypy
+    needs: changed-files
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Python tools
+        uses: BrandonLWhite/pipx-install-action@v0.1.1
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: poetry
+
+      - name: Install dependencies
+        run: poetry install --only=typing
+
+      - name: Type check code
+        uses: liskin/gh-problem-matcher-wrap@v3
+        continue-on-error: true
+        with:
+          linters: mypy
+          run: poe check-types --show-column-numbers --no-error-summary ${{ needs.changed-files.outputs.changed_python_files }}
+
+  docs:
+    if: needs.changed-files.outputs.any_docs_changed == 'true'
+    runs-on: ubuntu-latest
+    name: Check docs
+    needs: changed-files
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Python tools
+        uses: BrandonLWhite/pipx-install-action@v0.1.1
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: poetry
+
+      - name: Install dependencies
+        run: poetry install --only=docs
+
+      - name: Add Sphinx problem matcher
+        run: echo "::add-matcher::.github/sphinx-problem-matcher.json"
+
+      - name: Build docs
+        run: |
+          poe docs |& tee /tmp/output
+          # fail the job if there are issues
+          grep -q " WARNING:" /tmp/output && exit 1 || exit 0
diff --git a/.gitignore b/.gitignore
@@ -74,6 +74,7 @@ target/
 .env
 
 # virtualenv
+env/
 venv/
 .venv/
 ENV/