Skip to content

Conversation

d-v-b
Copy link
Contributor

@d-v-b d-v-b commented Aug 19, 2025

This PR will do two things:

The reason for two things in this PR, instead of 1, is that changing docstrings in zarr python is incredibly tedious because we have a lot of similar functions, with very similar docstrings: we have asynchronous.create, synchronous.create, asynchronous.create_array, synchronous.create_array, Group.create_array, AsyncGroup.create_array, init_array, from_array, ... So any PR that changes docstrings needs to be sure that all relevant docstrings are updated. This is more work, but it's part of the spirit of "leaving things better than you found it".

edit: this PR grew in scope, but not complexity. So I think it's fine to keep this in one PR.
Here's a list of the changes:

  • remove outdated references to configuration options for controlling codecs (thereby closing DOC: Configuration value 'array.v3_default_compressors' has been removed, but is still documented #3389)
  • Ensure that all docstrings for store parameters are consistent. They are all now correctly reporting the type of the parameter as StoreLike
  • Test that array creation function/methods which use the same parameters have those parameters declared identically in docstrings. We could expand these tests as needed to include more functions, but I wanted to focus on array creation routines for now because removing the outdated config content touched the docstrings for compressor, serializer, and filters extensively, so these needed to be tested.
  • Where necessary, change docstrings to pass the above tests.

One specific change: I normalized a large number of store docstring declarations to store : StoreLike or None, default=None (obviously this is only for functions where the store parameter is nullable). This is consistent with NumpyDoc and more informative that just saying "StoreLike, optional", because the latter does not convey what the default value is.

@github-actions github-actions bot added the needs release notes Automatically applied to PRs which haven't added release notes label Aug 19, 2025
Copy link

codecov bot commented Aug 20, 2025

Codecov Report

❌ Patch coverage is 50.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 94.75%. Comparing base (c9509ee) to head (7d93490).

Files with missing lines Patch % Lines
src/zarr/core/group.py 50.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #3390      +/-   ##
==========================================
+ Coverage   94.70%   94.75%   +0.04%     
==========================================
  Files          79       79              
  Lines        9532     9525       -7     
==========================================
- Hits         9027     9025       -2     
+ Misses        505      500       -5     
Files with missing lines Coverage Δ
src/zarr/api/asynchronous.py 89.96% <ø> (ø)
src/zarr/api/synchronous.py 92.95% <ø> (ø)
src/zarr/core/array.py 97.94% <ø> (+0.49%) ⬆️
src/zarr/storage/_common.py 92.43% <ø> (ø)
src/zarr/core/group.py 95.03% <50.00%> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@d-v-b d-v-b marked this pull request as ready for review August 20, 2025 16:22
@d-v-b d-v-b changed the title doc/undocument deprecated config docstring cleanup Aug 20, 2025
@d-v-b d-v-b requested a review from a team August 20, 2025 16:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
needs release notes Automatically applied to PRs which haven't added release notes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant