Backport PR #3380: Use deprecation decorator (#3382)

docs/release-notes/3380.bugfix.md

@@ -0,0 +1 @@
+Raise {exc}`FutureWarning` when calling deprecated {mod}`scanpy.pp` functions {smaller}`P Angerer`

pyproject.toml

@@ -66,6 +66,7 @@ dependencies = [
     "packaging>=21.3",
     "session-info",
     "legacy-api-wrap>=1.4",  # for positional API deprecations
+    "typing-extensions; python_version < '3.13'",
 ]
 dynamic = ["version"]
 

src/scanpy/_compat.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import sys
 from dataclasses import dataclass, field
 from functools import cache, partial
@@ -38,6 +39,8 @@ class ZappyArray:
     "fullname",
     "pkg_metadata",
     "pkg_version",
+    "old_positionals",
+    "deprecated",
 ]
 
 
@@ -90,3 +93,12 @@ def pkg_version(package: str) -> Version:
     # but this code makes it possible to run scanpy without it.
     def old_positionals(*old_positionals: str):
         return lambda func: func
+
+
+if sys.version_info >= (3, 13):
+    from warnings import deprecated as _deprecated
+else:
+    from typing_extensions import deprecated as _deprecated
+
+
+deprecated = partial(_deprecated, category=FutureWarning)

src/scanpy/plotting/_preprocessing.py

@@ -6,7 +6,7 @@
 from matplotlib import pyplot as plt
 from matplotlib import rcParams
 
-from .._compat import old_positionals
+from .._compat import deprecated, old_positionals
 from .._settings import settings
 from . import _utils
 
@@ -103,6 +103,7 @@ def highly_variable_genes(
 
 
 # backwards compat
+@deprecated("Use sc.pl.highly_variable_genes instead")
 @old_positionals("log", "show", "save")
 def filter_genes_dispersion(
     result: np.recarray,

src/scanpy/preprocessing/_deprecated/highly_variable_genes.py

@@ -9,7 +9,7 @@
 from scipy.sparse import issparse
 
 from ... import logging as logg
-from ..._compat import old_positionals
+from ..._compat import deprecated, old_positionals
 from .._distributed import materialize_as_ndarray
 from .._utils import _get_mean_var
 
@@ -19,6 +19,7 @@
     from scipy.sparse import spmatrix
 
 
+@deprecated("Use sc.pp.highly_variable_genes instead")
 @old_positionals(
     "flavor",
     "min_disp",
@@ -48,18 +49,17 @@ def filter_genes_dispersion(
     """\
     Extract highly variable genes :cite:p:`Satija2015,Zheng2017`.
 
-    .. warning::
-        .. deprecated:: 1.3.6
-            Use :func:`~scanpy.pp.highly_variable_genes`
-            instead. The new function is equivalent to the present
-            function, except that
+    .. deprecated:: 1.3.6
 
-            * the new function always expects logarithmized data
-            * `subset=False` in the new function, it suffices to
-              merely annotate the genes, tools like `pp.pca` will
-              detect the annotation
-            * you can now call: `sc.pl.highly_variable_genes(adata)`
-            * `copy` is replaced by `inplace`
+       Use :func:`~scanpy.pp.highly_variable_genes` instead.
+       The new function is equivalent to the present function, except that
+
+       * the new function always expects logarithmized data
+       * `subset=False` in the new function, it suffices to
+         merely annotate the genes, tools like `pp.pca` will
+         detect the annotation
+       * you can now call: `sc.pl.highly_variable_genes(adata)`
+       * `copy` is replaced by `inplace`
 
     If trying out parameters, pass the data matrix instead of AnnData.
 

src/scanpy/preprocessing/_simple.py

@@ -19,7 +19,7 @@
 from sklearn.utils import check_array, sparsefuncs
 
 from .. import logging as logg
-from .._compat import old_positionals
+from .._compat import deprecated, old_positionals
 from .._settings import settings as sett
 from .._utils import (
     _check_array_function_arguments,
@@ -34,26 +34,25 @@
 from ._distributed import materialize_as_ndarray
 from ._utils import _to_dense
 
-# install dask if available
 try:
     import dask.array as da
 except ImportError:
     da = None
 
-# backwards compat
-from ._deprecated.highly_variable_genes import filter_genes_dispersion  # noqa: F401
-
 if TYPE_CHECKING:
     from collections.abc import Collection, Iterable, Sequence
     from numbers import Number
     from typing import Literal
 
     import pandas as pd
     from numpy.typing import NDArray
+    from scipy.sparse import csc_matrix
 
     from .._compat import DaskArray
     from .._utils import AnyRandom
 
+    CSMatrix = csr_matrix | csc_matrix
+
 
 @old_positionals(
     "min_counts", "min_genes", "max_counts", "max_genes", "inplace", "copy"
@@ -476,6 +475,7 @@ def sqrt(
         return X.sqrt()
 
 
+@deprecated("Use sc.pp.normalize_total instead")
 @old_positionals(
     "counts_per_cell_after",
     "counts_per_cell",
@@ -499,16 +499,16 @@ def normalize_per_cell(
     """\
     Normalize total counts per cell.
 
-    .. warning::
-        .. deprecated:: 1.3.7
-            Use :func:`~scanpy.pp.normalize_total` instead.
-            The new function is equivalent to the present
-            function, except that
+    .. deprecated:: 1.3.7
+
+       Use :func:`~scanpy.pp.normalize_total` instead.
+       The new function is equivalent to the present
+       function, except that
 
-            * the new function doesn't filter cells based on `min_counts`,
-              use :func:`~scanpy.pp.filter_cells` if filtering is needed.
-            * some arguments were renamed
-            * `copy` is replaced by `inplace`
+       * the new function doesn't filter cells based on `min_counts`,
+         use :func:`~scanpy.pp.filter_cells` if filtering is needed.
+       * some arguments were renamed
+       * `copy` is replaced by `inplace`
 
     Normalize each cell by total counts over all genes, so that every cell has
     the same total count after normalization.