Make tool dependencies more manageable

.github/workflows/test.yaml

@@ -21,12 +21,7 @@ jobs:
         id: "setup-python"
         uses: "actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c" # v5.0.0
         with:
-          python-version: "3.11"
-          cache: "pip"
-          cache-dependency-path: |
-            pyproject.toml
-            tox.ini
-            .github/workflows/test.yaml
+          python-version: "3.12"
 
       - name: "Build the project"
         run: "pip wheel ."
@@ -105,14 +100,6 @@ jobs:
         with:
           python-version: "${{ matrix.run.pythons }}"
           allow-prereleases: true
-          # Cache packages that pip downloads.
-          # This does not cache the installed files.
-          cache: "pip"
-          cache-dependency-path: |
-            .github/workflows/test.yaml
-            pyproject.toml
-            tox.ini
-            week-number.txt
 
       - name: "Restore cache"
         id: "restore-cache"
@@ -121,7 +108,7 @@ jobs:
           path: |
             .tox/
             .venv/
-          key: "test-os=${{ matrix.run.os.id }}-hash=${{ hashFiles('.github/workflows/test.yaml', 'pyproject.toml', 'tox.ini', 'week-number.txt') }}"
+          key: "test-os=${{ matrix.run.os.id }}-hash=${{ hashFiles('.github/workflows/test.yaml', 'pyproject.toml', 'tox.ini', 'week-number.txt', 'requirements/*/*.txt') }}"
 
       - name: "Identify venv path"
         shell: "bash"
@@ -164,21 +151,14 @@ jobs:
         id: "setup-python"
         uses: "actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c" # v5.0.0
         with:
-          python-version: "3.11"
-          # Cache packages that pip downloads.
-          # This does not cache the installed files.
-          cache: "pip"
-          cache-dependency-path: |
-            .github/workflows/test.yaml
-            pyproject.toml
-            week-number.txt
+          python-version: "3.12"
 
       - name: "Restore cache"
         id: "restore-cache"
         uses: "actions/cache@ab5e6d0c87105b4c9c2047343972218f562e4319" # v4.0.1
         with:
           path: ".venv/"
-          key: "coverage-hash=${{ hashFiles('.github/workflows/test.yaml', 'pyproject.toml', 'week-number.txt') }}"
+          key: "coverage-hash=${{ hashFiles('.github/workflows/test.yaml', 'pyproject.toml', 'week-number.txt', 'requirements/*/*.txt') }}"
 
       - name: "Create a virtual environment"
         if: "steps.restore-cache.outputs.cache-hit == false"
@@ -214,15 +194,7 @@ jobs:
         id: "setup-python"
         uses: "actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c" # v5.0.0
         with:
-          python-version: "3.11"
-          # Cache packages that pip downloads.
-          # This does not cache the installed files.
-          cache: "pip"
-          cache-dependency-path: |
-            .github/workflows/test.yaml
-            pyproject.toml
-            tox.ini
-            week-number.txt
+          python-version: "3.12"
 
       - name: "Restore cache"
         id: "restore-cache"
@@ -232,7 +204,7 @@ jobs:
             .mypy_cache/
             .tox/
             .venv/
-          key: "lint-hash=${{ hashFiles('.github/workflows/test.yaml', 'pyproject.toml', 'tox.ini', 'week-number.txt') }}"
+          key: "lint-hash=${{ hashFiles('.github/workflows/test.yaml', 'pyproject.toml', 'tox.ini', 'week-number.txt', 'requirements/*/*.txt') }}"
 
       - name: "Create a virtual environment"
         if: "steps.restore-cache.outputs.cache-hit == false"

.gitignore

@@ -10,4 +10,4 @@ htmlcov/
 .coverage*
 .idea/
 .venv/
-poetry.lock
+/poetry.lock

.pre-commit-config.yaml

@@ -20,38 +20,38 @@ repos:
       - id: "trailing-whitespace"
 
   - repo: "https://github.com/asottile/pyupgrade"
-    rev: "v3.15.0"
+    rev: "v3.15.2"
     hooks:
       - id: "pyupgrade"
         name: "Enforce Python 3.8+ idioms"
         args:
           - "--py38-plus"
 
   - repo: "https://github.com/psf/black-pre-commit-mirror"
-    rev: "23.11.0"
+    rev: "24.3.0"
     hooks:
       - id: "black"
         language_version: "python3.8"
 
   - repo: "https://github.com/pycqa/isort"
-    rev: "5.12.0"
+    rev: "5.13.2"
     hooks:
       - id: "isort"
 
   - repo: "https://github.com/pycqa/flake8"
-    rev: "6.1.0"
+    rev: "7.0.0"
     hooks:
       - id: "flake8"
         additional_dependencies:
-          - "flake8-bugbear==23.9.16"
+          - "flake8-bugbear==24.2.6"
 
   - repo: "https://github.com/editorconfig-checker/editorconfig-checker.python"
     rev: "2.7.3"
     hooks:
       - id: "editorconfig-checker"
 
   - repo: "https://github.com/python-jsonschema/check-jsonschema"
-    rev: "0.27.2"
+    rev: "0.28.0"
     hooks:
       - id: "check-dependabot"
       - id: "check-github-workflows"

.readthedocs.yaml

@@ -5,11 +5,11 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "3.11"
+    python: "3.12"
 
 python:
   install:
-    - requirements: "docs/requirements.txt"
+    - requirements: "requirements/docs/requirements.txt"
 
 sphinx:
   configuration: "docs/conf.py"

README.rst

@@ -96,7 +96,7 @@ To set up a development environment, follow these steps at a command line:
 
     # Install dependencies.
     python -m pip install -U pip setuptools wheel
-    python -m pip install poetry pre-commit
+    python -m pip install poetry pre-commit tox scriv
     poetry install --all-extras
 
     # Enable pre-commit.

changelog.d/20240328_075816_kurtmckee_manageable_dependencies.rst

@@ -0,0 +1,5 @@
+Development
+-----------
+
+*   Move tool dependencies into separate ``requirements.txt`` files.
+*   Add a tox label, ``update``, so it's easy to update tool dependencies.

pyproject.toml

@@ -27,12 +27,6 @@ http = ["requests"]
 lxml = ["lxml"]
 
 
-[tool.poetry.group.dev.dependencies]
-pytest = "^7.2.0"
-scriv = {extras = ["toml"], version = "^1.0.0"}
-tox = "^4.3.5"
-
-
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"

requirements/README.rst

@@ -0,0 +1,51 @@
+``requirements/``
+#################
+
+This directory contains the files that manage dependencies for the project.
+
+At the time of writing, Poetry supports discrete dependency groups
+but always resolves dependencies coherently across all groups.
+However, in some cases, dependencies do not need to be coherently resolved;
+for example, mypy's dependencies do not need to be resolved
+together with Sphinx's dependencies.
+
+Each subdirectory in this directory contains a ``pyproject.toml`` file
+with purpose-specific dependencies listed.
+
+
+How it's used
+=============
+
+Tox is configured to use the exported ``requirements.txt`` files as needed.
+In addition, Read the Docs is configured to use ``docs/requirements.txt``.
+This helps ensure reproducible testing, linting, and documentation builds.
+
+
+How it's updated
+================
+
+A tox label, ``update``, ensures that dependencies can be easily updated,
+and that ``requirements.txt`` files are consistently re-exported.
+
+This can be invoked by running:
+
+..  code-block::
+
+    tox run -m update
+
+
+How to add dependencies
+=======================
+
+New dependencies can be added to a given subdirectory's ``pyproject.toml``
+by either manually modifying the file, or by running a command like:
+
+..  code-block::
+
+    poetry add --lock --directory "requirements/$DIR" $DEPENDENCY_NAME
+
+Either way, the dependencies must be re-exported:
+
+..  code-block::
+
+    tox run -m update