From 940e51ce8e4e5805459b9c79be85ce98c0f51c48 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Sat, 1 Aug 2026 07:00:08 +0000 Subject: [PATCH 1/2] test: remove redundant test_docstring_consistent_parameters --- tests/test_api/test_synchronous.py | 93 +----------------------------- 1 file changed, 1 insertion(+), 92 deletions(-) diff --git a/tests/test_api/test_synchronous.py b/tests/test_api/test_synchronous.py index 9b15ec32f6..9ac216d882 100644 --- a/tests/test_api/test_synchronous.py +++ b/tests/test_api/test_synchronous.py @@ -1,16 +1,12 @@ from __future__ import annotations -from typing import TYPE_CHECKING, Any, Final +from typing import Final import pytest from numpydoc.docscrape import NumpyDocString -import zarr from zarr.api import asynchronous, synchronous -if TYPE_CHECKING: - from collections.abc import Callable - MATCHED_EXPORT_NAMES: Final[tuple[str, ...]] = tuple( sorted(set(synchronous.__all__) | set(asynchronous.__all__)) ) @@ -39,90 +35,3 @@ def test_docstrings_match(callable_name: str) -> None: if a != b: mismatch.append((idx, (a, b))) assert mismatch == [] - - -@pytest.mark.parametrize( - ("parameter_name", "array_creation_routines"), - [ - pytest.param( - ("store", "path"), - ( - asynchronous.create_array, - synchronous.create_array, - asynchronous.create_group, - synchronous.create_group, - zarr.AsyncGroup.create_array, - zarr.Group.create_array, - ), - id="store-path-create_array_group", - ), - pytest.param( - ( - "store", - "path", - ), - ( - asynchronous.create, - synchronous.create, - zarr.Group.create, - ), - id="store-path-create", - ), - pytest.param( - ( - ( - "filters", - "codecs", - "compressors", - "compressor", - "chunks", - "shape", - "dtype", - "shardsfill_value", - ) - ), - ( - asynchronous.create, - synchronous.create, - asynchronous.create_array, - synchronous.create_array, - zarr.AsyncGroup.create_array, - zarr.Group.create_array, - ), - id="encoding-params-create_and_array", - ), - ], -) -def test_docstring_consistent_parameters( - parameter_name: str, array_creation_routines: tuple[Callable[[Any], Any], ...] -) -> None: - """ - Tests that array and group creation routines document the same parameters consistently. - This test inspects the docstrings of sets of callables and generates two dicts: - - - a dict where the keys are parameter descriptions and the values are the names of the routines with those - descriptions - - a dict where the keys are parameter types and the values are the names of the routines with those types - - If each dict has just 1 value, then the parameter description and type in the docstring must be - identical across different routines. But if these dicts have multiple values, then there must be - routines that use the same parameter but document it differently, which will trigger a test failure. - """ - descs: dict[tuple[str, ...], tuple[str, ...]] = {} - types: dict[str, tuple[str, ...]] = {} - for routine in array_creation_routines: - key = f"{routine.__module__}.{routine.__qualname__}" - docstring = NumpyDocString(routine.__doc__) - param_dict = {d.name: d for d in docstring["Parameters"]} - if parameter_name in param_dict: - val = param_dict[parameter_name] - if tuple(val.desc) in descs: - descs[tuple(val.desc)] = descs[tuple(val.desc)] + (key,) - else: - descs[tuple(val.desc)] = (key,) - if val.type in types: - types[val.type] = types[val.type] + (key,) - else: - types[val.type] = (key,) - assert len(descs) <= 1 - assert len(types) <= 1 From 0ce5c265c92d5cb4d5f66712b746e0ecd9b1dba3 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Sat, 1 Aug 2026 09:45:48 +0000 Subject: [PATCH 2/2] restore and improve test --- tests/test_api/test_synchronous.py | 112 ++++++++++++++++++++++++++++- 1 file changed, 111 insertions(+), 1 deletion(-) diff --git a/tests/test_api/test_synchronous.py b/tests/test_api/test_synchronous.py index 9ac216d882..1a7ee43b2a 100644 --- a/tests/test_api/test_synchronous.py +++ b/tests/test_api/test_synchronous.py @@ -1,12 +1,16 @@ from __future__ import annotations -from typing import Final +from typing import TYPE_CHECKING, Any, Final import pytest from numpydoc.docscrape import NumpyDocString +import zarr from zarr.api import asynchronous, synchronous +if TYPE_CHECKING: + from collections.abc import Callable + MATCHED_EXPORT_NAMES: Final[tuple[str, ...]] = tuple( sorted(set(synchronous.__all__) | set(asynchronous.__all__)) ) @@ -35,3 +39,109 @@ def test_docstrings_match(callable_name: str) -> None: if a != b: mismatch.append((idx, (a, b))) assert mismatch == [] + + +# NOTE: this test used to always pass silently due to a bug — it compared a +# tuple like ("store", "path") against a dict keyed by single names, so the +# check never actually ran. Fixed by looping over each name separately. +# Now that it runs for real, it fails: the docstrings really are inconsistent +# across create/create_array/create_group/Group.create_array. Marked xfail +# for now so CI stays green but the issue is tracked, not forgotten. +# See #4225 +@pytest.mark.xfail( + reason=( + "Docstrings for shared parameters (store, path, filters, codecs, " + "compressors, compressor, chunks, shape, dtype, shards, fill_value) " + "are inconsistent across create/create_array/create_group/" + "Group.create_array. Test was previously a silent no-op due to a bug; " + "now fixed and failing as expected. See #XXXX." + ), + strict=True, +) +@pytest.mark.parametrize( + ("parameter_name", "array_creation_routines"), + [ + pytest.param( + ("store", "path"), + ( + asynchronous.create_array, + synchronous.create_array, + asynchronous.create_group, + synchronous.create_group, + zarr.AsyncGroup.create_array, + zarr.Group.create_array, + ), + id="store-path-create_array_group", + ), + pytest.param( + ( + "store", + "path", + ), + ( + asynchronous.create, + synchronous.create, + zarr.Group.create, + ), + id="store-path-create", + ), + pytest.param( + ( + ( + "filters", + "codecs", + "compressors", + "compressor", + "chunks", + "shape", + "dtype", + "shards", + "fill_value", + ) + ), + ( + asynchronous.create, + synchronous.create, + asynchronous.create_array, + synchronous.create_array, + zarr.AsyncGroup.create_array, + zarr.Group.create_array, + ), + id="encoding-params-create_and_array", + ), + ], +) +def test_docstring_consistent_parameters( + parameter_name: tuple[str, ...], array_creation_routines: tuple[Callable[[Any], Any], ...] +) -> None: + """ + Tests that array and group creation routines document the same parameters consistently. + This test inspects the docstrings of sets of callables and generates two dicts: + + - a dict where the keys are parameter descriptions and the values are the names of the routines with those + descriptions + - a dict where the keys are parameter types and the values are the names of the routines with those types + + If each dict has just 1 value, then the parameter description and type in the docstring must be + identical across different routines. But if these dicts have multiple values, then there must be + routines that use the same parameter but document it differently, which will trigger a test failure. + """ + descs: dict[tuple[str, ...], tuple[str, ...]] = {} + types: dict[str, tuple[str, ...]] = {} + for routine in array_creation_routines: + key = f"{routine.__module__}.{routine.__qualname__}" + docstring = NumpyDocString(routine.__doc__) + param_dict = {d.name: d for d in docstring["Parameters"]} + for name in parameter_name: + if name in param_dict: + val = param_dict[name] + if tuple(val.desc) in descs: + descs[tuple(val.desc)] = descs[tuple(val.desc)] + (key,) + else: + descs[tuple(val.desc)] = (key,) + if val.type in types: + types[val.type] = types[val.type] + (key,) + else: + types[val.type] = (key,) + assert len(descs) <= 1 + assert len(types) <= 1