[codex] Modernize Python compatibility, dependencies, tests, and docs

[tuhulab]

Summary

This PR modernizes QUICHE for current Python tooling while preserving the existing public API surface (quiche.pp, quiche.tl, quiche.pl) and stabilizing install/test workflows.

It addresses compatibility and maintenance pain points caused by old grammar-era packaging metadata, outdated pins, and eager imports of heavy optional dependencies.

Problem and user impact

Before this change:

• Project metadata used legacy fields and did not declare runtime dependencies in pyproject.toml.
• Python support targeted only 3.7-3.9.
• Import/runtime paths could fail early when optional heavy dependencies were not installed.
• No automated test suite or CI matrix existed to protect compatibility changes.

This made installation brittle, especially for users on modern Python versions, and increased regression risk.

Root causes

• Packaging configuration was incomplete for modern PEP 621 workflows.
• Optional stacks (scanpy/squidpy/pertpy/muon/sketchKH/R-driven workflows) were imported eagerly.
• A few runtime bugs (parameter mismatch and row-alignment issues) were hidden due limited test coverage.

What this PR changes

1) Packaging and dependency modernization

• Modernized pyproject.toml metadata to PEP 621 format.
• Declared explicit runtime dependencies.
• Set supported Python range to >=3.10,<3.13.
• Added extras:
  • plot
  • full
  • dev
• Updated venv_quiche.yml to align with Python 3.10-3.12 and modern stack versions.
• Kept R dependencies in conda for edgeR/R workflows.

2) Compatibility and correctness fixes (API-preserving)

• Replaced bare except: handlers with explicit handling.
• Removed outdated boolean-style checks.
• Added optional dependency guards with actionable ImportErrors.
• Fixed concrete runtime bugs:
  • compute_spatial_niches(khop=...) now passes k correctly.
  • compute_spatial_niches now preserves row alignment via obs_names.
  • Fixed chained assignment in annotation update path.
  • Fixed undefined metric variable in plotting defaults.
  • Fixed list-color handling in generate_colors.
  • Fixed incorrect call-site argument in plotting metadata helper.

3) Test suite + CI

• Added tests/ with deterministic synthetic fixtures and coverage for:
  • imports
  • preprocessing
  • graph helpers
  • metrics helpers
  • QUICHE smoke paths
• Added GitHub Actions matrix for Python 3.10/3.11/3.12.

4) Documentation

• Updated README installation guidance for pip extras and conda/R workflows.
• Added quick smoke-test command.
• Added known limitations for heavy optional stacks.
• Added migration report and changelog entry.

Validation performed

Local validation on Python 3.11:

• pytest -q -> 19 passed
• pytest --cov=quiche --cov-report=term-missing -> 19 passed

(One pandas FutureWarning remains in an existing statistical helper; behavior is unaffected.)

Backward compatibility statement

• Public module/function/class import paths are preserved.
• Heavy optional workflows now fail fast with clear install guidance instead of breaking base imports.
• pip install . stays lightweight; conda remains the recommended route for R-backed analysis.

Commit structure

• packaging/deps: modernize metadata and env
• code-compat: guard optional deps and fix runtime bugs
• tests-ci: add synthetic tests and py3.10-3.12 matrix
• docs: document migration, install paths, and limits

[AtlasMaroc]

@tuhulab i tried using your suggestion for installing the full environment using pip install .e [full], but i got an error regarding version availability such as muon !

[jranek]

Wow, thank you @tuhulab for all of these updates, this is super helpful!! I will work on reviewing the changes.

As a note, pip install .[full] breaks for me due to a sketchKH dependency issue. We should only be using sketchKH >= 0.1.2, which requires python>=3.6, <3.10 which is currently incompatible with these updates. I will work on updating the python dependencies in the sketchKH package to enable the python modernization here.

Jolene

[jranek]

Should now be resolved with sketchKH==0.1.3