refactor(template): switch project automation from mise tasks to nox sessions

liblaf · liblaf · commit cb4954050951 · 2026-03-22T21:37:26.000+08:00
Add a generated noxfile and update test and benchmark workflows to discover and run nox sessions through uv, so template projects use one consistent automation entrypoint locally and in CI. Remove redundant test and bench shell tasks and inline pyright config, while updating ignores and install locking to support the new environment layout more reliably.
diff --git a/.config/cspell.config.yaml b/.config/cspell.config.yaml
@@ -7,13 +7,10 @@ cache:
 caseSensitive: false
 enableGlobDot: true
 ignorePaths:
-  - .cspell.*
   - .git/
-  - "*-lock.*"
-  - "*.lock"
   - cspell.*
-  - go.sum
 ignoreRandomStrings: true
+maxFileSize: 500KB
 useGitignore: true
 words:
   - arithmatex
@@ -27,11 +24,13 @@ words:
   - getattr
   - hynek
   - inlinehilite
+  - kwargs
   - libc
   - liblaf
   - mathjax
   - mkdocs
   - mkdocstrings
+  - noxfile
   - numprocesses
   - numpy
   - pycache
@@ -45,13 +44,11 @@ words:
   - pyproject
   - pyrightconfig
   - pytest
-  - pyvenv
   - pyvista
   - sdist
   - strftime
   - tombi
   - trimesh
-  - unshallow
   - uuidgen
   - venv
   - virtualenv
diff --git a/copier.yaml b/copier.yaml
@@ -45,6 +45,7 @@ _skip_if_exists:
   - docs/.nav.yml
   - docs/README.md
   - mkdocs.yaml
+  - noxfile.py
   - pyproject.toml
   - README.md
   - src/
diff --git a/template/.config/copier/mise-tasks/bench.sh b/template/.config/copier/mise-tasks/bench.sh
diff --git a/template/.config/copier/mise-tasks/install.sh b/template/.config/copier/mise-tasks/install.sh
@@ -9,14 +9,20 @@ function has() {
   type "$@" &> /dev/null
 }
 
+function lock() {
+  local -r id="$(basename -- "$PWD")"
+  mkdir --parents --verbose '/tmp/mise-flock'
+  flock --nonblock "/tmp/mise-flock/$id.lock" "$@"
+}
+
 if [[ -f 'pixi.lock' ]]; then
   pixi='pixi'
   if has pixi-wrapper.sh; then pixi='pixi-wrapper.sh'; fi
-  "$pixi" install "$@"
+  lock "$pixi" install "$@"
 fi
 
 if [[ -f 'uv.lock' ]]; then
   uv_sync=(uv sync)
   if has uv-sync.sh; then uv_sync=(uv-sync.sh); fi
-  "${uv_sync[@]}" "$@"
+  lock "${uv_sync[@]}" "$@"
 fi
diff --git a/template/.config/copier/mise-tasks/test.sh b/template/.config/copier/mise-tasks/test.sh
diff --git a/template/.config/copier/mise-tasks/upgrade.sh b/template/.config/copier/mise-tasks/upgrade.sh
@@ -10,14 +10,20 @@ function has() {
   type "$@" &> /dev/null
 }
 
+function lock() {
+  local -r name="$(basename -- "$PWD")"
+  mkdir --parents --verbose '/tmp/mise-flock'
+  flock --nonblock "/tmp/mise-flock/$name.lock" "$@"
+}
+
 if [[ -f 'pixi.lock' ]]; then
   pixi='pixi'
   if has pixi-wrapper.sh; then pixi='pixi-wrapper.sh'; fi
-  "$pixi" upgrade "$@"
+  lock "$pixi" upgrade "$@"
 fi
 
 if [[ -f 'uv.lock' ]]; then
   uv_sync=(uv sync)
   if has uv-sync.sh; then uv_sync=(uv-sync.sh); fi
-  "${uv_sync[@]}" --upgrade "$@"
+  lock "${uv_sync[@]}" --upgrade "$@"
 fi
diff --git a/template/.config/linters/pyrightconfig.json b/template/.config/linters/pyrightconfig.json
diff --git a/template/.github/workflows/bench.yaml b/template/.github/workflows/bench.yaml
@@ -18,49 +18,43 @@ jobs:
     name: Collect
     runs-on: ubuntu-latest
     outputs:
-      has-benches: ${{ steps.collect.outputs.has-benches }}
-      python-versions: ${{ steps.inspect.outputs.supported_python_classifiers_json_array }}
+      sessions: ${{ steps.collect.outputs.sessions }}
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-      - id: inspect
-        name: Build and Inspect a Python Package
-        uses: hynek/build-and-inspect-python-package@v2
-      - name: Setup Python
-        uses: liblaf/actions/setup-python@v1
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          activate-environment: true
+      - name: Install Dependencies
+        run: uv sync --active --frozen --all-packages
       - id: collect
         name: Collect
         run: |-
-          if pytest -m 'benchmark' --collect-only; then
-            echo 'has-tests=true' >> "$GITHUB_OUTPUT"
-          else
-            code="$?"
-            if (("$code" == 5)); then
-              echo 'has-tests=false' >> "$GITHUB_OUTPUT"
-            else
-              exit "$code"
-            fi
-          fi
+          echo "sessions=$(
+            nox --list-sessions --json --tags 'bench' |
+              jq --compact-output '[.[].session]'
+          )" >> "$GITHUB_OUTPUT"
 
   # CodSpeedHQ does not support the same benchmark multiple times
   # so we don't run on multiple python versions here.
   bench:
     name: Bench
     needs:
       - collect
-    if: needs.collect.outputs.has-benches == 'true'
+    if: needs.collect.outputs.sessions != '[]'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-      - name: Setup Python
-        uses: liblaf/actions/setup-python@v1
-      - name: Install Mise
-        uses: jdx/mise-action@v4
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          activate-environment: true
+      - name: Install Dependencies
+        run: uv sync --active --frozen --all-packages
       - name: Bench
         uses: CodSpeedHQ/action@v4
         with:
-          run: mise run bench
+          run: nox --tags 'bench'
           mode: instrumentation
-        env:
-          FORCE_COLOR: 1
diff --git a/template/.github/workflows/docs.yaml b/template/.github/workflows/docs.yaml
@@ -27,8 +27,12 @@ jobs:
         uses: actions/configure-pages@v5
       - name: Set Environment Variables
         run: echo 'SITE_URL=${{ steps.config.outputs.base_url }}' >> "$GITHUB_ENV"
-      - name: Setup Python
-        uses: liblaf/actions/setup-python@v1
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          activate-environment: true
+      - name: Install Dependencies
+        run: uv sync --active --frozen --all-packages
       - if: hashFiles('docs/scripts/pre-build.sh') != ''
         name: Pre-Build
         run: docs/scripts/pre-build.sh
diff --git a/template/.github/workflows/test.yaml b/template/.github/workflows/test.yaml
@@ -20,53 +20,45 @@ jobs:
     name: Collect
     runs-on: ubuntu-latest
     outputs:
-      has-tests: ${{ steps.collect.outputs.has-tests }}
-      python-versions: ${{ steps.inspect.outputs.supported_python_classifiers_json_array }}
+      sessions: ${{ steps.collect.outputs.sessions }}
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-      - id: inspect
-        name: Build and Inspect a Python Package
-        uses: hynek/build-and-inspect-python-package@v2
-      - name: Setup Python
-        uses: liblaf/actions/setup-python@v1
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          activate-environment: true
+      - name: Install Dependencies
+        run: uv sync --active --frozen --all-packages
       - id: collect
         name: Collect
         run: |-
-          if pytest --collect-only; then
-            echo 'has-tests=true' >> "$GITHUB_OUTPUT"
-          else
-            code="$?"
-            if (("$code" == 5)); then
-              echo 'has-tests=false' >> "$GITHUB_OUTPUT"
-            else
-              exit "$code"
-            fi
-          fi
+          echo "sessions=$(
+            nox --list-sessions --json --tags 'test' |
+              jq --compact-output '[.[].session]'
+          )" >> "$GITHUB_OUTPUT"
 
   test:
     name: Test
     permissions:
       id-token: write
     needs:
       - collect
-    if: needs.collect.outputs.has-tests == 'true'
+    if: needs.collect.outputs.sessions != '[]'
     runs-on: ubuntu-latest
-    env:
-      EAGER_IMPORT: true # ref: <https://github.com/scientific-python/lazy-loader?tab=readme-ov-file#early-failure>
     steps:
       - name: Checkout
         uses: actions/checkout@v6
         with:
           fetch-depth: 0 # I don't know why, but it is present in Codecov's documentation
-      - name: Setup Python
-        uses: liblaf/actions/setup-python@v1
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install Mise
-        uses: jdx/mise-action@v4
+          activate-environment: true
+      - name: Install Dependencies
+        run: uv sync --active --frozen --all-packages
       - name: Test
-        run: mise run test
+        run: nox --session '${{ matrix.session }}'
       - if: success() || failure()
         name: Upload Coverage
         uses: codecov/codecov-action@v5
@@ -81,5 +73,5 @@ jobs:
           use_oidc: true
     strategy:
       matrix:
-        python-version: ${{ fromJson(needs.collect.outputs.python-versions) }}
+        session: ${{ fromJson(needs.collect.outputs.sessions) }}
       fail-fast: false
diff --git a/template/.gitignore b/template/.gitignore
@@ -11,6 +11,7 @@ __pycache__/
 dist/
 
 # Unit test / coverage reports
+.nox/
 .cache/
 .coverage
 .coverage.*
@@ -24,7 +25,7 @@ dist/
 .venv/
 
 # mkdocs documentation
-site/
+/site/
 
 # Ruff stuff:
 .ruff_cache/
diff --git a/template/.vscode/settings.json b/template/.vscode/settings.json
@@ -3,9 +3,10 @@
     "**/__pycache__/": true,
     "**/.cache/": true,
     "**/.codspeed/": true,
-    "**/.coverage": true,
     "**/.coverage.*": true,
+    "**/.coverage": true,
     "**/.hypothesis/": true,
+    "**/.nox/": true,
     "**/.pixi/": true,
     "**/.pytest_cache/": true,
     "**/.ruff_cache/": true,
diff --git a/template/__builtins__.pyi b/template/__builtins__.pyi
@@ -1,6 +1,7 @@
 # This file is @generated by <https://github.com/liblaf/copier-python>.
 # DO NOT EDIT!
 
+# ref: <https://github.com/astral-sh/ruff/pull/22021>
 # ref: <https://github.com/microsoft/pyright/blob/main/docs/builtins.md>
 
 from typing import overload, type_check_only
diff --git a/template/noxfile.py b/template/noxfile.py
@@ -0,0 +1,31 @@
+from typing import Any
+
+import nox
+import nox_uv
+from liblaf import nox_recipes as recipes
+from liblaf.nox_recipes import Resolution
+
+nox.options.default_venv_backend = "uv"
+nox.options.reuse_existing_virtualenvs = True
+nox.options.tags = ["test"]
+PYPROJECT: dict[str, Any] = nox.project.load_toml("pyproject.toml")
+PYTHON_VERSIONS: list[str] = nox.project.python_versions(PYPROJECT)
+
+
+@nox_uv.session(reuse_venv=True, tags=["bench"], uv_groups=["test"], uv_quiet=True)
+def bench(s: nox.Session) -> None:
+    recipes.pytest_bench(s, suppress_no_test_exit_code=True)
+
+
+@nox.session(python=PYTHON_VERSIONS, reuse_venv=True, tags=["test"])
+@nox.parametrize(
+    "resolution",
+    [
+        nox.param(Resolution.HIGHEST, id="highest"),
+        # nox.param(Resolution.LOWEST, id="lowest"),
+        nox.param(Resolution.LOWEST_DIRECT, id="lowest-direct"),
+    ],
+)
+def test(s: nox.Session, resolution: Resolution | None) -> None:
+    recipes.setup_uv(s, groups=["test"], resolution=resolution)
+    recipes.pytest(s, suppress_no_test_exit_code=True)
diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja
