Migration guide (#898)

* Drop Py3.10, test Py3.13.

* Add migration guide and PyTest fixes.

* `pre-commit autoupdate`

Author: hameerabbasi

.github/workflows/ci.yml

@@ -11,19 +11,19 @@ jobs:
     strategy:
       matrix:
         os: ['ubuntu-latest']
-        python: ['3.10', '3.11', '3.12']
+        python: ['3.11', '3.12', '3.13']
         pip_opts: ['']
         numba_boundscheck: [0]
         include:
           - os: macos-latest
-            python: '3.10'
+            python: '3.11'
           - os: windows-latest
-            python: '3.10'
+            python: '3.11'
           - os: ubuntu-latest
-            python: '3.10'
+            python: '3.11'
             numba_boundscheck: 1
           - os: ubuntu-latest
-            python: '3.10'
+            python: '3.11'
             pip_opts: 'numpy<2'
       fail-fast: false
     runs-on: ${{ matrix.os }}

.pre-commit-config.yaml

@@ -1,14 +1,12 @@
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
     - id: check-yaml
     - id: end-of-file-fixer
     - id: trailing-whitespace
     - id: fix-byte-order-marker
     - id: destroyed-symlinks
-    - id: fix-encoding-pragma
-      args: ["--remove"]
     - id: mixed-line-ending
     - id: name-tests-test
       args: ["--pytest-test-first"]
@@ -18,7 +16,7 @@ repos:
       exclude: ".ipynb"
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.12.7
+  rev: v0.13.1
   hooks:
     - id: ruff-check
       args: ["--fix"]

docs/migration-jl.md

@@ -0,0 +1,26 @@
+# Migration to the Finch Julia backend
+To switch to the Finch Julia backend, set the environment variable `SPARSE_BACKEND="Finch"`, then continue using.
+
+While this is largely compatible with the Array API, support for some functions may not be present, and API compatibility isn't strictly preserved with the default (Numba) backend.
+
+However, the new backend has a large performance benefit over the default backend. Below, you will find a table of common invocations, with their equivalents in the Finch Julia backend. The most common change is a standard API for construction of arrays.
+
+| Numba Backend<br>(`SPARSE_BACKEND="Numba"`) | Finch Julia Backend<br>(`SPARSE_BACKEND="Finch"`)  | Notes |
+|---------------------------------------------|----------------------------------------------------|-------|
+| `sparse.COO.from_numpy(arr, fill_value=fv)`<br>`sparse.COO.from_scipy(arr)`<br>`sparse.COO(x)` | `sparse.asarray(x, format="coo", [fill_value=fv])` | Doesn't support pulling out individual arrays |
+| `sparse.GCXS.from_numpy(arr, fill_value=fv)`<br>`sparse.GCXS.from_scipy(arr)`<br>`sparse.GCXS(x)` | `sparse.asarray(x, format="csf", [fill_value=fv])` | Format might not be a 1:1 match |
+| `sparse.DOK.from_numpy(arr, fill_value=fv)`<br>`sparse.DOK.from_scipy(arr)`<br>`sparse.DOK(x)` | `sparse.asarray(x, format="dok", [fill_value=fv])` | Format might not be a 1:1 match |
+
+Most things work as expected, with the following exceptions, which aren't defined yet for Finch:
+
+* `sparse.broadcast_to`
+* `sparse.solve`
+* Statistical functions: `mean`, `std`, `var`
+* `sparse.isdtype`
+* `sparse.reshape`
+* Some elementwise functions
+* Manipulation functions: `concat`, `expand_dims`, `squeeze`, `flip`, `roll`, `stack`
+* `arg*` functions: `argmin`, `argmax`
+* Sorting functions: `sort`, `argsort`
+
+IEEE-754 compliance is hard to maintain with sparse arrays in general. This is now even more true of the Julia backend, which trades off performance for IEEE-754 compatibility.

mkdocs.yml

@@ -91,6 +91,7 @@ nav:
     - quickstart.md
     - construct.md
     - operations.md
+    - migration-jl.md
   - API:
     - api.md
     - api/*

pixi.toml

@@ -10,7 +10,7 @@ numba = ">=0.49"
 numpy = ">=1.17"
 
 [dependencies]
-python = ">=3.10,<3.13"
+python = ">=3.11,<3.14"
 
 [feature.extra.pypi-dependencies]
 dask = { version = ">=2024", extras = ["array"] }

pyproject.toml

@@ -9,7 +9,7 @@ description = "Sparse n-dimensional arrays for the PyData ecosystem"
 readme = "README.md"
 dependencies = ["numpy>=1.17", "numba>=0.49"]
 maintainers = [{ name = "Hameer Abbasi", email = "hameerabbasi@yahoo.com" }]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = { file = "LICENSE" }
 keywords = ["sparse", "numpy", "scipy", "dask"]
 classifiers = [

sparse/numba_backend/_coo/core.py

@@ -596,12 +596,12 @@ def nnz(self):
         --------
         >>> x = np.array([0, 0, 1, 0, 1, 2, 0, 1, 2, 3, 0, 0])
         >>> np.count_nonzero(x)
-        6
+        np.int64(6)
         >>> s = COO.from_numpy(x)
         >>> s.nnz
         6
         >>> np.count_nonzero(x) == s.nnz
-        True
+        np.True_
         """
         return self.coords.shape[1]
 

sparse/numba_backend/_sparse_array.py

@@ -82,12 +82,12 @@ def nnz(self):
         >>> from sparse import COO
         >>> x = np.array([0, 0, 1, 0, 1, 2, 0, 1, 2, 3, 0, 0])
         >>> np.count_nonzero(x)
-        6
+        np.int64(6)
         >>> s = COO.from_numpy(x)
         >>> s.nnz
         6
         >>> np.count_nonzero(x) == s.nnz
-        True
+        np.True_
         """
 
     @property