Wrap legacy APIs

[flying-sheep]

Part of scanpy 2.0

• Closes #
• Tests included or not required because:

• Release notes not necessary because:

I implemented a Ruff check (PLR0917) for this, but setting max-positional-args = 3 would make this massive PR even larger, so I opted to do it in a separate one.

Reviewers

Your main job is to check if the position of the * makes sense for each exported function (i.e. the ones with the @legacy_api decorator). I tried my best to base it on internal usage of each API, but one placement or the other might be to early.

The only real logic changes are in scanpy/tests/test_package_structure.py. This PR:

• makes public APIs with more than 5 parameters keyword-only without breaking backwards compatibility (for now)
• makes private APIs with more than 5 parameters keyword-only
• checks that we don’t internally use the old positional APIs using a warning filter with action='error'
• checks that APIs use our convention for the copy parameter (adata as first param, returns adata type or None`)
• manually checked that APIs use our convention filename: Path | str/path: Path | str

Follow-up changes

• Set max-positional-args = 3
• make sure that no new public API gets introduced without being included in the api_module_names list
• enforce convention show, return_fig, ax
• enforce convention for random_seed: AnyRandom
• deprecate/remove read spatial and plotting spatial from scanpy. #2331

[codecov]

Codecov Report

Merging #2702 (8aec872) into master (86dc4d5) will increase coverage by 0.29%.
The diff coverage is 83.20%.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2702      +/-   ##
==========================================
+ Coverage   72.53%   72.83%   +0.29%     
==========================================
  Files         111      111              
  Lines       12185    12378     +193     
==========================================
+ Hits         8838     9015     +177     
- Misses       3347     3363      +16     

Files	Coverage Δ
scanpy/_compat.py	44.44% <100.00%> (+3.96%)	⬆️
scanpy/_settings.py	90.24% <100.00%> (+0.07%)	⬆️
scanpy/datasets/_datasets.py	86.04% <100.00%> (+0.21%)	⬆️
scanpy/experimental/pp/_highly_variable_genes.py	63.46% <ø> (ø)
scanpy/experimental/pp/_normalization.py	95.06% <100.00%> (ø)
scanpy/external/pp/_bbknn.py	58.33% <100.00%> (+8.33%)	⬆️
scanpy/external/pp/_dca.py	58.33% <100.00%> (+8.33%)	⬆️
scanpy/external/pp/_harmony_integrate.py	86.66% <100.00%> (+2.05%)	⬆️
scanpy/external/pp/_hashsolo.py	89.74% <100.00%> (+0.17%)	⬆️
scanpy/external/pp/_scanorama_integrate.py	88.88% <100.00%> (+0.88%)	⬆️
... and 58 more

[ilan-gold]

Nothing blocking, but I am pretty worried about the breaking changes. This isn't really my call though.