refactor warnings

[d-v-b]

closes #3096

this PR adds zarr-specific subclasses of FutureWarning and DeprecationWarning, so that we can expose routines for silencing future / deprecation warnings specifically emitted by zarr-python.

This PR is a draft until I add the silencing routines later in this PR.

[dstansby]

👍 to having our own zarr warning sub-classes, I think I'm 👎 on having some of our own warning silencing helpers, but depends on what the proposal is I guess. So would be good to have separate PRs for those.

[d-v-b]

I amended the PR description to remove the goal of providing top-level functions for users to silence zarr warnings. For now, users can use the built-in warnings library to control warnings.

[codecov]

Codecov Report

❌ Patch coverage is 70.90909% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.54%. Comparing base (e985f1d) to head (61ff062).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/zarr/api/asynchronous.py	33.33%	12 Missing ⚠️
src/zarr/_compat.py	0.00%	1 Missing ⚠️
src/zarr/convenience.py	0.00%	1 Missing ⚠️
src/zarr/creation.py	0.00%	1 Missing ⚠️
src/zarr/testing/__init__.py	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3098      +/-   ##
==========================================
+ Coverage   94.40%   94.54%   +0.13%     
==========================================
  Files          78       78              
  Lines        9401     9419      +18     
==========================================
+ Hits         8875     8905      +30     
+ Misses        526      514      -12     

Files with missing lines	Coverage Δ
src/zarr/api/synchronous.py	92.95% <100.00%> (+0.10%)	⬆️
src/zarr/codecs/transpose.py	89.47% <ø> (ø)
src/zarr/core/array.py	97.10% <100.00%> (-0.33%)	⬇️
src/zarr/core/buffer/gpu.py	90.00% <100.00%> (+0.12%)	⬆️
src/zarr/core/chunk_grids.py	91.58% <100.00%> (+0.07%)	⬆️
src/zarr/core/codec_pipeline.py	93.13% <100.00%> (-0.96%)	⬇️
src/zarr/core/common.py	93.38% <100.00%> (+0.05%)	⬆️
src/zarr/core/dtype/common.py	85.54% <100.00%> (ø)
src/zarr/core/group.py	95.03% <100.00%> (+0.22%)	⬆️
src/zarr/core/metadata/v2.py	91.27% <100.00%> (+0.05%)	⬆️
... and 9 more

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[d-v-b]

this will allow users who are tired of seeing zarr-specific warnings to suppress them.

[dstansby]

I milestoned as 3.2.0, but I guess this isn't breaking (because the new warnings subclass the old warnings), so could go in 3.1.2 instead?

[dstansby]

Code changes look good overall, but:

• Tests need fixing
• I think there's more warnings in the list of our warning filters that should be converted to the new zarr-specific warnings
• The new warning classes shold be included in the API docs

[d-v-b]

I removed almost all the ignored warnings from pyproject.toml, at the cost of inserting a bunch of explicit with pytest.warns() statements throughout our tests. This was useful because it revealed how many warnings zarr emits during normal usage. For consolidated metadata in particular I think we need to rethink emitting a warning every time its used. I don't think this feature is typically used by individual users but rather libraries like xarray, in which case the best way to convey the off-spec-ness of consolidated metadata is via documentation.

[d-v-b]

we should also consider changing our ZipStore implementation to hide the UserWarning emitted whenever a key is modified.

[TomAugspurger]

removed almost all the ignored warnings from pyproject.toml, at the cost of inserting a bunch of explicit with pytest.warns() statements throughout our tests

Thanks for doing this. I was going to suggest that, but didn't want to assign work to you that's only tangentially related to the PR. I think that being explicit in the tests about where warnings are raised is a good practice.

[d-v-b]

consistent with my "test code models user code" theory, excluding every warning individually from the tests has given me a newfound appreciation for all the warnings zarr-python emits on a regular basis

[d-v-b]

I don't think the coverage report is very useful here. If we discount it, I think this is ready to go

[dstansby]

One final comment on the release note, otherwise 👍 Once that's fixed, feel free to self-merge