Skip to content

fix(tests): repair docstring-consistency test and align create_array docs - #4417

Merged
d-v-b merged 3 commits into
zarr-developers:mainfrom
guhou-hvi:fix/docstring-consistent-params
Sep 30, 2026
Merged

d-v-b merged 3 commits into
zarr-developers:mainfrom
guhou-hvi:fix/docstring-consistent-params

Conversation

@guhou-hvi

Copy link
Copy Markdown
Contributor

Problem

test_docstring_consistent_parameters in tests/test_api/test_synchronous.py silently passed regardless of docstring mismatches:

  1. A typo concatenated shards, fill_value into a single string shardsfill_value, so neither parameter was checked.
  2. The outer parameter_name is a tuple, but the body did if parameter_name in param_dict: — looking up the tuple as a key, which is always False.

Fixes #4225.

Changes

  • Test: split the concatenated parameter, iterate over each name in the tuple so the assertions run.
  • Docstrings: align filters, compressors, chunks, shape, dtype (description and type) across core.array.create_array, api.synchronous.create_array, AsyncGroup.create_array and Group.create_array.
  • group.py: normalize RST double-backticks ( ) to markdown single-backticks in the three create_array` docstring blocks.
  • array.py / synchronous.py: remove stray blank line in filters paragraph.
  • Add changelog fragment.

Verification

pytest tests/test_api/test_synchronous.py -v  # 31 passed
ruff check src/ tests/                        # All checks passed!

@d-v-b

d-v-b commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

🤖 AI text below 🤖

The changelog fragment changes/4225.bugfix.md should be renamed to changes/4417.misc.md. changes/README.md asks for fragments named after the pull request number, and towncrier renders the number as a link to /pull/<number> (issue_format in pyproject.toml). As named, the release notes would link to /pull/4225, which is the issue this fixes. misc rather than bugfix is suggested because the change fixes a test and aligns docstrings, with no change to how zarr behaves.

git mv changes/4225.bugfix.md changes/4417.misc.md

This PR is planned for the 3.4.1 patch release.

@d-v-b d-v-b added this to the 3.4.1 milestone Sep 29, 2026
@codecov

codecov Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.44%. Comparing base (5e3d8a4) to head (08facc5).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #4417   +/-   ##
=======================================
  Coverage   94.44%   94.44%           
=======================================
  Files          93       93           
  Lines       13221    13221           
=======================================
  Hits        12487    12487           
  Misses        734      734           
Files with missing lines Coverage Δ
src/zarr/api/asynchronous.py 96.32% <ø> (ø)
src/zarr/api/synchronous.py 92.95% <ø> (ø)
src/zarr/core/array.py 98.09% <ø> (ø)
src/zarr/core/group.py 95.43% <ø> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

The rebuilt test now parametrizes one case per documented parameter over
the create_array variants (module-level, AsyncGroup, Group, Group.create),
deriving the parameter list from the docstrings so new parameters are
checked automatically; `name` is the only deliberate exemption.

Docstring fixes surfaced by the widened check:
- `data` was malformed on Group.create/Group.create_array and missing on
  AsyncGroup.create_array
- `chunk_key_encoding` and `config` documented types that differ from the
  signatures (ChunkKeyEncodingLike, ArrayConfigLike)
- `overwrite` now says what happens (keys under the path are deleted) in
  all variants instead of "all existing paths in the store"
- stray `}}` in the chunk key encoding examples
- `VariableLengthUTF8` listed twice where `VariableLengthBytes` was meant
- dangling "in zarr.config." fragment after the v2 default-compressor line
- Group.create used unresolved `[zarr.config][]` cross-refs

Rename the changelog fragment to the pull request number.

Assisted-by: ClaudeCode:claude-fable-5-1
@d-v-b

d-v-b commented Sep 30, 2026

Copy link
Copy Markdown
Contributor

thanks for this @guhou-hvi, I pushed a few additional changes on top of yours:

  • data was malformed on Group.create and Group.create_array (numpydoc read the description as the type) and missing from AsyncGroup.create_array.
  • chunk_key_encoding and config documented types that differ from the signatures; they now say ChunkKeyEncodingLike and ArrayConfigLike.
  • overwrite now describes what actually happens in every variant: existing keys under the path are deleted. The module-level docstring previously said all paths in the store are deleted, which is not what _prepare_overwrite does.
  • A stray closing brace in the chunk key encoding examples, VariableLengthUTF8 listed twice where VariableLengthBytes was meant, and a dangling "in zarr.config." sentence after the Zarr format 2 default-compressor line, all in lines this PR was already rewriting.
  • Group.create used the [zarr.config][] cross-ref form; it now matches the other blocks.

@d-v-b
d-v-b merged commit 9e631c6 into zarr-developers:main Sep 30, 2026
41 checks passed
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.

Fix broken docstring-consistency test - it reveals mismatches in parameter docs

2 participants