Wrap legacy APIs

.pre-commit-config.yaml

@@ -5,6 +5,10 @@ repos:
     -   id: ruff
         args: ["--fix"]
     -   id: ruff-format
+    # The following can be removed once PLR0917 is out of preview
+    -   name: ruff preview rules
+        id: ruff
+        args: ["--preview", "--select=PLR0917"]
 -   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0
     hooks:

docs/conf.py

@@ -183,21 +183,21 @@ def setup(app: Sphinx):
 
 qualname_overrides = {
     "sklearn.neighbors._dist_metrics.DistanceMetric": "sklearn.metrics.DistanceMetric",
-    # If the docs are built with an old version of numpy, this will make it work:
-    "numpy.random.RandomState": "numpy.random.mtrand.RandomState",
     "scanpy.plotting._matrixplot.MatrixPlot": "scanpy.pl.MatrixPlot",
     "scanpy.plotting._dotplot.DotPlot": "scanpy.pl.DotPlot",
     "scanpy.plotting._stacked_violin.StackedViolin": "scanpy.pl.StackedViolin",
     "pandas.core.series.Series": "pandas.Series",
 }
 
 nitpick_ignore = [
+    # Technical issues
+    ("py:class", "numpy.int64"),  # documented as “attribute”
     # Will probably be documented
     ("py:class", "scanpy._settings.Verbosity"),
     ("py:class", "scanpy.neighbors.OnFlySymMatrix"),
     # Currently undocumented
     # https://github.com/mwaskom/seaborn/issues/1810
-    ("py:class", "seaborn.ClusterGrid"),
+    ("py:class", "seaborn.matrix.ClusterGrid"),
     ("py:class", "samalg.SAM"),
     # Won’t be documented
     ("py:class", "scanpy.plotting._utils._AxesSubplot"),

docs/extensions/cite.py

@@ -15,7 +15,7 @@
     from sphinx.application import Sphinx
 
 
-def cite_role(
+def cite_role(  # noqa: PLR0917
     name: str,
     rawsource: str,
     text: str,

docs/extensions/debug_docstrings.py

@@ -13,7 +13,7 @@
 _pd_orig = sphinx.ext.napoleon._process_docstring
 
 
-def pd_new(app, what, name, obj, options, lines):
+def pd_new(app, what, name, obj, options, lines):  # noqa: PLR0917
     _pd_orig(app, what, name, obj, options, lines)
     print(*lines, sep="\n")
 

docs/extensions/function_images.py

@@ -9,7 +9,7 @@
     from sphinx.ext.autodoc import Options
 
 
-def insert_function_images(
+def insert_function_images(  # noqa: PLR0917
     app: Sphinx, what: str, name: str, obj: Any, options: Options, lines: list[str]
 ):
     path = app.config.api_dir / f"{name}.png"

docs/release-notes/1.10.0.md

@@ -34,3 +34,5 @@
 ```
 
 * Dropped support for Python 3.8. [More details here](https://numpy.org/neps/nep-0029-deprecation_policy.html). {pr}`2695` {smaller}`P Angerer`
+* Deprecated specifying large numbers of function parameters by position as opposed to by name/keyword in all public APIs.
+  e.g. prefer `sc.tl.umap(adata, min_dist=0.1, spread=0.8)` over `sc.tl.umap(adata, 0.1, 0.8)` {pr}`2702` {smaller}`P Angerer`

pyproject.toml

@@ -66,6 +66,7 @@ dependencies = [
     "umap-learn>=0.3.10",
     "packaging",
     "session-info",
+    "legacy-api-wrap>=1.4",  # for positional API deprecations
     "get-annotations; python_version < '3.10'",
 ]
 dynamic = ["version"]
@@ -168,6 +169,8 @@ markers = [
     "gpu: tests that use a GPU (currently unused, but needs to be specified here as we import anndata.tests.helpers, which uses it)",
 ]
 filterwarnings = [
+    # legacy-api-wrap: internal use of positional API
+    "error:The specified parameters:FutureWarning",
     # When calling `.show()` in tests, this is raised
     "ignore:FigureCanvasAgg is non-interactive:UserWarning",
     # We explicitly handle these errors in tests
@@ -202,6 +205,7 @@ select = [
     "TID251",  # Banned imports
     "ICN",     # Follow import conventions
     "PTH",     # Pathlib instead of os.path
+    "PLR0917", # Ban APIs with too many positional parameters
 ]
 ignore = [
     # line too long -> we accept long comment lines; black gets rid of long code lines

scanpy/_compat.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from functools import partial
 from pathlib import Path
 
+from legacy_api_wrap import legacy_api
 from packaging import version
 
 try:
@@ -61,3 +63,6 @@ def pkg_version(package):
     from importlib.metadata import version as v
 
     return version.parse(v(package))
+
+
+old_positionals = partial(legacy_api, category=FutureWarning)

scanpy/_settings.py

@@ -10,6 +10,7 @@
 from typing import TYPE_CHECKING, Any, Literal, TextIO, Union
 
 from . import logging
+from ._compat import old_positionals
 from .logging import _RootLogger, _set_log_file, _set_log_level
 
 if TYPE_CHECKING:
@@ -36,6 +37,8 @@
 
 
 class Verbosity(IntEnum):
+    """Logging verbosity levels."""
+
     error = 0
     warning = 1
     info = 2
@@ -102,14 +105,14 @@ def __init__(
         file_format_figs: str = "pdf",
         autosave: bool = False,
         autoshow: bool = True,
-        writedir: str | Path = "./write/",
-        cachedir: str | Path = "./cache/",
-        datasetdir: str | Path = "./data/",
-        figdir: str | Path = "./figures/",
+        writedir: Path | str = "./write/",
+        cachedir: Path | str = "./cache/",
+        datasetdir: Path | str = "./data/",
+        figdir: Path | str = "./figures/",
         cache_compression: str | None = "lzf",
         max_memory=15,
         n_jobs=1,
-        logfile: str | Path | None = None,
+        logfile: Path | str | None = None,
         categories_to_ignore: Iterable[str] = ("N/A", "dontknow", "no_gate", "?"),
         _frameon: bool = True,
         _vector_friendly: bool = False,
@@ -269,7 +272,7 @@ def writedir(self) -> Path:
         return self._writedir
 
     @writedir.setter
-    def writedir(self, writedir: str | Path):
+    def writedir(self, writedir: Path | str):
         _type_check(writedir, "writedir", (str, Path))
         self._writedir = Path(writedir)
 
@@ -281,7 +284,7 @@ def cachedir(self) -> Path:
         return self._cachedir
 
     @cachedir.setter
-    def cachedir(self, cachedir: str | Path):
+    def cachedir(self, cachedir: Path | str):
         _type_check(cachedir, "cachedir", (str, Path))
         self._cachedir = Path(cachedir)
 
@@ -293,7 +296,7 @@ def datasetdir(self) -> Path:
         return self._datasetdir
 
     @datasetdir.setter
-    def datasetdir(self, datasetdir: str | Path):
+    def datasetdir(self, datasetdir: Path | str):
         _type_check(datasetdir, "datasetdir", (str, Path))
         self._datasetdir = Path(datasetdir).resolve()
 
@@ -305,7 +308,7 @@ def figdir(self) -> Path:
         return self._figdir
 
     @figdir.setter
-    def figdir(self, figdir: str | Path):
+    def figdir(self, figdir: Path | str):
         _type_check(figdir, "figdir", (str, Path))
         self._figdir = Path(figdir)
 
@@ -365,7 +368,7 @@ def logpath(self) -> Path | None:
         return self._logpath
 
     @logpath.setter
-    def logpath(self, logpath: str | Path | None):
+    def logpath(self, logpath: Path | str | None):
         _type_check(logpath, "logfile", (str, Path))
         # set via “file object” branch of logfile.setter
         self.logfile = Path(logpath).open("a")
@@ -385,7 +388,7 @@ def logfile(self) -> TextIO:
         return self._logfile
 
     @logfile.setter
-    def logfile(self, logfile: str | Path | TextIO | None):
+    def logfile(self, logfile: Path | str | TextIO | None):
         if not hasattr(logfile, "write") and logfile:
             self.logpath = logfile
         else:  # file object
@@ -413,8 +416,23 @@ def categories_to_ignore(self, categories_to_ignore: Iterable[str]):
     # Functions
     # --------------------------------------------------------------------------------
 
+    @old_positionals(
+        "scanpy",
+        "dpi",
+        "dpi_save",
+        "frameon",
+        "vector_friendly",
+        "fontsize",
+        "figsize",
+        "color_map",
+        "format",
+        "facecolor",
+        "transparent",
+        "ipython_format",
+    )
     def set_figure_params(
         self,
+        *,
         scanpy: bool = True,
         dpi: int = 80,
         dpi_save: int = 150,
@@ -427,7 +445,7 @@ def set_figure_params(
         facecolor: str | None = None,
         transparent: bool = False,
         ipython_format: str = "png2x",
-    ):
+    ) -> None:
         """\
         Set resolution/size, styling and format of figures.
 

scanpy/_utils/__init__.py

@@ -45,7 +45,7 @@ def __repr__(self) -> str:
 _empty = Empty.token
 
 # e.g. https://scikit-learn.org/stable/modules/generated/sklearn.decomposition.PCA.html
-AnyRandom = Union[None, int, random.RandomState]  # maybe in the future random.Generator
+AnyRandom = Union[int, random.RandomState, None]  # maybe in the future random.Generator
 
 EPS = 1e-15
 
@@ -96,42 +96,56 @@ def type_doc(name: str):
     )
 
 
-def deprecated_arg_names(arg_mapping: Mapping[str, str]):
-    """
-    Decorator which marks a functions keyword arguments as deprecated. It will
-    result in a warning being emitted when the deprecated keyword argument is
-    used, and the function being called with the new argument.
-
-    Parameters
-    ----------
-    arg_mapping
-        Mapping from deprecated argument name to current argument name.
-    """
-
+def renamed_arg(old_name, new_name, *, pos_0: bool = False):
     def decorator(func):
         @wraps(func)
-        def func_wrapper(*args, **kwargs):
-            warnings.simplefilter("always", DeprecationWarning)  # turn off filter
-            for old, new in arg_mapping.items():
-                if old in kwargs:
-                    warnings.warn(
-                        f"Keyword argument '{old}' has been "
-                        f"deprecated in favour of '{new}'. "
-                        f"'{old}' will be removed in a future version.",
-                        category=DeprecationWarning,
-                        stacklevel=2,
+        def wrapper(*args, **kwargs):
+            if old_name in kwargs:
+                f_name = func.__name__
+                pos_str = (
+                    (
+                        f" at first position. Call it as `{f_name}(val, ...)` "
+                        f"instead of `{f_name}({old_name}=val, ...)`"
                     )
-                    val = kwargs.pop(old)
-                    kwargs[new] = val
-            # reset filter
-            warnings.simplefilter("default", DeprecationWarning)
+                    if pos_0
+                    else ""
+                )
+                msg = (
+                    f"In function `{f_name}`, argument `{old_name}` "
+                    f"was renamed to `{new_name}`{pos_str}."
+                )
+                warnings.warn(msg, FutureWarning, stacklevel=3)
+                if pos_0:
+                    args = (kwargs.pop(old_name), *args)
+                else:
+                    kwargs[new_name] = kwargs.pop(old_name)
             return func(*args, **kwargs)
 
-        return func_wrapper
+        return wrapper
 
     return decorator
 
 
+def _import_name(name: str) -> Any:
+    from importlib import import_module
+
+    parts = name.split(".")
+    obj = import_module(parts[0])
+    for i, name in enumerate(parts[1:]):
+        try:
+            obj = import_module(f"{obj.__name__}.{name}")
+        except ModuleNotFoundError:
+            break
+    else:
+        i = len(parts)
+    for name in parts[i + 1 :]:
+        try:
+            obj = getattr(obj, name)
+        except AttributeError:
+            raise RuntimeError(f"{parts[:i]}, {parts[i + 1:]}, {obj} {name}")
+    return obj
+
+
 def _one_of_ours(obj, root: str):
     return (
         hasattr(obj, "__name__")
@@ -146,19 +160,19 @@ def descend_classes_and_funcs(mod: ModuleType, root: str, encountered=None):
     if encountered is None:
         encountered = WeakSet()
     for obj in vars(mod).values():
-        if not _one_of_ours(obj, root):
+        if not _one_of_ours(obj, root) or obj in encountered:
             continue
+        encountered.add(obj)
         if callable(obj) and not isinstance(obj, MethodType):
             yield obj
             if isinstance(obj, type):
                 for m in vars(obj).values():
                     if callable(m) and _one_of_ours(m, root):
                         yield m
-        elif isinstance(obj, ModuleType) and obj not in encountered:
+        elif isinstance(obj, ModuleType):
             if obj.__name__.startswith("scanpy.tests"):
                 # Python’s import mechanism seems to add this to `scanpy`’s attributes
                 continue
-            encountered.add(obj)
             yield from descend_classes_and_funcs(obj, root, encountered)
 
 
@@ -264,6 +278,7 @@ def compute_association_matrix_of_groups(
     adata: AnnData,
     prediction: str,
     reference: str,
+    *,
     normalization: Literal["prediction", "reference"] = "prediction",
     threshold: float = 0.01,
     max_n_names: int | None = 2,
@@ -595,7 +610,7 @@ def select_groups(
     return groups_order_subset, groups_masks
 
 
-def warn_with_traceback(message, category, filename, lineno, file=None, line=None):
+def warn_with_traceback(message, category, filename, lineno, file=None, line=None):  # noqa: PLR0917
     """Get full tracebacks when warning is raised by setting
 
     warnings.showwarning = warn_with_traceback

scanpy/datasets/_datasets.py

@@ -10,6 +10,7 @@
 
 from .. import _utils
 from .. import logging as logg
+from .._compat import old_positionals
 from .._settings import settings
 from ..readwrite import read, read_visium
 from ._utils import check_datasetdir_exists, filter_oldformatwarning
@@ -20,7 +21,11 @@
 HERE = Path(__file__).parent
 
 
+@old_positionals(
+    "n_variables", "n_centers", "cluster_std", "n_observations", "random_state"
+)
 def blobs(
+    *,
     n_variables: int = 11,
     n_centers: int = 5,
     cluster_std: float = 1.0,
@@ -192,7 +197,7 @@ def paul15() -> ad.AnnData:
     # names reflecting the cell type identifications from the paper
     cell_type = 6 * ["Ery"]
     cell_type += "MEP Mk GMP GMP DC Baso Baso Mo Mo Neu Neu Eos Lymph".split()
-    adata.obs["paul15_clusters"] = [f"{i}{cell_type[i-1]}" for i in clusters]
+    adata.obs["paul15_clusters"] = [f"{i}{cell_type[i - 1]}" for i in clusters]
     # make string annotations categorical (optional)
     _utils.sanitize_anndata(adata)
     # just keep the first of the two equivalent names per gene