Use deprecation decorator

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

@@ -48,6 +48,10 @@ class ZappyArray:
     "fullname",
     "pkg_metadata",
     "pkg_version",
+    "old_positionals",
+    "deprecated",
+    "njit",
+    "_numba_threading_layer",
 ]
 
 
@@ -102,6 +106,15 @@ 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)
+
+
 @overload
 def njit(fn: Callable[P, R], /) -> Callable[P, R]: ...
 @overload

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

@@ -18,7 +18,7 @@
 from sklearn.utils import check_array, sparsefuncs
 
 from .. import logging as logg
-from .._compat import njit, old_positionals
+from .._compat import deprecated, njit, old_positionals
 from .._settings import settings as sett
 from .._utils import (
     _check_array_function_arguments,
@@ -474,6 +474,7 @@ def sqrt(
         return X.sqrt()
 
 
+@deprecated("Use sc.pp.normalize_total instead")
 @old_positionals(
     "counts_per_cell_after",
     "counts_per_cell",
@@ -497,16 +498,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
 
-            * 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`
+       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`
 
     Normalize each cell by total counts over all genes, so that every cell has
     the same total count after normalization.