Repository navigation
Refactor: split utils.py (4454 lines) into _validate.py / _color.py / _geometry.py and finish _datashader.py extraction #696
Description
Summary
src/spatialdata_plot/pl/utils.py is 4454 lines and mixes several unrelated concerns. Roughly ~3400 of those lines are two cohesive concerns (validation, color resolution) interleaved with everything else. Splitting them into sibling modules would massively improve navigability and shrink the blast radius of changes — with essentially no behavioral risk.
Why now
- Any contributor touching one validation message or color helper must scroll a 4454-line file and risks editing adjacent unrelated code.
- There is no import cycle in the extraction direction:
utils.pyimports only fromrender_params(a leaf) plus third-party libs — never fromrender.py/basic.py. The consumers import from utils. - There is an established precedent:
pl/_palette.pyandpl/_datashader.pyare already self-contained sibling modules. - All symbols involved are private (
_foo) — no public API surface to preserve.
Proposed split
| New module | Moves (approx lines) | Examples |
|---|---|---|
pl/_validate.py |
~1400 | _type_check_params (L2660), _validate_*_render_params ×5 (L3106–3835), _validate_show_parameters (L2483), _validate_col_for_column_table, uniqueness/shadow checks |
pl/_color.py |
~1370 | _set_color_source_vec (L1265), _map_color_seg (L1486), _extract_colors_from_table_uns (L1689), categorical-mapping chain (L1616–1940), _color_vector_to_rgba, _get_linear_colormap, _set_outline |
pl/_geometry.py |
~460 | _get_collection_shape (L601), _convert_shapes (L4273), pathpatch helpers |
(finish) pl/_datashader.py |
~234 | the canvas/aggregate helpers still in utils.py (L3910–4451) that _datashader.py currently back-imports — the only near-cycle in the repo. Also fixes the _datshader_get_how_kw_for_spread typo. |
After these moves, utils.py is left as a ~1000-line grab-bag of genuinely cross-cutting helpers (figure/axes, coord/extent, table extraction).
Risk / effort
Mechanical: each move is an import-path swap in render.py/basic.py/_datashader.py (their import blocks already group symbols by concern). No cycle, no public surface, covered by existing tests. Effort: medium · Risk: low. Best done as one module per PR.
Notes
- The two mega-functions being relocated (
_get_collection_shape,_convert_shapes,_type_check_params,_set_color_source_vec) are themselves decomposition candidates, but that is out of scope here — this issue is the relocation only, to keep diffs reviewable. Decomposition can follow once each lives in a smaller, single-concern file.
Part of a maintainability/refactor audit of main.
Activity
refactor(utils): extract color resolution into _color.py (#696)
refactor(utils): extract parameter validation into _validate.py (#696)
refactor(utils): move 6 cross-cutting helpers from _color to utils (#696
fix(utils): keep set_zero_in_cmap_to_transparent public