Refactor test utils to use a class

docs/conf.py

@@ -32,12 +32,20 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "scanpydoc.elegant_typehints",
+    "sphinx_autofixture",
 ]
 
 #  API documentation when building
 nitpicky = True
 autosummary_generate = True
 autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "special-members": True,
+    # everything except __call__ really, to avoid having to write autosummary templates
+    "exclude-members": (
+        "__setattr__,__delattr__,__repr__,__eq__,__or__,__ror__,__hash__,__weakref__,__init__,__new__"
+    ),
+}
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 todo_include_todos = False
@@ -55,9 +63,11 @@
     "np.dtype": "numpy.dtype",
     "np.number": "numpy.number",
     "np.integer": "numpy.integer",
+    "np.random.Generator": "numpy.random.Generator",
     "ArrayLike": "numpy.typing.ArrayLike",
     "DTypeLike": "numpy.typing.DTypeLike",
     "NDArray": "numpy.typing.NDArray",
+    "_pytest.fixtures.FixtureRequest": "pytest.FixtureRequest",
     **{
         k: v
         for k_plain, v in {
@@ -74,10 +84,17 @@
 # If that doesn’t work, ignore them
 nitpick_ignore = {
     ("py:class", "fast_array_utils.types.T_co"),
+    ("py:class", "Arr"),
+    ("py:class", "testing.fast_array_utils._array_type.Arr"),
+    ("py:class", "testing.fast_array_utils._array_type.Inner"),
+    ("py:class", "_DTypeLikeFloat32"),
+    ("py:class", "_DTypeLikeFloat64"),
     # sphinx bugs, should be covered by `autodoc_type_aliases` above
+    ("py:class", "Array"),
     ("py:class", "ArrayLike"),
     ("py:class", "DTypeLike"),
     ("py:class", "NDArray"),
+    ("py:class", "_pytest.fixtures.FixtureRequest"),
 }
 
 # Options for HTML output

docs/index.rst

@@ -1,10 +1,15 @@
 ``fast_array_utils``
 ====================
 
+.. toctree::
+   :hidden:
+
+   fast-array-utils <self>
+   testing
+
 .. automodule:: fast_array_utils
    :members:
 
-
 ``fast_array_utils.conv``
 -------------------------
 

docs/testing.rst

@@ -0,0 +1,11 @@
+``testing.fast_array_utils``
+============================
+
+.. automodule:: testing.fast_array_utils
+   :members:
+
+``testing.fast_array_utils.pytest``
+-----------------------------------
+
+.. automodule:: testing.fast_array_utils.pytest
+   :members:

pyproject.toml

@@ -23,20 +23,33 @@ classifiers = [
 ]
 dynamic = [ "description", "version" ]
 dependencies = [ "numba", "numpy" ]
-optional-dependencies.doc = [ "furo", "scanpydoc>=0.15.2", "sphinx>=8", "sphinx-autodoc-typehints" ]
+optional-dependencies.doc = [
+  "furo",
+  "pytest",
+  "scanpydoc>=0.15.2",
+  "sphinx>=8",
+  "sphinx-autodoc-typehints",
+  "sphinx-autofixture",
+]
 optional-dependencies.full = [ "dask", "fast-array-utils[sparse]", "h5py", "zarr" ]
 optional-dependencies.sparse = [ "scipy>=1.8" ]
 optional-dependencies.test = [ "coverage[toml]", "pytest", "pytest-codspeed" ]
 urls.'Documentation' = "https://icb-fast-array-utils.readthedocs-hosted.com/"
 urls.'Issue Tracker' = "https://github.com/scverse/fast-array-utils/issues"
 urls.'Source Code' = "https://github.com/scverse/fast-array-utils"
 
-[tool.hatch.metadata.hooks.docstring-description]
+entry_points.pytest11.fast_array_utils = "testing.fast_array_utils.pytest"
 
 [tool.hatch.version]
 source = "vcs"
 raw-options = { local_scheme = "no-local-version" } # be able to publish dev version
 
+# TODO: support setting main package in the plugin
+# [tool.hatch.metadata.hooks.docstring-description]
+
+[tool.hatch.build.targets.wheel]
+packages = [ "src/testing", "src/fast_array_utils" ]
+
 [tool.hatch.envs.default]
 installer = "uv"
 
@@ -85,6 +98,8 @@ lint.per-file-ignores."tests/**/test_*.py" = [
   "S101",    # tests use `assert`
 ]
 lint.allowed-confusables = [ "×", "’" ]
+lint.flake8-bugbear.extend-immutable-calls = [ "testing.fast_array_utils.Flags" ]
+
 lint.flake8-copyright.notice-rgx = "SPDX-License-Identifier: MPL-2\\.0"
 lint.flake8-type-checking.exempt-modules = [  ]
 lint.flake8-type-checking.strict = true

src/fast_array_utils/conv/_asarray.py

@@ -2,17 +2,16 @@
 from __future__ import annotations
 
 from functools import singledispatch
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, cast
 
 import numpy as np
+from numpy.typing import NDArray
 
 from .. import types
 
 
 if TYPE_CHECKING:
-    from typing import Any
-
-    from numpy.typing import ArrayLike, NDArray
+    from numpy.typing import ArrayLike
 
 
 __all__ = ["asarray"]
@@ -64,9 +63,9 @@
 
 @asarray.register(types.CupyArray)
 def _(x: types.CupyArray) -> NDArray[Any]:
-    return x.get()  # type: ignore[no-any-return]
+    return cast(NDArray[Any], x.get())
 
 
 @asarray.register(types.CupySparseMatrix)
 def _(x: types.CupySparseMatrix) -> NDArray[Any]:
-    return x.toarray().get()  # type: ignore[no-any-return]
+    return cast(NDArray[Any], x.toarray().get())

src/fast_array_utils/stats/_sum.py

@@ -2,26 +2,27 @@
 from __future__ import annotations
 
 from functools import partial, singledispatch
-from typing import TYPE_CHECKING, overload
+from typing import TYPE_CHECKING, Any, cast, overload
 
 import numpy as np
+from numpy.typing import NDArray
 
 from .. import types
 
 
 if TYPE_CHECKING:
-    from typing import Any, Literal
+    from typing import Literal
 
-    from numpy.typing import ArrayLike, DTypeLike, NDArray
+    from numpy.typing import ArrayLike, DTypeLike
 
 
 @overload
 def sum(
-    x: ArrayLike, /, *, axis: None = None, dtype: DTypeLike | None = None
+    x: ArrayLike | types.ZarrArray, /, *, axis: None = None, dtype: DTypeLike | None = None
 ) -> np.number[Any]: ...
 @overload
 def sum(
-    x: ArrayLike, /, *, axis: Literal[0, 1], dtype: DTypeLike | None = None
+    x: ArrayLike | types.ZarrArray, /, *, axis: Literal[0, 1], dtype: DTypeLike | None = None
 ) -> NDArray[Any]: ...
 @overload
 def sum(
@@ -30,7 +31,11 @@ def sum(
 
 
 def sum(
-    x: ArrayLike, /, *, axis: Literal[0, 1, None] = None, dtype: DTypeLike | None = None
+    x: ArrayLike | types.ZarrArray,
+    /,
+    *,
+    axis: Literal[0, 1, None] = None,
+    dtype: DTypeLike | None = None,
 ) -> NDArray[Any] | np.number[Any] | types.DaskArray:
     """Sum over both or one axis.
 
@@ -56,7 +61,7 @@ def _sum(
     dtype: DTypeLike | None = None,
 ) -> NDArray[Any] | np.number[Any] | types.DaskArray:
     assert not isinstance(x, types.CSBase | types.DaskArray)
-    return np.sum(x, axis=axis, dtype=dtype)  # type: ignore[no-any-return]
+    return cast(NDArray[Any] | np.number[Any], np.sum(x, axis=axis, dtype=dtype))
 
 
 @_sum.register(types.CSBase)
@@ -67,7 +72,7 @@ def _(
 
     if isinstance(x, types.CSMatrix):
         x = sp.csr_array(x) if x.format == "csr" else sp.csc_array(x)
-    return np.sum(x, axis=axis, dtype=dtype)  # type: ignore[no-any-return]
+    return cast(NDArray[Any] | np.number[Any], np.sum(x, axis=axis, dtype=dtype))
 
 
 @_sum.register(types.DaskArray)
@@ -108,11 +113,14 @@ def sum_drop_keepdims(
         # Explicitly use numpy result dtype (e.g. `NDArray[bool].sum().dtype == int64`)
         dtype = np.zeros(1, dtype=x.dtype).sum().dtype
 
-    return reduction(  # type: ignore[no-any-return,no-untyped-call]
-        x,
-        sum_drop_keepdims,
-        partial(np.sum, dtype=dtype),
-        axis=axis,
-        dtype=dtype,
-        meta=np.array([], dtype=dtype),
+    return cast(
+        types.DaskArray,
+        reduction(  # type: ignore[no-untyped-call]
+            x,
+            sum_drop_keepdims,
+            partial(np.sum, dtype=dtype),
+            axis=axis,
+            dtype=dtype,
+            meta=np.array([], dtype=dtype),
+        ),
     )