Skip to content

Commit 5a4f169

Browse files
committed
Address review on #4494: deprecate instead of reject
- parse_attributes checks Mapping rather than dict and emits ZarrDeprecationWarning for out-of-contract input instead of raising; dict(data) still runs so accepted values behave exactly as before - parse_shapelike loses the reject_bool kwarg; bools now warn (ZarrDeprecationWarning) wherever they parse, ahead of rejection once the deprecation window elapses - dimension_names string/bytes exclusion and storage_transformers mapping exclusion unchanged - tests updated: bools and non-mapping attributes are covered by pytest.warns cases; repair fixtures reading stored true chunks keep their assertions
1 parent bbf6b2d commit 5a4f169

8 files changed

Lines changed: 67 additions & 36 deletions

File tree

‎changes/4494.bugfix.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Tighten array metadata field validation: ``shape`` rejects booleans, ``attributes`` requires a dict with string keys, ``dimension_names`` rejects a bare string, and ``storage_transformers`` rejects a mapping.
1+
Tighten array metadata field validation: `dimension_names` rejects a bare string and `storage_transformers` rejects a mapping. `shape` fields that contain booleans and `attributes` fields that are not mappings with string keys still parse as before, but emit a `ZarrDeprecationWarning` ahead of rejection in a future release.

‎src/zarr/core/common.py‎

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121

2222
from zarr.core.config import config as zarr_config
2323
from zarr.core.json_parse import convert, parse_field
24-
from zarr.errors import ZarrRuntimeWarning
24+
from zarr.errors import ZarrDeprecationWarning, ZarrRuntimeWarning
2525

2626
if TYPE_CHECKING:
2727
from collections.abc import Awaitable, Callable, Iterator
@@ -211,18 +211,21 @@ def parse_named_configuration(
211211
return name_parsed, configuration_parsed
212212

213213

214-
def parse_shapelike(data: ShapeLike, *, reject_bool: bool = False) -> tuple[int, ...]:
214+
def _warn_bool_shapelike() -> None:
215+
msg = (
216+
"Boolean values in shape-like fields are deprecated and will be "
217+
"rejected in a future release."
218+
)
219+
warnings.warn(msg, ZarrDeprecationWarning, stacklevel=3)
220+
221+
222+
def parse_shapelike(data: ShapeLike) -> tuple[int, ...]:
215223
"""
216224
Parse a shape-like input into an explicit shape.
217-
218-
``reject_bool`` controls whether JSON ``true``/``false`` values are rejected.
219-
Stored chunk sizes written as ``true`` by older versions of this library are
220-
still read leniently, so the default is ``False``; document ``shape`` fields
221-
pass ``reject_bool=True``.
222225
"""
223-
if reject_bool and isinstance(data, bool):
224-
msg = f"Expected an integer or an iterable of integers. Got {data} instead."
225-
raise TypeError(msg)
226+
if isinstance(data, bool):
227+
# bools are int subclasses; accept them for now but deprecate
228+
_warn_bool_shapelike()
226229
if isinstance(data, int | np.integer):
227230
if data < 0:
228231
raise ValueError(f"Expected a non-negative integer. Got {data} instead")
@@ -233,11 +236,11 @@ def parse_shapelike(data: ShapeLike, *, reject_bool: bool = False) -> tuple[int,
233236
msg = f"Expected an integer or an iterable of integers. Got {data} instead."
234237
raise TypeError(msg) from e
235238

236-
if not all(isinstance(v, int | np.integer) for v in data_tuple) or (
237-
reject_bool and any(isinstance(v, bool) for v in data_tuple)
238-
):
239+
if not all(isinstance(v, int | np.integer) for v in data_tuple):
239240
msg = f"Expected an iterable of integers. Got {data} instead."
240241
raise TypeError(msg)
242+
if any(isinstance(v, bool) for v in data_tuple):
243+
_warn_bool_shapelike()
241244
if not all(v > -1 for v in data_tuple):
242245
msg = f"Expected all values to be non-negative. Got {data} instead."
243246
raise ValueError(msg)

‎src/zarr/core/metadata/common.py‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
from __future__ import annotations
22

3-
from typing import TYPE_CHECKING
3+
import warnings
4+
from collections.abc import Mapping
5+
from typing import TYPE_CHECKING, cast
6+
7+
from zarr.errors import ZarrDeprecationWarning
48

59
if TYPE_CHECKING:
610
from zarr.core.common import JSON
@@ -9,6 +13,11 @@
913
def parse_attributes(data: object) -> dict[str, JSON]:
1014
if data is None:
1115
return {}
12-
if not isinstance(data, dict) or not all(isinstance(k, str) for k in data):
13-
raise TypeError(f"Expected dict with string keys. Got {type(data)} instead.")
14-
return dict(data)
16+
if not isinstance(data, Mapping) or not all(isinstance(k, str) for k in data):
17+
msg = (
18+
"Attributes metadata that is not a mapping with string keys is "
19+
"deprecated and will be rejected in a future release. "
20+
f"Got {data!r}."
21+
)
22+
warnings.warn(msg, ZarrDeprecationWarning, stacklevel=2)
23+
return dict(cast("Mapping[str, JSON]", data))

‎src/zarr/core/metadata/v2.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ def __init__(
9393
"""
9494
Metadata for a Zarr format 2 array.
9595
"""
96-
shape_parsed = parse_shapelike(shape, reject_bool=True)
96+
shape_parsed = parse_shapelike(shape)
9797
chunks_parsed = parse_chunks(chunks, shape_parsed)
9898
compressor_parsed = parse_compressor(compressor)
9999
order_parsed = parse_indexing_order(order)

‎src/zarr/core/metadata/v3.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -545,7 +545,7 @@ def __init__(
545545
Because the class is a frozen dataclass, we set attributes using object.__setattr__
546546
"""
547547

548-
shape_parsed = parse_shapelike(shape, reject_bool=True)
548+
shape_parsed = parse_shapelike(shape)
549549
chunk_grid_parsed = parse_chunk_grid(chunk_grid)
550550
chunk_key_encoding_parsed = parse_chunk_key_encoding(chunk_key_encoding)
551551
dimension_names_parsed = parse_dimension_names(dimension_names)

‎tests/test_common.py‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
product,
2222
)
2323
from zarr.core.config import parse_indexing_order
24+
from zarr.errors import ZarrDeprecationWarning
2425

2526
if TYPE_CHECKING:
2627
from typing import Any, Literal
@@ -224,12 +225,10 @@ def test_parse_shapelike_invalid_iterable_types(data: Any) -> None:
224225

225226

226227
@pytest.mark.parametrize(("data", "expected"), [(True, (1,)), ([True], (1,)), ((True, 1), (1, 1))])
227-
def test_parse_shapelike_reject_bool(data: Any, expected: tuple[int, ...]) -> None:
228-
"""With reject_bool=True, bools are not valid shape elements even though
229-
they are int subclasses. The default stays lenient for stored chunk fields."""
230-
with pytest.raises(TypeError, match="Expected an"):
231-
parse_shapelike(data, reject_bool=True)
232-
assert parse_shapelike(data) == expected
228+
def test_parse_shapelike_bool_deprecated(data: Any, expected: tuple[int, ...]) -> None:
229+
"""Bools still parse as ints for backward compatibility, but warn."""
230+
with pytest.warns(ZarrDeprecationWarning, match="Boolean values"):
231+
assert parse_shapelike(data) == expected
233232

234233

235234
@pytest.mark.parametrize("data", [(1, 2, 3, -1), (-10,)])

‎tests/test_metadata/test_repair.py‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
from zarr.core.metadata.v3 import RectilinearChunkGridMetadata, RegularChunkGridMetadata
2828
from zarr.core.sync import sync
2929
from zarr.dtype import Int16
30-
from zarr.errors import ZarrUserWarning
30+
from zarr.errors import ZarrDeprecationWarning, ZarrUserWarning
3131
from zarr.storage import LocalStore, MemoryStore, StorePath
3232
from zarr.storage._common import make_store_path
3333

@@ -518,7 +518,6 @@ def _sharding_chunk_shape(chunks: Any) -> tuple[tuple[int, ...], object]:
518518
(np.int64(4), (4,)),
519519
((np.int64(4),), (4,)),
520520
(np.array([4]), (4,)),
521-
((True,), (1,)),
522521
(range(4, 5), (4,)),
523522
],
524523
)
@@ -527,14 +526,23 @@ def test_chunk_shape_read_as_array_shape(
527526
) -> None:
528527
"""`ArrayV2Metadata` and `ShardingCodec` read their chunk shape as `parse_shapelike`
529528
reads an array shape: an integer or an iterable of integers, including NumPy
530-
integers and bools."""
529+
integers."""
531530
parsed, written = CHUNK_SHAPE_SITES[site](chunks)
532531
assert parsed == expected
533532
assert all(type(size) is int for size in parsed)
534533
assert written == expected
535534

536535

537-
@pytest.mark.parametrize("chunks", [(0,), (False,)])
536+
@pytest.mark.parametrize("site", CHUNK_SHAPE_SITES)
537+
def test_chunk_shape_bool_deprecated(site: str) -> None:
538+
"""A bool chunk size still reads as 1, but warns pending removal."""
539+
with pytest.warns(ZarrDeprecationWarning, match="Boolean values"):
540+
parsed, written = CHUNK_SHAPE_SITES[site]((True,))
541+
assert parsed == (1,)
542+
assert written == (1,)
543+
544+
545+
@pytest.mark.parametrize("chunks", [(0,)])
538546
def test_v2_chunk_size_zero_written_as_given(chunks: tuple[Any, ...]) -> None:
539547
"""`ArrayV2Metadata` accepts a chunk size of 0 and writes it back as given; reading
540548
a stored 0 is `zarr.core.metadata.repair`' business. `ShardingCodec` rejects one."""
@@ -543,6 +551,15 @@ def test_v2_chunk_size_zero_written_as_given(chunks: tuple[Any, ...]) -> None:
543551
assert metadata.to_dict()["chunks"] == (0,)
544552

545553

554+
def test_v2_chunk_size_false_written_as_given() -> None:
555+
"""A bool chunk size still reads and writes as before, but warns pending
556+
removal."""
557+
with pytest.warns(ZarrDeprecationWarning, match="Boolean values"):
558+
metadata = _v2_metadata((False,))
559+
assert metadata.chunks == (0,)
560+
assert metadata.to_dict()["chunks"] == (0,)
561+
562+
546563
@pytest.mark.parametrize("site", CHUNK_SHAPE_SITES)
547564
def test_chunk_shape_read_as_array_shape_rejects_negative(site: str) -> None:
548565
with pytest.raises(ValueError, match="Expected all values to be non-negative"):

‎tests/test_metadata/test_v3.py‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
MetadataValidationError,
3232
NodeTypeValidationError,
3333
UnknownCodecError,
34+
ZarrDeprecationWarning,
3435
)
3536

3637
if TYPE_CHECKING:
@@ -96,18 +97,20 @@ def test_parse_dimension_names_invalid(data: Any) -> None:
9697
parse_dimension_names(data)
9798

9899

99-
@pytest.mark.parametrize("data", [[], "str", 5])
100-
def test_parse_attributes_invalid(data: Any) -> None:
101-
"""Non-dict attributes values are rejected."""
100+
@pytest.mark.parametrize(
101+
("data", "expected"), [([], {}), ([["a", 1]], {"a": 1}), ({1: "x"}, {1: "x"})]
102+
)
103+
def test_parse_attributes_lenient_deprecated(data: Any, expected: dict[str, Any]) -> None:
104+
"""Non-mapping attributes still parse as before, but warn."""
102105
from zarr.core.metadata.common import parse_attributes
103106

104-
with pytest.raises(TypeError, match="Expected dict with string keys"):
105-
parse_attributes(data)
107+
with pytest.warns(ZarrDeprecationWarning, match="mapping with string keys"):
108+
assert parse_attributes(data) == expected
106109

107110

108111
@pytest.mark.parametrize("data", [{}, {"a": 1}])
109112
def test_parse_attributes_valid(data: Any) -> None:
110-
"""Dicts with string keys are accepted."""
113+
"""Dicts with string keys are accepted without a warning."""
111114
from zarr.core.metadata.common import parse_attributes
112115

113116
assert parse_attributes(data) == data

0 commit comments

Comments
 (0)