[sylvesterkaczmarek]

Closes #4335.

CellBrowser stores the supplied export directory in categorical color-file references, then resolves those references relative to the configuration directory. A relative data_dir can therefore produce a duplicated directory prefix and fail to find a color file that was just written.

Pass an absolute data directory to both export and build, matching the existing working absolute-input behavior. Symlink and .. semantics, forwarded arguments and the wrapper's deprecation remain unchanged. The release note explains that existing configurations are preserved: affected references need correction or careful regeneration with custom settings saved. Absolute color references also need updating if the raw export directory moves.

Validation

• Final host run with default pytest plugins: 41 passed, including all 11 new cases. Candidate hashes were stable.
• Independent review reran 11 focused and 41 adjacent checks. The exact original wrapper fails five new cases, including the real relative color lookup; the absolute integration control passes.
• Real CellBrowser 1.2.22 integration checks color mappings, expression, metadata, coordinates, configuration and HTML output. Current-main tests bypass only its unrelated non-spatial private-API import, block reference downloads/servers and select built-in Python I/O fallbacks.
• A separate Scanpy 1.12.5 compatibility probe uses the real unmodified spatial helper: original relative export fails; original absolute and both corrected paths pass. This is separate from current-main validation.
• Ruff lint, formatting and whitespace checks pass. Independent review found no implementation defect; its documentation finding is addressed in the release note.

Previously generated broken configurations are not repaired automatically. CellBrowser's independent spatial-import and shell path-quoting defects are outside this change. Full repository tests, documentation build, native Windows and upstream CI were not run.

Post-submission verification

The release-note fragment has been renamed to 4495.fix.md. The targeted tests were independently rerun after the filename change and passed: 11 tests. Human review of the latest changes remains pending.

LLM usage

• LLM or coding agent used

• If one was used, I, a human, have reviewed, understood and tested every changed line

• Closes sc.external.exporting.cellbrowser: cellbrowser_raw_data\sample_colors.tsv does not exist, skipping it An exception has occurred, use %tb to see the full traceback. #4335

• Tests included: path forwarding and optional real CellBrowser integration.

• Release notes not necessary because:

A release note is included as 4495.fix.md, matching the assigned PR number.

[read-the-docs-business]

Documentation build overview

📚 scanpy | 🛠️ Build #4691912 | 📁 Comparing c8465dc against latest (117682e)

  🔍 Preview build  

3 files changed

± release-notes/index.html
± api/generated/scanpy.pp.calculate_qc_metrics.html
± api/generated/scanpy.settings.html

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.13%. Comparing base (117682e) to head (c8465dc).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4495   +/-   ##
=======================================
  Coverage   85.13%   85.13%           
=======================================
  Files         138      138           
  Lines       12247    12247           
=======================================
  Hits        10427    10427           
  Misses       1820     1820           

Flag	Coverage Δ
hatch-test.low-vers	78.66% <ø> (ø)
hatch-test.pre	84.92% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/scanpy/external/exporting.py	21.80% <ø> (ø)