Edit outdated docs to pass doctests.

.github/workflows/ci.yml

@@ -50,7 +50,7 @@ jobs:
           pip install -e '.[tests]'
       - name: Run tests
         run: |
-          SPARSE_BACKEND=Numba pytest --pyargs sparse --cov-report=xml:coverage_Numba.xml -n auto -vvv
+          SPARSE_BACKEND=Numba pytest --pyargs sparse --doctest-modules --cov-report=xml:coverage_Numba.xml -n auto -vvv
           SPARSE_BACKEND=Finch pytest --pyargs sparse/tests --cov-report=xml:coverage_Finch.xml -n auto -vvv
           SPARSE_BACKEND=MLIR pytest --pyargs sparse/mlir_backend --cov-report=xml:coverage_MLIR.xml -n auto -vvv
       - uses: codecov/codecov-action@v4

sparse/numba_backend/_compressed/compressed.py

@@ -819,7 +819,7 @@ def _prune(self):
         --------
         >>> coords = np.array([[0, 1, 2, 3]])
         >>> data = np.array([1, 0, 1, 2])
-        >>> s = COO(coords, data).asformat("gcxs")
+        >>> s = COO(coords, data, shape=(4,)).asformat("gcxs")
         >>> s._prune()
         >>> s.nnz
         3

sparse/numba_backend/_coo/common.py

@@ -901,7 +901,7 @@ def diagonalize(a, axis=0):
     >>> a = sparse.random((3, 3, 3, 3, 3), density=0.3)
     >>> a_diag = sparse.diagonalize(a, axis=2)
     >>> (sparse.diagonal(a_diag, axis1=2, axis2=5) == a.transpose([0, 1, 3, 4, 2])).all()
-    True
+    np.True_
 
     Returns
     -------
@@ -944,7 +944,7 @@ def isposinf(x, out=None):
     --------
     [`numpy.isposinf`][] : The NumPy equivalent
     """
-    from .core import elemwise
+    from sparse import elemwise
 
     return elemwise(lambda x, out=None, dtype=None: np.isposinf(x, out=out), x, out=out)
 
@@ -971,7 +971,7 @@ def isneginf(x, out=None):
     --------
     [`numpy.isneginf`][] : The NumPy equivalent
     """
-    from .core import elemwise
+    from sparse import elemwise
 
     return elemwise(lambda x, out=None, dtype=None: np.isneginf(x, out=out), x, out=out)
 
@@ -1234,7 +1234,7 @@ def unique_values(x, /):
     >>> import sparse
     >>> x = sparse.COO.from_numpy([1, 0, 2, 1, 2, -3])
     >>> sparse.unique_values(x)
-    array([-3, 0, 1, 2])
+    array([-3,  0,  1,  2])
     """
 
     x = _validate_coo_input(x)
@@ -1279,9 +1279,9 @@ def sort(x, /, *, axis=-1, descending=False, stable=False):
     >>> import sparse
     >>> x = sparse.COO.from_numpy([1, 0, 2, 0, 2, -3])
     >>> sparse.sort(x).todense()
-    array([-3, 0, 0, 1, 2, 2])
+    array([-3,  0,  0,  1,  2,  2])
     >>> sparse.sort(x, descending=True).todense()
-    array([ 2, 2, 1, 0, 0, -3])
+    array([ 2,  2,  1,  0,  0, -3])
 
     """
     from .._common import moveaxis

sparse/numba_backend/_coo/core.py

@@ -156,7 +156,7 @@ class COO(SparseArray, NDArrayOperatorsMixin):  # lgtm [py/missing-equals]
     >>> rows = [0, 1, 2, 3, 4]
     >>> cols = [0, 0, 0, 1, 1]
     >>> data = [10, 20, 30, 40, 50]
-    >>> z = COO((data, (rows, cols)))
+    >>> z = COO((data, (rows, cols)), shape=(5, 2))
     >>> z.todense()  # doctest: +NORMALIZE_WHITESPACE
     array([[10,  0],
            [20,  0],
@@ -168,10 +168,10 @@ class COO(SparseArray, NDArrayOperatorsMixin):  # lgtm [py/missing-equals]
     indices imply summation:
 
     >>> d = {(0, 0, 0): 1, (1, 2, 3): 2, (1, 1, 0): 3}
-    >>> COO(d)
+    >>> COO(d, shape=(2, 3, 4))
     <COO: shape=(2, 3, 4), dtype=int64, nnz=3, fill_value=0>
     >>> L = [((0, 0), 1), ((1, 1), 2), ((0, 0), 3)]
-    >>> COO(L).todense()  # doctest: +NORMALIZE_WHITESPACE
+    >>> COO(L, shape=(2, 2)).todense()  # doctest: +NORMALIZE_WHITESPACE
     array([[4, 0],
            [0, 2]])
 
@@ -440,6 +440,7 @@ def from_scipy_sparse(cls, x, /, *, fill_value=None):
 
         Examples
         --------
+        >>> import scipy.sparse
         >>> x = scipy.sparse.rand(6, 3, density=0.2)
         >>> s = COO.from_scipy_sparse(x)
         >>> np.array_equal(x.todense(), s.todense())
@@ -459,7 +460,7 @@ def from_scipy_sparse(cls, x, /, *, fill_value=None):
         )
 
     @classmethod
-    def from_iter(cls, x, shape=None, fill_value=None, dtype=None):
+    def from_iter(cls, x, shape, fill_value=None, dtype=None):
         """
         Converts an iterable in certain formats to a [`sparse.COO`][] array. See examples
         for details.
@@ -468,7 +469,7 @@ def from_iter(cls, x, shape=None, fill_value=None, dtype=None):
         ----------
         x : Iterable or Iterator
             The iterable to convert to [`sparse.COO`][].
-        shape : tuple[int], optional
+        shape : tuple[int]
             The shape of the array.
         fill_value : scalar
             The fill value for this array.
@@ -486,31 +487,31 @@ def from_iter(cls, x, shape=None, fill_value=None, dtype=None):
         Here, the first part represents the coordinate and the second part represents the value.
 
         >>> x = [((0, 0), 1), ((1, 1), 1)]
-        >>> s = COO.from_iter(x)
+        >>> s = COO.from_iter(x, shape=(2, 2))
         >>> s.todense()
         array([[1, 0],
                [0, 1]])
 
         You can also have a similar format with a dictionary.
 
         >>> x = {(0, 0): 1, (1, 1): 1}
-        >>> s = COO.from_iter(x)
+        >>> s = COO.from_iter(x, shape=(2, 2))
         >>> s.todense()
         array([[1, 0],
                [0, 1]])
 
         The third supported format is ``(data, (..., row, col))``.
 
         >>> x = ([1, 1], ([0, 1], [0, 1]))
-        >>> s = COO.from_iter(x)
+        >>> s = COO.from_iter(x, shape=(2, 2))
         >>> s.todense()
         array([[1, 0],
                [0, 1]])
 
         You can also pass in a [`collections.abc.Iterator`][] object.
 
         >>> x = [((0, 0), 1), ((1, 1), 1)].__iter__()
-        >>> s = COO.from_iter(x)
+        >>> s = COO.from_iter(x, shape=(2, 2))
         >>> s.todense()
         array([[1, 0],
                [0, 1]])
@@ -1293,7 +1294,7 @@ def _sort_indices(self):
         --------
         >>> coords = np.array([[1, 2, 0]], dtype=np.uint8)
         >>> data = np.array([4, 1, 3], dtype=np.uint8)
-        >>> s = COO(coords, data)
+        >>> s = COO(coords, data, shape=(3,))
         >>> s._sort_indices()
         >>> s.coords  # doctest: +NORMALIZE_WHITESPACE
         array([[0, 1, 2]], dtype=uint8)
@@ -1321,7 +1322,7 @@ def _sum_duplicates(self):
         --------
         >>> coords = np.array([[0, 1, 1, 2]], dtype=np.uint8)
         >>> data = np.array([6, 5, 2, 2], dtype=np.uint8)
-        >>> s = COO(coords, data)
+        >>> s = COO(coords, data, shape=(3,))
         >>> s._sum_duplicates()
         >>> s.coords  # doctest: +NORMALIZE_WHITESPACE
         array([[0, 1, 2]], dtype=uint8)
@@ -1354,7 +1355,7 @@ def _prune(self):
         --------
         >>> coords = np.array([[0, 1, 2, 3]])
         >>> data = np.array([1, 0, 1, 2])
-        >>> s = COO(coords, data)
+        >>> s = COO(coords, data, shape=(4,))
         >>> s._prune()
         >>> s.nnz
         3

sparse/numba_backend/_coo/indexing.py

@@ -524,9 +524,9 @@ def _get_mask_pairs(starts_old, stops_old, c, idx):  # pragma: no cover
     --------
     >>> c = np.array([1, 2, 1, 2, 1, 1, 2, 2])
     >>> starts_old = numba.typed.List()
-    ... starts_old.append(4)
+    >>> starts_old.append(4)
     >>> stops_old = numba.typed.List()
-    ... stops_old.append(8)
+    >>> stops_old.append(8)
     >>> idx = np.array([1, 2, 1])
     >>> _get_mask_pairs(starts_old, stops_old, c, idx)
     (ListType[int64]([4]), ListType[int64]([6]), 2)
@@ -575,9 +575,9 @@ def _filter_pairs(starts, stops, coords, indices):  # pragma: no cover
     --------
     >>> import numpy as np
     >>> starts = numba.typed.List()
-    ... starts.append(2)
+    >>> starts.append(2)
     >>> stops = numba.typed.List()
-    ... stops.append(7)
+    >>> stops.append(7)
     >>> coords = np.array([[0, 1, 2, 3, 4, 5, 6, 7]])
     >>> indices = np.array([[2, 8, 2]])  # Start, stop, step pairs
     >>> _filter_pairs(starts, stops, coords, indices)
@@ -627,11 +627,11 @@ def _join_adjacent_pairs(starts_old, stops_old):  # pragma: no cover
     Examples
     --------
     >>> starts = numba.typed.List()
-    ... starts.append(2)
-    ... starts.append(5)
+    >>> starts.append(2)
+    >>> starts.append(5)
     >>> stops = numba.typed.List()
-    ... stops.append(5)
-    ... stops.append(7)
+    >>> stops.append(5)
+    >>> stops.append(7)
     >>> _join_adjacent_pairs(starts, stops)
     (ListType[int64]([2]), ListType[int64]([7]))
     """

sparse/numba_backend/_dok.py

@@ -149,6 +149,7 @@ def from_scipy_sparse(cls, x, /, *, fill_value=None):
 
         Examples
         --------
+        >>> import scipy.sparse
         >>> x = scipy.sparse.rand(6, 3, density=0.2)
         >>> s = DOK.from_scipy_sparse(x)
         >>> np.array_equal(x.todense(), s.todense())

sparse/numba_backend/_sparse_array.py

@@ -691,7 +691,7 @@ def mean(self, axis=None, keepdims=False, dtype=None, out=None):
         mean along all axes.
 
         >>> s.mean()
-        0.5
+        np.float64(0.5)
         """
 
         if axis is None:
@@ -771,7 +771,7 @@ def var(self, axis=None, dtype=None, out=None, ddof=0, keepdims=False):
         variance along all axes.
 
         >>> s.var()
-        0.5
+        np.float64(0.5)
         """
         axis = normalize_axis(axis, self.ndim)
 

sparse/numba_backend/_utils.py

@@ -267,19 +267,18 @@ def random(
 
     Examples
     --------
-    >>> from sparse import random
     >>> from scipy import stats
-    >>> rvs = lambda x: stats.poisson(25, loc=10).rvs(x, random_state=np.random.RandomState(1))
-    >>> s = random((2, 3, 4), density=0.25, random_state=np.random.RandomState(1), data_rvs=rvs)
-    >>> s.todense()  # doctest: +NORMALIZE_WHITESPACE
-    array([[[ 0,  0,  0,   0],
-            [34,  0, 29,  30],
+    >>> rng = np.random.default_rng(42)
+    >>> rvs = lambda x: stats.poisson(25, loc=10).rvs(x, random_state=rng)
+    >>> s = sparse.random((2, 3, 4), density=0.25, random_state=rng, data_rvs=rvs)
+    >>> s.todense()
+    array([[[39,  0,  0,  0],
+            [28, 33,  0, 37],
             [ 0,  0,  0,  0]],
     <BLANKLINE>
-           [[33,  0,  0, 34],
-            [34,  0,  0,  0],
-            [ 0,  0,  0,  0]]])
-
+           [[ 0,  0,  0,  0],
+            [ 0,  0, 34,  0],
+            [ 0,  0,  0, 36]]])
     """
     # Copied, in large part, from scipy.sparse.random
     # See https://github.com/scipy/scipy/blob/main/LICENSE.txt
@@ -422,15 +421,15 @@ def equivalent(x, y, /, loose=False):
     Examples
     --------
     >>> equivalent(1, 1)
-    True
+    np.True_
     >>> equivalent(np.nan, np.nan + 1)
-    True
+    np.True_
     >>> equivalent(1, 2)
-    False
+    np.False_
     >>> equivalent(np.inf, np.inf)
-    True
-    >>> equivalent(np.PZERO, np.NZERO)
-    False
+    np.True_
+    >>> equivalent(np.float64(0.0), np.float64(-0.0))
+    np.False_
     """
     x = np.asarray(x)
     y = np.asarray(y)

sparse/numba_backend/tests/test_coo.py

@@ -1025,11 +1025,14 @@ def test_invalid_attrs_error():
 def test_invalid_iterable_error():
     with pytest.raises(ValueError):
         x = [(3, 4, 5)]
-        COO.from_iter(x)
+        COO.from_iter(x, shape=(6,))
 
     with pytest.raises(ValueError):
         x = [((2.3, 4.5), 3.2)]
-        COO.from_iter(x)
+        COO.from_iter(x, shape=(5,))
+
+    with pytest.raises(TypeError):
+        COO.from_iter({(1, 1): 1})
 
 
 def test_prod_along_axis():