Flesh out readme (#80)

Author: flying-sheep

Diff for: .pre-commit-config.yaml

@@ -6,7 +6,7 @@ repos:
       - id: trailing-whitespace
       - id: no-commit-to-branch
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.2
+    rev: v0.11.5
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

Diff for: README.rst

@@ -15,14 +15,54 @@
 fast-array-utils
 ================
 
-To use ``fast_array_utils.stats`` or ``fast_array_tils.conv``:
+.. begin
+
+usage
+-----
+
+``fast-array-utils`` supports the following array types:
+
+- ``numpy.ndarray``
+- ``scipy.sparse.cs{rc}_{array,matrix}``
+- ``cupy.ndarray`` and ``cupyx.scipy.sparse.cs{rc}_matrix``
+- ``dask.array.Array``
+- ``h5py.Dataset`` and ``zarr.Array``
+- ``anndata.abc.CS{CR}Dataset`` (only supported by ``.conv.to_dense`` at the moment)
+
+Use ``fast_array_utils.conv.to_dense`` to densify arrays and optionally move them to CPU memory:
+
+.. code:: python
+
+   from fast_array_utils.conv import to_dense
+
+   numpy_arr = to_dense(sparse_arr_or_mat)
+   numpy_arr = to_dense(dask_or_cuda_arr, to_cpu_memory=True)
+   dense_dask_arr = to_dense(dask_arr)
+   dense_cupy_arr = to_dense(sparse_cupy_mat)
+
+Use ``fast_array_utils.conv.*`` to calculate statistics across one or both axes of a 2D array.
+All of them support an `axis` and `dtype` parameter:
+
+.. code:: python
+
+   from fast_array_utils import stats
+
+   all_equal = stats.is_constant(arr_2d)
+   col_sums = stats.sum(arr_2d, axis=0)
+   mean = stats.mean(arr_2d)
+   row_means, row_vars = stats.mean_var(arr_2d, axis=1)
+
+installation
+------------
+
+To use ``fast_array_utils.stats`` or ``fast_array_utils.conv``:
 
 .. code:: bash
 
-   [uv] pip install fast-array-utils[accel]
+   (uv) pip install 'fast-array-utils[accel]'
 
 To use ``testing.fast_array_utils``:
 
 .. code:: bash
 
-   [uv] pip install fast-array-utils[testing]
+   (uv) pip install 'fast-array-utils[testing]'

Diff for: docs/index.rst

@@ -12,3 +12,8 @@
 
 .. automodule:: fast_array_utils
    :members:
+
+See also the test utilities in :mod:`testing.fast_array_utils`.
+
+.. include:: ../README.rst
+   :start-after: .. begin

Diff for: pyproject.toml

@@ -1,10 +1,9 @@
 [build-system]
 build-backend = "hatchling.build"
-requires = [ "hatch-docstring-description", "hatch-vcs", "hatchling" ]
+requires = [ "hatch-docstring-description>=1.1.1", "hatch-fancy-pypi-readme", "hatch-vcs", "hatchling" ]
 
 [project]
 name = "fast-array-utils"
-readme = "README.rst"
 license = "MPL-2.0"
 authors = [
   { name = "Philipp A.", email = "[email protected]" },
@@ -18,7 +17,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
 ]
-dynamic = [ "description", "version" ]
+dynamic = [ "description", "readme", "version" ]
 dependencies = [ "numpy" ]
 optional-dependencies.accel = [ "numba" ]
 optional-dependencies.doc = [
@@ -55,8 +54,13 @@ entry-points.pytest11.fast_array_utils = "testing.fast_array_utils.pytest"
 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.metadata.hooks.fancy-pypi-readme]
+content-type = "text/x-rst"
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.rst"
+start-after = ".. begin"
+
+[tool.hatch.metadata.hooks.docstring-description]
 
 [tool.hatch.build.targets.wheel]
 packages = [ "src/testing", "src/fast_array_utils" ]

Diff for: src/testing/fast_array_utils/__init__.py

@@ -1,5 +1,8 @@
 # SPDX-License-Identifier: MPL-2.0
-"""Testing utilities."""
+"""Testing utilities.
+
+Ideally used through the :mod:`testing.fast_array_utils.pytest` plugin.
+"""
 
 from __future__ import annotations
 

Diff for: src/testing/fast_array_utils/_array_type.py

@@ -391,7 +391,7 @@ def random_mat(
     container: Literal["array", "matrix"] = "array",
     rng: np.random.Generator | None = None,
 ) -> types.CSBase:
-    """Create a random matrix."""
+    """Create a random sparse matrix/array."""
     from scipy.sparse import random as random_spmat
     from scipy.sparse import random_array as random_sparr
 

Diff for: src/testing/fast_array_utils/pytest.py

@@ -97,7 +97,7 @@ def _skip_if_unimportable(array_type: ArrayType) -> pytest.MarkDecorator:
 def array_type(request: pytest.FixtureRequest, tmp_path: Path) -> Generator[ArrayType, None, None]:
     """Fixture for a supported :class:`~testing.fast_array_utils.ArrayType`.
 
-    Use :class:`testing.fast_array_utils.Flags` to select or skip array types
+    Use :class:`testing.fast_array_utils.Flags` to select or skip array types:
 
     #.  using ``select=``/``args[0]``:
 
@@ -114,6 +114,21 @@ def test_something(array_type: ArrayType) -> None:
             @pytest.mark.array_type(skip=Flags.Dask | Flags.Disk | Flags.Gpu)
             def test_something(array_type: ArrayType) -> None:
                 ...
+
+    For special cases, you can also specify a :class:`set` of array types and flags.
+    This is useful if you want to select or skip only specific array types.
+
+    .. code:: python
+
+        from testing.fast_array_utils import SUPPORTED_TYPES
+
+        SPARSE_AND_DASK = {
+            at for at in SUPPORTED_TYPES if at.flags & Flags.Sparse and at.flags & Flags.Dask
+        }
+
+        @pytest.mark.array_type(skip={*SPARSE_AND_DASK, Flags.Disk})
+        def test_something(array_type: ArrayType) -> None:
+            ...
     """
     at = cast("ArrayType", request.param)
     f: h5py.File | None = None

Diff for: tests/test_numpy_scipy_sparse.py

@@ -32,7 +32,7 @@ def test_ndim(array_type: ArrayType[types.CSBase, None]) -> None:
 
 @numba.njit(cache=True)
 def mat_shape(mat: types.CSBase) -> tuple[int, ...]:
-    return np.shape(mat)  # type: ignore[arg-type]
+    return np.shape(mat)
 
 
 @pytest.mark.array_type(select=Flags.Sparse, skip=Flags.Dask | Flags.Disk | Flags.Gpu)

Diff for: tests/test_stats.py

@@ -100,7 +100,7 @@ def test_sum(
         assert sum_.dtype == dtype_in
 
     expected = np.sum(np_arr, axis=axis, dtype=dtype_arg)
-    np.testing.assert_array_equal(sum_, expected)  # type: ignore[arg-type]
+    np.testing.assert_array_equal(sum_, expected)
 
 
 @pytest.mark.array_type(skip=ATS_SPARSE_DS)
@@ -143,7 +143,7 @@ def test_mean_var(
         mean, var = mean.compute(), var.compute()  # type: ignore[assignment]
     if isinstance(mean, types.CupyArray) and isinstance(var, types.CupyArray):
         mean, var = mean.get(), var.get()
-    np.testing.assert_array_equal(mean, mean_expected)  # type: ignore[arg-type]
+    np.testing.assert_array_equal(mean, mean_expected)
     np.testing.assert_array_almost_equal(var, var_expected)  # type: ignore[arg-type]