Skip to content

docstring cleanup #3390

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: main
Choose a base branch
from

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.71%. Comparing base (6a546d6) to head (184c7aa).

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.66%   94.71%   +0.04%     
==========================================
  Files          79       79              
  Lines        9444     9437       -7     
==========================================
- Hits         8940     8938       -2     
+ Misses        504      499       -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.62% <ø> (+0.51%) ⬆️
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