Skip to content

Fix docstring parameter names that do not match the signatures - #1254

Open
VenishPaneliya wants to merge 1 commit into
scverse:mainfrom
VenishPaneliya:docstring-param-names
Open

VenishPaneliya wants to merge 1 commit into
scverse:mainfrom
VenishPaneliya:docstring-param-names

Conversation

@VenishPaneliya

@VenishPaneliya VenishPaneliya commented Sep 21, 2026

Copy link
Copy Markdown

Three docstrings name a parameter that the function does not have. In two of the three the name is the spelling used by a sibling function, so these look like drift rather than an original mistake.

1. rasterize_binsreturn_regions_as_labels vs return_region_as_labels

rasterize_bins() takes return_region_as_labels (singular), while rasterize() takes return_regions_as_labels (plural). The rasterize_bins docstring uses the plural form as its parameter heading, even though its own value_key entry already says:

Ignored if return_region_as_labels is True.

The same plural form is repeated in rasterize_bins_link_table_to_labels, where it is given to the reader as an instruction:

This function should be called after having rasterized the bins (calling rasterize_bins() with return_regions_as_labels=True) …

rasterize_bins has no return_regions_as_labels parameter and takes no **kwargs, so following that sentence literally raises TypeError: rasterize_bins() got an unexpected keyword argument 'return_regions_as_labels'.

2. SpatialData.subsetfilter_table vs filter_tables

The signature is subset(element_names, filter_tables=True, include_orphan_tables=False), but the Parameters section documents filter_table. The singular filter_table is the query functions' spelling (bounding_box_query, polygon_query). The include_orphan_tables entry in the very same docstring already refers to filter_tables correctly, so the two halves disagree with each other.

3. validate_axesaxis vs axes

validate_axes(axes) documents axis, which is the parameter of validate_axis_name directly above it.


All three are docstrings only, no behaviour change, and the singular/plural spellings used elsewhere in the codebase are left untouched — only the entries that disagree with their own signature are corrected.

Checked with a source-level pass over each function: the parameter names in the Parameters section now equal the signature exactly.

function documented signature
validate_axes ['axes'] ['axes']
SpatialData.subset ['element_names', 'filter_tables', 'include_orphan_tables'] same
rasterize_bins [..., 'value_key', 'return_region_as_labels'] same

ruff check and ruff format --check are clean on all three files.

Three docstrings name a parameter the function does not have. In two of
them the name is the spelling used by a sibling function, so the docs
drifted rather than being wrong from the start:

- `validate_axes(axes)` documents `axis`, which is the parameter of the
  neighbouring `validate_axis_name`.
- `SpatialData.subset(filter_tables=...)` documents `filter_table`, the
  spelling used by the `*_query` functions. The same docstring already
  refers to `filter_tables` correctly when describing
  `include_orphan_tables`.
- `rasterize_bins(return_region_as_labels=...)` documents
  `return_regions_as_labels`, which is `rasterize`'s spelling. Its own
  `value_key` entry already refers to `return_region_as_labels`.

`rasterize_bins_link_table_to_labels` repeats the last one in prose and
tells the reader to call `rasterize_bins()` with
`return_regions_as_labels=True`; `rasterize_bins` has no such parameter
and takes no `**kwargs`, so that call raises `TypeError`.

Docstrings only, no behaviour change.
@codecov

codecov Bot commented Sep 21, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.40%. Comparing base (65dc73e) to head (93057e5).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1254   +/-   ##
=======================================
  Coverage   91.40%   91.40%           
=======================================
  Files          53       53           
  Lines        8381     8381           
=======================================
  Hits         7661     7661           
  Misses        720      720           
Files with missing lines Coverage Δ
src/spatialdata/_core/operations/rasterize_bins.py 94.81% <ø> (ø)
src/spatialdata/_core/spatialdata.py 93.36% <ø> (ø)
src/spatialdata/models/_utils.py 88.95% <ø> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant