Update to Python 3.15, other maintenance, and allocator stuff (#157)

* Support Python 3.15; fix allocator mismatches with NumPy >= 2.5

NumPy 2.5 allocates with PyMem_RawMalloc, but frees OWNDATA arrays that
have no memory handler with libc free(). The two differ on free-threaded
3.15 (mimalloc) and under PYTHONMALLOC=debug, so matrix.serialize and
binread aborted there.

- claim_buffer attaches NumPy's default memory handler (setup.py sets
  NPY_TARGET_VERSION to 1.22 to expose it)
- binread allocates with GraphBLAS's own allocator instead of libc malloc
- add utils.can_unclaim_buffer to check before handing an array's buffer
  to GraphBLAS; document unclaim_buffer
- initialize() raises if GraphBLAS fails to initialize
- add tests/test_memory.py (runs in a subprocess with PYTHONMALLOC=debug)

Python 3.15 and maintenance:
- add 3.15 classifier and Black target; test 3.15 rc in CI via the
  conda-forge python_rc channel, ranked below conda-forge
- cibuildwheel v3.4 -> v4.2 (builds cp315 and cp315t wheels)
- update all actions and pin them to commit SHAs; group Dependabot
  updates with a 7-day cooldown
- least-privilege workflow permissions, cancel superseded PR runs, no
  ${{ }} expansion inside run: scripts; `bash -el` so a failing command
  in a multi-command test step fails the step
- stricter pytest config: warnings are errors, strict markers and config
- update pre-commit hooks; add actionlint, zizmor and pysentry
- rename CLAUDE.md to AGENTS.md and update it
- publish via PyPI Trusted Publishing (environments pypi and test-pypi)
  instead of an API token

* Pair NumPy memory handlers with GraphBLAS arenas; add give_buffer

GraphBLAS (>= 10.4) frees a buffer with its arena's allocator, and NumPy
frees an array's data with the array's memory handler. A buffer that
crosses between them needs both to agree, or the wrong free aborts
(free-threaded 3.15, PYTHONMALLOC=debug) or corrupts memory.

- claim_buffer and claim_buffer_2d attach the handler for the buffer's
  arena (NumPy's default if the arena uses NumPy's allocator, else one
  that calls the arena's functions); new optional `arena` argument
- add give_buffer, a context manager that hands an array (or a copy)
  to GraphBLAS and commits only if GraphBLAS took it, and empty(),
  which allocates arrays GraphBLAS can always own
- can_unclaim_buffer checks the handler matches the arena;
  unclaim_buffer raises if the array can't be owned
- serialize_* name the result's arena; binread reads into the new
  matrix's arena and packs with give_buffer, which also fixes iso
  matrices packed with a full-size Ax_size; binwrite restores the
  matrix if writing fails
- tests fail when NumPy frees an array that has no handler; test_memory
  covers both memory managers and a libc arena (explicit, global, and
  Context); doctests run for every api module; wheel tests use -W error
- drop stale flake8 ignores; ignore create_headers.py's output

Author: eriknw

.flake8

@@ -5,7 +5,5 @@ extend-ignore =
     E203,
 # E203 whitespace before ':' (to be compatible with black)
 per-file-ignores =
-    suitesparse_graphblas/io/binary.py:C408,
-    suitesparse_graphblas/tests/test_io.py:E721,
 # The api package re-exports its submodules for `from suitesparse_graphblas import api`
     suitesparse_graphblas/api/__init__.py:F401,

.github/dependabot.yml

@@ -4,3 +4,12 @@ updates:
     directory: '/'
     schedule:
       interval: 'weekly'
+    # Wait a week after a release before proposing it, so a compromised or
+    # broken release has time to be noticed and yanked.
+    cooldown:
+      default-days: 7
+    # One PR per week for all action bumps instead of one PR per action.
+    groups:
+      github-actions:
+        patterns:
+          - '*'

.github/workflows/docs.yml

@@ -6,8 +6,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  pages: write
-  id-token: write
+  contents: read
 
 concurrency:
   group: pages
@@ -17,33 +16,38 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Build package in Docker
         run: |
           docker build --target psg \
-            --build-arg SUITESPARSE=v$(cat GB_VERSION.txt) \
+            --build-arg SUITESPARSE="v$(cat GB_VERSION.txt)" \
             --build-arg VERSION=99.0.0.0 \
             --build-arg COMPACT=1 \
             -t psg-docs .
 
       - name: Generate docs with pdoc
         run: |
-          docker run --rm -v ${{ github.workspace }}/site:/out psg-docs \
+          docker run --rm -v "$GITHUB_WORKSPACE/site:/out" psg-docs \
             bash -c "pip install --break-system-packages -q pdoc && \
               pdoc --output-directory /out --no-show-source --docformat numpy \
               suitesparse_graphblas.api"
 
-      - uses: actions/upload-pages-artifact@v3
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: site/
 
   deploy:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      pages: write  # to deploy to GitHub Pages
+      id-token: write  # to prove the deployment comes from this workflow
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - uses: actions/deploy-pages@v4
+      - uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
         id: deployment

.github/workflows/lint.yml

@@ -9,16 +9,21 @@ on:
 permissions:
   contents: read
 
+# Cancel superseded runs of a PR; never cancel branch pushes.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   pre-commit:
     name: pre-commit-hooks
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.11"
-      - uses: pre-commit/action@v3.0.1
+      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1

.github/workflows/test.yml

@@ -5,12 +5,22 @@ on:
     branches: [ main ]
   pull_request:
 
+permissions:
+  contents: read
+
+# Cancel superseded runs of a PR; never cancel runs on main.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ${{ matrix.os }}
     defaults:
       run:
-        shell: bash -l {0}
+        # -e: a custom shell gets no errexit, so without it a multi-command step
+        # (e.g. "Test") would only report the exit status of its last command.
+        shell: bash -el {0}
     strategy:
       fail-fast: false
       matrix:
@@ -19,50 +29,66 @@ jobs:
         # os: ["ubuntu-latest"]
         # source: ["source"]
         # A trailing "t" means the free-threaded (no-GIL) build of that version.
-        python-version: ["3.11", "3.12", "3.13", "3.14", "3.14t"]
+        # TODO: add "3.15t" once conda-forge builds cffi and numpy for cp315t.
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.14t", "3.15"]
     steps:
     - name: Checkout
-      uses: actions/checkout@v6
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       with:
         fetch-depth: 0
         persist-credentials: false
     - name: Compose conda environment file
+      env:
+        PYVER: ${{ matrix.python-version }}
       run: |
         # conda-forge ships two ABIs for CPython 3.13+ ("cp314" and "cp314t"),
         # and `python=3.14` alone lets the solver pick either one: it resolved
         # to free-threaded on Linux and Windows but to the GIL build on macOS.
         # The `python-gil` and `python-freethreading` metapackages pin
         # `python_abi` to one or the other, so ask for the one this matrix
         # entry wants instead of leaving it to the solver.
-        pyver="${{ matrix.python-version }}"
+        pyver=$PYVER
         if [[ $pyver == *t ]]; then
           variant=python-freethreading
           pyver=${pyver%t}
         else
           variant=python-gil
         fi
-        cp continuous_integration/environment.yml environment-ci.yml
+        channels=conda-forge,nodefaults
+        if [[ $pyver == 3.15 ]]; then
+          # TODO: drop this branch once Python 3.15.0 final is on conda-forge.
+          # Until then the 3.15 release candidates need `_python_rc`, which only
+          # the `python_rc` label provides.  The label must rank *below*
+          # conda-forge: it also holds older `python` rc builds (but no 3.15), and
+          # strict channel priority would then hide conda-forge's 3.15 rc.
+          channels=conda-forge,conda-forge/label/python_rc,nodefaults
+          awk '{ print } /^  - conda-forge$/ { print "  - conda-forge/label/python_rc" }' \
+            continuous_integration/environment.yml > environment-ci.yml
+        else
+          cp continuous_integration/environment.yml environment-ci.yml
+        fi
+        echo "CONDA_CHANNELS=$channels" >> "$GITHUB_ENV"
         echo "  - python=$pyver" >> environment-ci.yml
         echo "  - $variant" >> environment-ci.yml
         cat environment-ci.yml
     - name: Conda
-      uses: conda-incubator/setup-miniconda@v3
+      uses: conda-incubator/setup-miniconda@be893c923ea9cf1cf7cd510fbdde27c7e18cbdcb # v4.1.0
       with:
         auto-update-conda: true
         environment-file: environment-ci.yml
-        channels: conda-forge,nodefaults
+        channels: ${{ env.CONDA_CHANNELS }}
         channel-priority: strict
         activate-environment: suitesparse-graphblas
         auto-activate-base: false
     - name: GraphBLAS (from conda-forge)
       if: (contains(matrix.source, 'conda-forge'))
       run: |
-        conda install graphblas=$(cat GB_VERSION.txt)
+        conda install "graphblas=$(cat GB_VERSION.txt)"
     - name: GraphBLAS (from source)
       if: (contains(matrix.source, 'source'))
       run: |
         # From release (also works with beta versions)
-        GRAPHBLAS_PREFIX=${CONDA_PREFIX} bash suitesparse.sh refs/tags/$(cat GB_VERSION.txt).0
+        GRAPHBLAS_PREFIX="${CONDA_PREFIX}" bash suitesparse.sh "refs/tags/$(cat GB_VERSION.txt).0"
 
         # From tag
         # curl -L https://github.com/DrTimothyAldenDavis/GraphBLAS/archive/refs/tags/v$(cat GB_VERSION.txt).tar.gz | tar xzf -
@@ -84,18 +110,18 @@ jobs:
     - name: Configure coverage
       run: |
         # Cython's coverage plugin (see [tool.coverage.run] in pyproject.toml)
-        # needs coverage's C tracer.  conda-forge builds coverage without its C
-        # extension for free-threaded Python, and conda resolves `python=3.14`
-        # to the free-threaded build (3.14t) on some platforms.  There, loading
-        # the plugin raises ImportError and every `coverage run` dies before it
-        # runs anything, so run the tests directly instead.
+        # needs coverage's C tracer.  Where conda-forge has no compiled build of
+        # coverage for a Python (3.15, for now), it installs a pure-Python build
+        # that lacks the tracer.  There, loading the plugin raises ImportError and
+        # every `coverage run` dies before it runs anything, so run the tests
+        # directly instead.
         if python -c "import Cython.Coverage" 2>/dev/null; then
           coverage erase
-          echo "COV=coverage run -a --branch" >> $GITHUB_ENV
+          echo "COV=coverage run -a --branch" >> "$GITHUB_ENV"
         else
           echo "Cython coverage plugin unusable here; running without coverage"
           python -VV
-          echo "COV=python" >> $GITHUB_ENV
+          echo "COV=python" >> "$GITHUB_ENV"
         fi
     - name: Test
       env:

.github/workflows/update_graphblas.yml

@@ -1,12 +1,7 @@
 # Checks for latest SuiteSparse:GraphBLAS version on GitHub and creates a PR to update the version used by this repo.
 name: Check for GraphBLAS updates
 
-# In addition to permissions below, must explicitly allow GitHub Actions to create pull requests.
-# This setting can be found in a repository's settings under Actions > General > Workflow permissions.
-# https://github.com/peter-evans/create-pull-request#workflow-permissions
-permissions:
-  contents: write
-  pull-requests: write
+permissions: {}
 
 on:
   # Note: Workflow must run at least once to appear in workflows list.
@@ -26,24 +21,30 @@ jobs:
     name: Check for GraphBLAS update
     if: github.repository == 'GraphBLAS/python-suitesparse-graphblas' || github.repository == 'alugowski/python-suitesparse-graphblas'
     runs-on: ubuntu-latest
+    # In addition to these permissions, must explicitly allow GitHub Actions to create pull requests.
+    # This setting can be found in a repository's settings under Actions > General > Workflow permissions.
+    # https://github.com/peter-evans/create-pull-request#workflow-permissions
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.11"
 
       - name: Get latest GraphBLAS version
         run: |
           python latest_suitesparse_graphblas_version.py > GB_VERSION.txt
-          echo "GB_VERSION=$(cat GB_VERSION.txt)" >> $GITHUB_ENV
+          echo "GB_VERSION=$(cat GB_VERSION.txt)" >> "$GITHUB_ENV"
         shell: bash
 
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v8
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           # See documentation: https://github.com/peter-evans/create-pull-request
           # Action behavior: https://github.com/peter-evans/create-pull-request#action-behaviour