rename exists_ok to overwrite (#2548)

Author: d-v-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

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)

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,
                 )
             )

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,
     )