Use deprecation decorator

[flying-sheep]

• Closes Tell people they’re using deprecated functions #2505
• Tests included or not required because:

• Release notes not necessary because:

Alternative: make the decorator insert the change to docs too, but that’s more involved, as one would have to parse the docstring and figure out where and at what indentation level to insert the deprecation warning directive:

def deprecated(
    msg: LiteralString, /, version: LiteralString, notice: LiteralString *, stacklevel: int = 2
) -> Callable[[Callable[P, R]], Callable[P, R]]:
    def decorator(f_or_c: Callable[P, R], /) -> Callable[P, R]:
        f_or_c.__doc__ = ...  # TODO: insert .. deprecated:: {version}\n{indent(notice, " "*3)}
        return _deprecated(f"(since {version}:) {msg}", category=FutureWarning, stacklevel=stacklevel)(f_or_c)

    return decorator

[codecov]

Codecov Report

Attention: Patch coverage is 90.00000% with 1 line in your changes missing coverage. Please review.

Project coverage is 76.50%. Comparing base (751eafa) to head (735f00a).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/scanpy/_compat.py	75.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3380   +/-   ##
=======================================
  Coverage   76.49%   76.50%           
=======================================
  Files         111      111           
  Lines       12867    12874    +7     
=======================================
+ Hits         9843     9849    +6     
- Misses       3024     3025    +1     

Files with missing lines	Coverage Δ
src/scanpy/plotting/_preprocessing.py	87.71% <100.00%> (+0.21%)	⬆️
...preprocessing/_deprecated/highly_variable_genes.py	95.55% <100.00%> (+0.04%)	⬆️
src/scanpy/preprocessing/_simple.py	89.94% <100.00%> (+0.02%)	⬆️
src/scanpy/_compat.py	81.81% <75.00%> (-0.29%)	⬇️

---- 🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests