From 3e42500daa41ba0e7ff3c7fdc704d8d3742e7edd Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Tue, 10 Dec 2024 14:00:24 +0100 Subject: [PATCH] rename exists_ok to overwrite --- src/zarr/api/asynchronous.py | 18 +++++------ src/zarr/core/array.py | 30 ++++++++--------- src/zarr/core/group.py | 40 +++++++++++------------ tests/conftest.py | 2 +- tests/test_array.py | 10 +++--- tests/test_group.py | 62 ++++++++++++++++++------------------ tests/test_v2.py | 4 +-- 7 files changed, 83 insertions(+), 83 deletions(-) diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index 26822f725b..b5dbb0cfa5 100644 --- a/src/zarr/api/asynchronous.py +++ b/src/zarr/api/asynchronous.py @@ -71,7 +71,7 @@ _OVERWRITE_MODES: tuple[AccessModeLiteral, ...] = ("a", "r+", "w") -def _infer_exists_ok(mode: AccessModeLiteral) -> bool: +def _infer_overwrite(mode: AccessModeLiteral) -> bool: """ Check that an ``AccessModeLiteral`` is compatible with overwriting an existing Zarr node. """ @@ -414,14 +414,14 @@ async def save_array( arr = np.array(arr) shape = arr.shape chunks = getattr(arr, "chunks", None) # for array-likes with chunks attribute - exists_ok = kwargs.pop("exists_ok", None) or _infer_exists_ok(mode) + overwrite = kwargs.pop("overwrite", None) or _infer_overwrite(mode) new = await AsyncArray.create( store_path, zarr_format=zarr_format, shape=shape, dtype=arr.dtype, chunks=chunks, - exists_ok=exists_ok, + overwrite=overwrite, **kwargs, ) await new.setitem(slice(None), arr) @@ -647,7 +647,7 @@ async def group( return await AsyncGroup.from_store( store=store_path, zarr_format=_zarr_format, - exists_ok=overwrite, + overwrite=overwrite, attributes=attributes, ) @@ -753,12 +753,12 @@ async def open_group( except (KeyError, FileNotFoundError): pass if mode in _CREATE_MODES: - exists_ok = _infer_exists_ok(mode) + overwrite = _infer_overwrite(mode) _zarr_format = zarr_format or _default_zarr_version() return await AsyncGroup.from_store( store_path, zarr_format=_zarr_format, - exists_ok=exists_ok, + overwrite=overwrite, attributes=attributes, ) raise FileNotFoundError(f"Unable to find group: {store_path}") @@ -933,7 +933,7 @@ async def create( dtype=dtype, compressor=compressor, fill_value=fill_value, - exists_ok=overwrite, + overwrite=overwrite, filters=filters, dimension_separator=dimension_separator, zarr_format=zarr_format, @@ -1120,12 +1120,12 @@ async def open_array( return await AsyncArray.open(store_path, zarr_format=zarr_format) except FileNotFoundError: if not store_path.read_only and mode in _CREATE_MODES: - exists_ok = _infer_exists_ok(mode) + overwrite = _infer_overwrite(mode) _zarr_format = zarr_format or _default_zarr_version() return await create( store=store_path, zarr_format=_zarr_format, - overwrite=exists_ok, + overwrite=overwrite, **kwargs, ) raise diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index a6317e7a9e..6c8a954bac 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -266,7 +266,7 @@ async def create( filters: list[dict[str, JSON]] | None = None, compressor: dict[str, JSON] | None = None, # runtime - exists_ok: bool = False, + overwrite: bool = False, data: npt.ArrayLike | None = None, ) -> AsyncArray[ArrayV2Metadata]: ... @@ -294,7 +294,7 @@ async def create( codecs: Iterable[Codec | dict[str, JSON]] | None = None, dimension_names: Iterable[str] | None = None, # runtime - exists_ok: bool = False, + overwrite: bool = False, data: npt.ArrayLike | None = None, ) -> AsyncArray[ArrayV3Metadata]: ... @@ -322,7 +322,7 @@ async def create( codecs: Iterable[Codec | dict[str, JSON]] | None = None, dimension_names: Iterable[str] | None = None, # runtime - exists_ok: bool = False, + overwrite: bool = False, data: npt.ArrayLike | None = None, ) -> AsyncArray[ArrayV3Metadata]: ... @@ -355,7 +355,7 @@ async def create( filters: list[dict[str, JSON]] | None = None, compressor: dict[str, JSON] | None = None, # runtime - exists_ok: bool = False, + overwrite: bool = False, data: npt.ArrayLike | None = None, ) -> AsyncArray[ArrayV3Metadata] | AsyncArray[ArrayV2Metadata]: ... @@ -387,7 +387,7 @@ async def create( filters: list[dict[str, JSON]] | None = None, compressor: dict[str, JSON] | None = None, # runtime - exists_ok: bool = False, + overwrite: bool = False, data: npt.ArrayLike | None = None, ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]: """ @@ -429,7 +429,7 @@ async def create( compressor : dict[str, JSON], optional The compressor used to compress the data (default is None). V2 only. V3 arrays should not have 'compressor' parameter. - exists_ok : bool, optional + overwrite : bool, optional Whether to raise an error if the store already exists (default is False). data : npt.ArrayLike, optional The data to be inserted into the array (default is None). @@ -489,7 +489,7 @@ async def create( codecs=codecs, dimension_names=dimension_names, attributes=attributes, - exists_ok=exists_ok, + overwrite=overwrite, order=order, ) elif zarr_format == 2: @@ -522,7 +522,7 @@ async def create( filters=filters, compressor=compressor, attributes=attributes, - exists_ok=exists_ok, + overwrite=overwrite, ) else: raise ValueError(f"Insupported zarr_format. Got: {zarr_format}") @@ -552,9 +552,9 @@ async def _create_v3( codecs: Iterable[Codec | dict[str, JSON]] | None = None, dimension_names: Iterable[str] | None = None, attributes: dict[str, JSON] | None = None, - exists_ok: bool = False, + overwrite: bool = False, ) -> AsyncArray[ArrayV3Metadata]: - if exists_ok: + if overwrite: if store_path.store.supports_deletes: await store_path.delete_dir() else: @@ -609,9 +609,9 @@ async def _create_v2( filters: list[dict[str, JSON]] | None = None, compressor: dict[str, JSON] | None = None, attributes: dict[str, JSON] | None = None, - exists_ok: bool = False, + overwrite: bool = False, ) -> AsyncArray[ArrayV2Metadata]: - if exists_ok: + if overwrite: if store_path.store.supports_deletes: await store_path.delete_dir() else: @@ -1463,7 +1463,7 @@ def create( filters: list[dict[str, JSON]] | None = None, compressor: dict[str, JSON] | None = None, # runtime - exists_ok: bool = False, + overwrite: bool = False, ) -> Array: """Creates a new Array instance from an initialized store. @@ -1493,7 +1493,7 @@ def create( The filters used to compress the data (default is None). compressor : dict[str, JSON], optional The compressor used to compress the data (default is None). - exists_ok : bool, optional + overwrite : bool, optional Whether to raise an error if the store already exists (default is False). Returns @@ -1518,7 +1518,7 @@ def create( order=order, filters=filters, compressor=compressor, - exists_ok=exists_ok, + overwrite=overwrite, ), ) return cls(async_array) diff --git a/src/zarr/core/group.py b/src/zarr/core/group.py index 3613e3e12b..f46c5126b2 100644 --- a/src/zarr/core/group.py +++ b/src/zarr/core/group.py @@ -410,12 +410,12 @@ async def from_store( store: StoreLike, *, attributes: dict[str, Any] | None = None, - exists_ok: bool = False, + overwrite: bool = False, zarr_format: ZarrFormat = 3, ) -> AsyncGroup: store_path = await make_store_path(store) - if exists_ok: + if overwrite: if store_path.store.supports_deletes: await store_path.delete_dir() else: @@ -629,7 +629,7 @@ async def setitem(self, key: str, value: Any) -> None: """ path = self.store_path / key await async_api.save_array( - store=path, arr=value, zarr_format=self.metadata.zarr_format, exists_ok=True + store=path, arr=value, zarr_format=self.metadata.zarr_format, overwrite=True ) async def getitem( @@ -919,7 +919,7 @@ async def create_group( self, name: str, *, - exists_ok: bool = False, + overwrite: bool = False, attributes: dict[str, Any] | None = None, ) -> AsyncGroup: """Create a sub-group. @@ -928,7 +928,7 @@ async def create_group( ---------- name : str Group name. - exists_ok : bool, optional + overwrite : bool, optional If True, do not raise an error if the group already exists. attributes : dict, optional Group attributes. @@ -941,7 +941,7 @@ async def create_group( return await type(self).from_store( self.store_path / name, attributes=attributes, - exists_ok=exists_ok, + overwrite=overwrite, zarr_format=self.metadata.zarr_format, ) @@ -960,8 +960,8 @@ async def require_group(self, name: str, overwrite: bool = False) -> AsyncGroup: g : AsyncGroup """ if overwrite: - # TODO: check that exists_ok=True errors if an array exists where the group is being created - grp = await self.create_group(name, exists_ok=True) + # TODO: check that overwrite=True errors if an array exists where the group is being created + grp = await self.create_group(name, overwrite=True) else: try: item: ( @@ -1018,7 +1018,7 @@ async def create_array( filters: list[dict[str, JSON]] | None = None, compressor: dict[str, JSON] | None = None, # runtime - exists_ok: bool = False, + overwrite: bool = False, data: npt.ArrayLike | None = None, ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]: """ @@ -1052,7 +1052,7 @@ async def create_array( Filters for the array. compressor : dict[str, JSON] | None = None The compressor for the array. - exists_ok : bool = False + overwrite : bool = False If True, a pre-existing array or group at the path of this array will be overwritten. If False, the presence of a pre-existing array or group is an error. @@ -1077,7 +1077,7 @@ async def create_array( order=order, filters=filters, compressor=compressor, - exists_ok=exists_ok, + overwrite=overwrite, zarr_format=self.metadata.zarr_format, data=data, ) @@ -1651,7 +1651,7 @@ def from_store( *, attributes: dict[str, Any] | None = None, zarr_format: ZarrFormat = 3, - exists_ok: bool = False, + overwrite: bool = False, ) -> Group: """Instantiate a group from an initialized store. @@ -1663,7 +1663,7 @@ def from_store( A dictionary of JSON-serializable values with user-defined attributes. zarr_format : {2, 3}, optional Zarr storage format version. - exists_ok : bool, optional + overwrite : bool, optional If True, do not raise an error if the group already exists. Returns @@ -1680,7 +1680,7 @@ def from_store( AsyncGroup.from_store( store, attributes=attributes, - exists_ok=exists_ok, + overwrite=overwrite, zarr_format=zarr_format, ), ) @@ -2217,7 +2217,7 @@ def create_array( filters: list[dict[str, JSON]] | None = None, compressor: dict[str, JSON] | None = None, # runtime - exists_ok: bool = False, + overwrite: bool = False, data: npt.ArrayLike | None = None, ) -> Array: """Create a zarr array within this AsyncGroup. @@ -2251,7 +2251,7 @@ def create_array( Filters for the array. compressor : dict[str, JSON] | None = None The compressor for the array. - exists_ok : bool = False + overwrite : bool = False If True, a pre-existing array or group at the path of this array will be overwritten. If False, the presence of a pre-existing array or group is an error. @@ -2280,7 +2280,7 @@ def create_array( order=order, filters=filters, compressor=compressor, - exists_ok=exists_ok, + overwrite=overwrite, data=data, ) ) @@ -2558,7 +2558,7 @@ def array( filters: list[dict[str, JSON]] | None = None, compressor: dict[str, JSON] | None = None, # runtime - exists_ok: bool = False, + overwrite: bool = False, data: npt.ArrayLike | None = None, ) -> Array: """Create a zarr array within this AsyncGroup. @@ -2592,7 +2592,7 @@ def array( Filters for the array. compressor : dict[str, JSON] | None = None The compressor for the array. - exists_ok : bool = False + overwrite : bool = False If True, a pre-existing array or group at the path of this array will be overwritten. If False, the presence of a pre-existing array or group is an error. @@ -2622,7 +2622,7 @@ def array( order=order, filters=filters, compressor=compressor, - exists_ok=exists_ok, + overwrite=overwrite, data=data, ) ) diff --git a/tests/conftest.py b/tests/conftest.py index 35f31d39b3..fbef922931 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -100,7 +100,7 @@ async def async_group(request: pytest.FixtureRequest, tmpdir: LEGACY_PATH) -> As store, attributes=param.attributes, zarr_format=param.zarr_format, - exists_ok=False, + overwrite=False, ) diff --git a/tests/test_array.py b/tests/test_array.py index 86da801d1f..263b536784 100644 --- a/tests/test_array.py +++ b/tests/test_array.py @@ -27,12 +27,12 @@ @pytest.mark.parametrize("store", ["local", "memory", "zip"], indirect=["store"]) @pytest.mark.parametrize("zarr_format", [2, 3]) -@pytest.mark.parametrize("exists_ok", [True, False]) +@pytest.mark.parametrize("overwrite", [True, False]) @pytest.mark.parametrize("extant_node", ["array", "group"]) def test_array_creation_existing_node( store: LocalStore | MemoryStore, zarr_format: ZarrFormat, - exists_ok: bool, + overwrite: bool, extant_node: Literal["array", "group"], ) -> None: """ @@ -53,14 +53,14 @@ def test_array_creation_existing_node( new_shape = (2, 2) new_dtype = "float32" - if exists_ok: + if overwrite: if not store.supports_deletes: pytest.skip("store does not support deletes") arr_new = Array.create( spath / "extant", shape=new_shape, dtype=new_dtype, - exists_ok=exists_ok, + overwrite=overwrite, zarr_format=zarr_format, ) assert arr_new.shape == new_shape @@ -71,7 +71,7 @@ def test_array_creation_existing_node( spath / "extant", shape=new_shape, dtype=new_dtype, - exists_ok=exists_ok, + overwrite=overwrite, zarr_format=zarr_format, ) diff --git a/tests/test_group.py b/tests/test_group.py index afa290207d..416e10af9a 100644 --- a/tests/test_group.py +++ b/tests/test_group.py @@ -40,7 +40,7 @@ async def store(request: pytest.FixtureRequest, tmpdir: LEGACY_PATH) -> Store: @pytest.fixture(params=[True, False]) -def exists_ok(request: pytest.FixtureRequest) -> bool: +def overwrite(request: pytest.FixtureRequest) -> bool: result = request.param if not isinstance(result, bool): raise TypeError("Wrong type returned by test fixture.") @@ -154,7 +154,7 @@ def test_group_members(store: Store, zarr_format: ZarrFormat, consolidated_metad subsubsubgroup = subsubgroup.create_group("subsubsubgroup") members_expected["subarray"] = group.create_array( - "subarray", shape=(100,), dtype="uint8", chunk_shape=(10,), exists_ok=True + "subarray", shape=(100,), dtype="uint8", chunk_shape=(10,), overwrite=True ) # add an extra object to the domain of the group. @@ -227,7 +227,7 @@ def test_group(store: Store, zarr_format: ZarrFormat) -> None: # create an array from the "bar" group data = np.arange(0, 4 * 4, dtype="uint16").reshape((4, 4)) arr = bar.create_array( - "baz", shape=data.shape, dtype=data.dtype, chunk_shape=(2, 2), exists_ok=True + "baz", shape=data.shape, dtype=data.dtype, chunk_shape=(2, 2), overwrite=True ) arr[:] = data @@ -252,23 +252,23 @@ def test_group(store: Store, zarr_format: ZarrFormat) -> None: assert dict(bar3.attrs) == {"baz": "qux", "name": "bar"} -def test_group_create(store: Store, exists_ok: bool, zarr_format: ZarrFormat) -> None: +def test_group_create(store: Store, overwrite: bool, zarr_format: ZarrFormat) -> None: """ Test that `Group.from_store` works as expected. """ attributes = {"foo": 100} group = Group.from_store( - store, attributes=attributes, zarr_format=zarr_format, exists_ok=exists_ok + store, attributes=attributes, zarr_format=zarr_format, overwrite=overwrite ) assert group.attrs == attributes - if not exists_ok: + if not overwrite: with pytest.raises(ContainsGroupError): - _ = Group.from_store(store, exists_ok=exists_ok, zarr_format=zarr_format) + _ = Group.from_store(store, overwrite=overwrite, zarr_format=zarr_format) -def test_group_open(store: Store, zarr_format: ZarrFormat, exists_ok: bool) -> None: +def test_group_open(store: Store, zarr_format: ZarrFormat, overwrite: bool) -> None: """ Test the `Group.open` method. """ @@ -280,24 +280,24 @@ def test_group_open(store: Store, zarr_format: ZarrFormat, exists_ok: bool) -> N # create the group attrs = {"path": "foo"} group_created = Group.from_store( - store, attributes=attrs, zarr_format=zarr_format, exists_ok=exists_ok + store, attributes=attrs, zarr_format=zarr_format, overwrite=overwrite ) assert group_created.attrs == attrs assert group_created.metadata.zarr_format == zarr_format assert group_created.store_path == spath - # attempt to create a new group in place, to test exists_ok + # attempt to create a new group in place, to test overwrite new_attrs = {"path": "bar"} - if not exists_ok: + if not overwrite: with pytest.raises(ContainsGroupError): - Group.from_store(store, attributes=attrs, zarr_format=zarr_format, exists_ok=exists_ok) + Group.from_store(store, attributes=attrs, zarr_format=zarr_format, overwrite=overwrite) else: if not store.supports_deletes: pytest.skip( - "Store does not support deletes but `exists_ok` is True, requiring deletes to override a group" + "Store does not support deletes but `overwrite` is True, requiring deletes to override a group" ) group_created_again = Group.from_store( - store, attributes=new_attrs, zarr_format=zarr_format, exists_ok=exists_ok + store, attributes=new_attrs, zarr_format=zarr_format, overwrite=overwrite ) assert group_created_again.attrs == new_attrs assert group_created_again.metadata.zarr_format == zarr_format @@ -597,7 +597,7 @@ async def test_group_update_attributes_async(store: Store, zarr_format: ZarrForm def test_group_create_array( store: Store, zarr_format: ZarrFormat, - exists_ok: bool, + overwrite: bool, method: Literal["create_array", "array"], ) -> None: """ @@ -616,7 +616,7 @@ def test_group_create_array( else: raise AssertionError - if not exists_ok: + if not overwrite: if method == "create_array": with pytest.raises(ContainsArrayError): group.create_array(name="array", shape=shape, dtype=dtype, data=data) @@ -698,12 +698,12 @@ def test_group_array_creation( @pytest.mark.parametrize("store", ["local", "memory", "zip"], indirect=["store"]) @pytest.mark.parametrize("zarr_format", [2, 3]) -@pytest.mark.parametrize("exists_ok", [True, False]) +@pytest.mark.parametrize("overwrite", [True, False]) @pytest.mark.parametrize("extant_node", ["array", "group"]) def test_group_creation_existing_node( store: Store, zarr_format: ZarrFormat, - exists_ok: bool, + overwrite: bool, extant_node: Literal["array", "group"], ) -> None: """ @@ -725,14 +725,14 @@ def test_group_creation_existing_node( new_attributes = {"new": True} - if exists_ok: + if overwrite: if not store.supports_deletes: - pytest.skip("store does not support deletes but exists_ok is True") + pytest.skip("store does not support deletes but overwrite is True") node_new = Group.from_store( spath / "extant", attributes=new_attributes, zarr_format=zarr_format, - exists_ok=exists_ok, + overwrite=overwrite, ) assert node_new.attrs == new_attributes else: @@ -741,13 +741,13 @@ def test_group_creation_existing_node( spath / "extant", attributes=new_attributes, zarr_format=zarr_format, - exists_ok=exists_ok, + overwrite=overwrite, ) async def test_asyncgroup_create( store: Store, - exists_ok: bool, + overwrite: bool, zarr_format: ZarrFormat, ) -> None: """ @@ -758,19 +758,19 @@ async def test_asyncgroup_create( agroup = await AsyncGroup.from_store( store, attributes=attributes, - exists_ok=exists_ok, + overwrite=overwrite, zarr_format=zarr_format, ) assert agroup.metadata == GroupMetadata(zarr_format=zarr_format, attributes=attributes) assert agroup.store_path == await make_store_path(store) - if not exists_ok: + if not overwrite: with pytest.raises(ContainsGroupError): agroup = await AsyncGroup.from_store( spath, attributes=attributes, - exists_ok=exists_ok, + overwrite=overwrite, zarr_format=zarr_format, ) # create an array at our target path @@ -782,7 +782,7 @@ async def test_asyncgroup_create( _ = await AsyncGroup.from_store( StorePath(store=store) / collision_name, attributes=attributes, - exists_ok=exists_ok, + overwrite=overwrite, zarr_format=zarr_format, ) @@ -805,7 +805,7 @@ async def test_asyncgroup_open( group_w = await AsyncGroup.from_store( store=store, attributes=attributes, - exists_ok=False, + overwrite=False, zarr_format=zarr_format, ) @@ -819,7 +819,7 @@ async def test_asyncgroup_open_wrong_format( store: Store, zarr_format: ZarrFormat, ) -> None: - _ = await AsyncGroup.from_store(store=store, exists_ok=False, zarr_format=zarr_format) + _ = await AsyncGroup.from_store(store=store, overwrite=False, zarr_format=zarr_format) zarr_format_wrong: ZarrFormat # try opening with the wrong zarr format if zarr_format == 3: @@ -932,7 +932,7 @@ async def test_asyncgroup_create_group( async def test_asyncgroup_create_array( - store: Store, zarr_format: ZarrFormat, exists_ok: bool + store: Store, zarr_format: ZarrFormat, overwrite: bool ) -> None: """ Test that the AsyncGroup.create_array method works correctly. We ensure that array properties @@ -941,7 +941,7 @@ async def test_asyncgroup_create_array( agroup = await AsyncGroup.from_store(store=store, zarr_format=zarr_format) - if not exists_ok: + if not overwrite: with pytest.raises(ContainsGroupError): agroup = await AsyncGroup.from_store(store=store, zarr_format=zarr_format) diff --git a/tests/test_v2.py b/tests/test_v2.py index 68c07e2024..890d4039a3 100644 --- a/tests/test_v2.py +++ b/tests/test_v2.py @@ -145,7 +145,7 @@ def test_v2_non_contiguous(array_order: Literal["C", "F"], data_order: Literal[" fill_value=np.nan, dtype="float64", zarr_format=2, - exists_ok=True, + overwrite=True, order=array_order, ) @@ -165,7 +165,7 @@ def test_v2_non_contiguous(array_order: Literal["C", "F"], data_order: Literal[" fill_value=np.nan, dtype="float64", zarr_format=2, - exists_ok=True, + overwrite=True, order=array_order, )