feat: add noxfile checks (#659)

* feat: add noxfile checks

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix: some smaller fixes

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>

* refactor: rename

---------

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
Signed-off-by: Henry Schreiner <henryfs@princeton.edu>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: henryiii

.pre-commit-config.yaml

@@ -46,12 +46,13 @@ repos:
     rev: "v1.18.2"
     hooks:
       - id: mypy
-        files: "(src|tests)"
+        files: "(src|tests|noxfile.py)"
         args: []
         additional_dependencies:
           - click
           - markdown-it-py
           - pytest
+          - nox
           - orjson
           - repo-review>=0.10.6
           - rich

README.md

@@ -358,6 +358,14 @@ for family, grp in itertools.groupby(collected.checks.items(), key=lambda x: x[1
 - [`MY105`](https://learn.scientific-python.org/development/guides/style#MY105): MyPy enables redundant-expr
 - [`MY106`](https://learn.scientific-python.org/development/guides/style#MY106): MyPy enables truthy-bool
 
+### Nox
+- [`NOX101`](https://learn.scientific-python.org/development/guides/tasks#NOX101): Sets minimum nox version
+- [`NOX102`](https://learn.scientific-python.org/development/guides/tasks#NOX102): Sets venv backend
+- [`NOX103`](https://learn.scientific-python.org/development/guides/tasks#NOX103): Set default per session instead of session list
+- [`NOX201`](https://learn.scientific-python.org/development/guides/tasks#NOX201): Set a script block with dependencies in your noxfile
+- [`NOX202`](https://learn.scientific-python.org/development/guides/tasks#NOX202): Has a shebang line
+- [`NOX203`](https://learn.scientific-python.org/development/guides/tasks#NOX203): Provide a main block to run nox
+
 ### Pre-commit
 - [`PC100`](https://learn.scientific-python.org/development/guides/style#PC100): Has pre-commit-hooks
 - [`PC110`](https://learn.scientific-python.org/development/guides/style#PC110): Uses black or ruff-format

docs/pages/guides/tasks.md

@@ -260,6 +260,9 @@ This supports setting up a quick server as well, run like this:
 $ nox -s docs -- --serve
 ```
 
+Notice that we set `default=False` so that docs are not built every time nox is
+run without arguments. {% rr NOX103 %}
+
 #### Build (pure Python)
 
 For pure Python packages, this could be useful:
@@ -304,7 +307,8 @@ def build(session: nox.Session) -> None:
 
 The [uv](https://github.com/astral-sh/uv) project is a Rust reimplementation of
 pip, pip-tools, and venv that is very, very fast. You can tell nox to use `uv`
-if it is on your system by adding the following to your `noxfile.py`:
+if it is on your system by adding the following to your `noxfile.py`
+{% rr NOX102 %}:
 
 ```python
 nox.needs_version = ">=2024.3.2"
@@ -322,7 +326,39 @@ Check your jobs with `uv`; most things do not need to change. The main
 difference is `uv` doesn't install `pip` unless you ask it to. If you want to
 interact with uv, nox might be getting uv from it's environment instead of the
 system environment, so you can install `uv` if `shutil.which("uv")` returns
-`None`.
+`None`. You should also set a minimum version of nox. {% rr NOX101 %}
+
+### Running without nox or requiring dependencies
+
+Nox also allows you to use the script block, both for running with runners (like
+`uv run` and `pipx run`), and for specifying dependencies to install or a
+minimum nox version; nox will read this block and run itself from a venv with
+those requirements installed if they are not met.
+
+```python
+#!/usr/bin/env -S uv run --script
+
+# /// script
+# dependencies = ["nox>=2025.10.16"]
+# ///
+
+import nox
+
+nox.needs_version = ">=2025.10.16"
+
+if __name__ == "__main__":
+    nox.main()
+```
+
+The script block then specifies that nox is required {% rr NOX201 %}. If you
+want other dependencies here, those will also be installed before the file is
+run. Older versions of nox still need the `nox.needs_version` line to keep nice
+error messages.
+
+The first line is a shebang line {% rr NOX202 %}, which allows this file to be
+run directly if it is made executable. You can put any runner here; uv is shown.
+You also need a main block {% rr NOX203 %} to allow nox to be run when this file
+is executed directly.
 
 ### Examples
 

noxfile.py

@@ -1,3 +1,9 @@
+#!/usr/bin/env -S uv run --script
+
+# /// script
+# dependencies = ["nox>=2025.2.9"]
+# ///
+
 """
 Nox runner for cookie & sp-repo-review.
 
@@ -7,7 +13,8 @@
 from __future__ import annotations
 
 import difflib
-import email.message
+import email.parser
+import email.policy
 import functools
 import json
 import os
@@ -26,7 +33,6 @@
 import nox
 
 nox.needs_version = ">=2025.2.9"
-nox.options.sessions = ["rr_lint", "rr_tests", "rr_pylint", "readme"]
 nox.options.default_venv_backend = "uv|virtualenv"
 
 
@@ -58,7 +64,7 @@ def get_expected_version(backend: str, vcs: bool) -> str:
     return "0.2.3" if vcs and backend not in {"maturin", "mesonpy", "uv"} else "0.1.0"
 
 
-def make_copier(session: nox.Session, backend: str, vcs: bool) -> None:
+def make_copier(session: nox.Session, backend: str, vcs: bool) -> Path:
     package_dir = Path(f"copy-{backend}")
     if package_dir.exists():
         rmtree_ro(package_dir)
@@ -85,7 +91,7 @@ def make_copier(session: nox.Session, backend: str, vcs: bool) -> None:
     return package_dir
 
 
-def make_cookie(session: nox.Session, backend: str, vcs: bool) -> None:
+def make_cookie(session: nox.Session, backend: str, vcs: bool) -> Path:
     package_dir = Path(f"cookie-{backend}")
     if package_dir.exists():
         rmtree_ro(package_dir)
@@ -106,7 +112,7 @@ def make_cookie(session: nox.Session, backend: str, vcs: bool) -> None:
     return package_dir
 
 
-def make_cruft(session: nox.Session, backend: str, vcs: bool) -> None:
+def make_cruft(session: nox.Session, backend: str, vcs: bool) -> Path:
     package_dir = Path(f"cruft-{backend}")
     if package_dir.exists():
         rmtree_ro(package_dir)
@@ -156,7 +162,7 @@ def init_git(session: nox.Session, package_dir: Path) -> None:
 IGNORE_FILES = {"__pycache__", ".git", ".copier-answers.yml", ".cruft.json"}
 
 
-def valid_path(path: Path):
+def valid_path(path: Path) -> bool:
     return path.is_file() and not IGNORE_FILES & set(path.parts)
 
 
@@ -233,7 +239,9 @@ def tests(session: nox.Session, backend: str, vcs: bool) -> None:
         "-c",
         f'import importlib.metadata as m; print(m.version("{name}"))',
         silent=True,
-    ).strip()
+    )
+    assert version
+    version = version.strip()
     expected_version = get_expected_version(backend, vcs)
     assert version == expected_version, f"{version=} != {expected_version=}"
 
@@ -287,7 +295,9 @@ def dist(session: nox.Session, backend: str, vcs: bool) -> None:
             (metadata_path,) = (
                 n for n in names if n.endswith("PKG-INFO") and "egg-info" not in n
             )
-            with tf.extractfile(metadata_path) as mfile:
+            efile = tf.extractfile(metadata_path)
+            assert efile
+            with efile as mfile:
                 info = mfile.read().decode("utf-8")
                 if "License-Expression: BSD-3-Clause" not in info:
                     msg = "License expression not found in METADATA"
@@ -302,7 +312,11 @@ def dist(session: nox.Session, backend: str, vcs: bool) -> None:
         metadata_path = next(iter(n for n in names if n.endswith("METADATA")))
         with zf.open(metadata_path) as mfile:
             txt = mfile.read()
-    license_fields = email.message.EmailMessage(txt).get_all("License", [])
+    license_fields = (
+        email.parser.BytesParser(policy=email.policy.default)
+        .parsebytes(txt)
+        .get_all("License", [])
+    )
     if license_fields:
         msg = f"Should not have anything in the License slot, got {license_fields}"
         session.error(msg)
@@ -403,14 +417,16 @@ def pc_bump(session: nox.Session) -> None:
 
         for proj, (old_version, space) in old_versions.items():
             if proj not in versions:
-                versions[proj] = session.run(
+                versions_proj = session.run(
                     "lastversion",
                     "--at=github",
                     "--format=tag",
                     "--exclude=~alpha|beta|rc",
                     proj,
                     silent=True,
-                ).strip()
+                )
+                assert versions_proj
+                versions[proj] = versions_proj.strip()
             new_version = versions[proj]
 
             after = PC_REPL_LINE.format(proj, new_version, space, '"')
@@ -449,7 +465,7 @@ def get_latest_version_tag(repo: str, old_version: str) -> dict[str, Any] | None
         and x["name"].startswith("v") == old_version.startswith("v")
     ]
     if tags:
-        return tags[0]
+        return tags[0]  # type: ignore[no-any-return]
     return None
 
 
@@ -548,3 +564,7 @@ def rr_build(session: nox.Session) -> None:
 
     session.install("build")
     session.run("python", "-m", "build")
+
+
+if __name__ == "__main__":
+    nox.main()

pyproject.toml

@@ -66,6 +66,7 @@ mypy = "sp_repo_review.checks.mypy:repo_review_checks"
 github = "sp_repo_review.checks.github:repo_review_checks"
 readthedocs = "sp_repo_review.checks.readthedocs:repo_review_checks"
 setupcfg = "sp_repo_review.checks.setupcfg:repo_review_checks"
+noxfile = "sp_repo_review.checks.noxfile:repo_review_checks"
 
 [project.entry-points."repo_review.fixtures"]
 workflows = "sp_repo_review.checks.github:workflows"
@@ -74,6 +75,7 @@ precommit = "sp_repo_review.checks.precommit:precommit"
 readthedocs = "sp_repo_review.checks.readthedocs:readthedocs"
 ruff = "sp_repo_review.checks.ruff:ruff"
 setupcfg = "sp_repo_review.checks.setupcfg:setupcfg"
+noxfile = "sp_repo_review.checks.noxfile:noxfile"
 
 [project.entry-points."repo_review.families"]
 scikit-hep = "sp_repo_review.families:get_families"