Deprecate group()

changes/3435.removal.md

@@ -0,0 +1,2 @@
+`zarr.group`, `zarr.api.synchronous.group`, and `zarr.api.asynchronous.group` are all deprecated and will be removed in the future.
+Use the relevant `open_group()` or `create_group()` functions instead.

docs/contributing.md

@@ -14,7 +14,7 @@ If you find a bug, please raise a [GitHub issue](https://github.com/zarr-develop
 
 ```python
 import zarr
-g = zarr.group()
+g = zarr.open_group()
 # etc.
 ```
 
@@ -230,4 +230,4 @@ If an existing Zarr format version changes, or a new version of the Zarr format
 ## Release procedure
 
 Open an issue on GitHub announcing the release using the release checklist template:
-[https://github.com/zarr-developers/zarr-python/issues/new?template=release-checklist.md](https://github.com/zarr-developers/zarr-python/issues/new?template=release-checklist.md>). The release checklist includes all steps necessary for the release.
+[https://github.com/zarr-developers/zarr-python/issues/new?template=release-checklist.md](https://github.com/zarr-developers/zarr-python/issues/new?template=release-checklist.md>). The release checklist includes all steps necessary for the release.

docs/quick-start.md

@@ -77,7 +77,7 @@ Zarr allows you to create hierarchical groups, similar to directories:
 ```python exec="true" session="quickstart" source="above" result="ansi"
 
 # Create nested groups and add arrays
-root = zarr.group("data/example-3.zarr")
+root = zarr.create_group("data/example-3.zarr")
 foo = root.create_group(name="foo")
 bar = root.create_array(
     name="bar", shape=(100, 10), chunks=(10, 10), dtype="f4"
@@ -102,7 +102,7 @@ Suppose we want to copy existing groups and arrays into a new storage backend:
 ```python exec="true" session="quickstart" source="above" result="html"
 
 # Create nested groups and add arrays
-root = zarr.group("data/example-4.zarr", attributes={'name': 'root'})
+root = zarr.create_group("data/example-4.zarr", attributes={'name': 'root'})
 foo = root.create_group(name="foo")
 bar = root.create_array(
     name="bar", shape=(100, 10), chunks=(10, 10), dtype="f4"

docs/user-guide/groups.md

@@ -106,7 +106,7 @@ property. E.g.:
 
 ```python exec="true" session="groups" source="above" result="ansi"
 store = zarr.storage.MemoryStore()
-root = zarr.group(store=store)
+root = zarr.create_group(store=store)
 foo = root.create_group('foo')
 bar = foo.create_array(name='bar', shape=1000000, chunks=100000, dtype='int64')
 bar[:] = 42
@@ -134,4 +134,4 @@ print(root.tree())
 ```
 
 !!! note
-    [`zarr.Group.tree`][] requires the optional [rich](https://rich.readthedocs.io/en/stable/) dependency. It can be installed with the `[tree]` extra.
+    [`zarr.Group.tree`][] requires the optional [rich](https://rich.readthedocs.io/en/stable/) dependency. It can be installed with the `[tree]` extra.

src/zarr/api/asynchronous.py

@@ -654,6 +654,7 @@ async def array(data: npt.ArrayLike | AnyArray, **kwargs: Any) -> AnyAsyncArray:
     return z
 
 
+@deprecated("Use open_group() or create_group() instead")
 async def group(
     *,  # Note: this is a change from v2
     store: StoreLike | None = None,

src/zarr/api/synchronous.py

@@ -407,6 +407,7 @@ def array(data: npt.ArrayLike | AnyArray, **kwargs: Any) -> AnyArray:
     return Array(sync(async_api.array(data=data, **kwargs)))
 
 
+@deprecated("Use open_group() or create_group() instead")
 def group(
     store: StoreLike | None = None,
     *,

src/zarr/core/group.py

@@ -1971,7 +1971,7 @@ def __iter__(self) -> Iterator[str]:
         Examples
         --------
         >>> import zarr
-        >>> g1 = zarr.group()
+        >>> g1 = zarr.create_group(store={})
         >>> g2 = g1.create_group('foo')
         >>> g3 = g1.create_group('bar')
         >>> d1 = g1.create_array('baz', shape=(10,), chunks=(10,))
@@ -2005,7 +2005,7 @@ def __setitem__(self, key: str, value: Any) -> None:
         Examples
         --------
         >>> import zarr
-        >>> group = zarr.group()
+        >>> group = zarr.create_group(store={})
         >>> group["foo"] = zarr.zeros((10,))
         >>> group["foo"]
         <Array memory://132270269438272/foo shape=(10,) dtype=float64>
@@ -2021,7 +2021,7 @@ async def update_attributes_async(self, new_attributes: dict[str, Any]) -> Group
         Examples
         --------
         >>> import zarr
-        >>> group = zarr.group()
+        >>> group = zarr.create_group(store={})
         >>> await group.update_attributes_async({"foo": "bar"})
         >>> group.attrs.asdict()
         {'foo': 'bar'}
@@ -2122,7 +2122,7 @@ def update_attributes(self, new_attributes: dict[str, Any]) -> Group:
         Examples
         --------
         >>> import zarr
-        >>> group = zarr.group()
+        >>> group = zarr.create_group(store={})
         >>> group.update_attributes({"foo": "bar"})
         >>> group.attrs.asdict()
         {'foo': 'bar'}
@@ -2247,7 +2247,7 @@ def keys(self) -> Generator[str, None]:
         Examples
         --------
         >>> import zarr
-        >>> g1 = zarr.group()
+        >>> g1 = zarr.create_group(store={})
         >>> g2 = g1.create_group('foo')
         >>> g3 = g1.create_group('bar')
         >>> d1 = g1.create_array('baz', shape=(10,), chunks=(10,))
@@ -2267,7 +2267,7 @@ def __contains__(self, member: str) -> bool:
         Examples
         --------
         >>> import zarr
-        >>> g1 = zarr.group()
+        >>> g1 = zarr.create_group(store={})
         >>> g2 = g1.create_group('foo')
         >>> d1 = g1.create_array('bar', shape=(10,), chunks=(10,))
         >>> 'foo' in g1
@@ -2286,7 +2286,7 @@ def groups(self) -> Generator[tuple[str, Group], None]:
         Examples
         --------
         >>> import zarr
-        >>> group = zarr.group()
+        >>> group = zarr.create_group(store={})
         >>> group.create_group("subgroup")
         >>> for name, subgroup in group.groups():
         ...     print(name, subgroup)
@@ -2301,7 +2301,7 @@ def group_keys(self) -> Generator[str, None]:
         Examples
         --------
         >>> import zarr
-        >>> group = zarr.group()
+        >>> group = zarr.create_group(store={})
         >>> group.create_group("subgroup")
         >>> for name in group.group_keys():
         ...     print(name)
@@ -2316,7 +2316,7 @@ def group_values(self) -> Generator[Group, None]:
         Examples
         --------
         >>> import zarr
-        >>> group = zarr.group()
+        >>> group = zarr.create_group(store={})
         >>> group.create_group("subgroup")
         >>> for subgroup in group.group_values():
         ...     print(subgroup)
@@ -2331,7 +2331,7 @@ def arrays(self) -> Generator[tuple[str, AnyArray], None]:
         Examples
         --------
         >>> import zarr
-        >>> group = zarr.group()
+        >>> group = zarr.create_group(store={})
         >>> group.create_array("subarray", shape=(10,), chunks=(10,))
         >>> for name, subarray in group.arrays():
         ...     print(name, subarray)
@@ -2346,7 +2346,7 @@ def array_keys(self) -> Generator[str, None]:
         Examples
         --------
         >>> import zarr
-        >>> group = zarr.group()
+        >>> group = zarr.create_group(store={})
         >>> group.create_array("subarray", shape=(10,), chunks=(10,))
         >>> for name in group.array_keys():
         ...     print(name)
@@ -2362,7 +2362,7 @@ def array_values(self) -> Generator[AnyArray, None]:
         Examples
         --------
         >>> import zarr
-        >>> group = zarr.group()
+        >>> group = zarr.create_group(store={})
         >>> group.create_array("subarray", shape=(10,), chunks=(10,))
         >>> for subarray in group.array_values():
         ...     print(subarray)
@@ -2407,7 +2407,7 @@ def create_group(self, name: str, **kwargs: Any) -> Group:
         Examples
         --------
         >>> import zarr
-        >>> group = zarr.group()
+        >>> group = zarr.create_group(store={})
         >>> subgroup = group.create_group("subgroup")
         >>> subgroup
         <Group memory://132270269438272/subgroup>

src/zarr/testing/stateful.py

@@ -88,7 +88,7 @@ def __init__(self, store: Store) -> None:
         self.store = store
 
         self.model = MemoryStore()
-        zarr.group(store=self.model)
+        zarr.create_group(store=self.model)
 
         # Track state of the hierarchy, these should contain fully qualified paths
         self.all_groups: set[str] = set()
@@ -98,7 +98,7 @@ def __init__(self, store: Store) -> None:
     def init_store(self) -> None:
         # This lets us reuse the fixture provided store.
         self._sync(self.store.clear())
-        zarr.group(store=self.store)
+        zarr.create_group(store=self.store)
 
     def can_add(self, path: str) -> bool:
         return path not in self.all_groups and path not in self.all_arrays
@@ -117,8 +117,8 @@ def add_group(self, name: str, data: DataObject) -> None:
         assume(self.can_add(path))
         note(f"Adding group: path='{path}'")
         self.all_groups.add(path)
-        zarr.group(store=self.store, path=path)
-        zarr.group(store=self.model, path=path)
+        zarr.create_group(store=self.store, path=path)
+        zarr.create_group(store=self.model, path=path)
 
     @rule(data=st.data(), name=node_names, array_and_chunks=np_array_and_chunks())
     def add_array(
@@ -172,8 +172,8 @@ def clear(self) -> None:
         self.all_groups.clear()
         self.all_arrays.clear()
 
-        zarr.group(store=self.store)
-        zarr.group(store=self.model)
+        zarr.create_group(store=self.store)
+        zarr.create_group(store=self.model)
 
         # TODO: MemoryStore is broken?
         # assert not self._sync(self.store.is_empty("/"))

tests/test_api.py

@@ -245,7 +245,7 @@ def test_open_normalized_path(
 ) -> None:
     node: Group | AnyArray
     if node_type == "group":
-        node = group(store=memory_store, path=path)
+        node = create_group(store=memory_store, path=path)
     elif node_type == "array":
         node = create(store=memory_store, path=path, shape=(2,))
 
@@ -600,7 +600,7 @@ def test_load_local(tmp_path: Path, path: str | None, load_read_only: bool) -> N
 
 def test_tree() -> None:
     pytest.importorskip("rich")
-    g1 = zarr.group()
+    g1 = zarr.create_group(store={})
     g1.create_group("foo")
     g3 = g1.create_group("bar")
     g3.create_group("baz")
@@ -1465,6 +1465,7 @@ def test_no_overwrite_array(tmp_path: Path, create_function: Callable, overwrite
         assert existing_fpath.exists()
 
 
+@pytest.mark.filterwarnings(r"ignore:Use open_group\(\) or create_group\(\) instead")
 @pytest.mark.parametrize("create_function", [create_group, group])
 @pytest.mark.parametrize("overwrite", [True, False])
 def test_no_overwrite_group(tmp_path: Path, create_function: Callable, overwrite: bool) -> None:  # type:ignore[type-arg]

tests/test_api/test_asynchronous.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import re
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
@@ -119,8 +120,14 @@ async def test_open_group_new_path(tmp_path: Path) -> None:
     """
     # tmp_path exists, but tmp_path / "test.zarr" will not, which is important for this test
     path = tmp_path / "test.zarr"
-    grp = await group(store=path, attributes={"a": 1})
+    with pytest.warns(
+        DeprecationWarning, match=re.escape("Use open_group() or create_group() instead")
+    ):
+        grp = await group(store=path, attributes={"a": 1})
     assert isinstance(grp, AsyncGroup)
     # Calling group on an existing store should just open that store
-    grp = await group(store=path)
+    with pytest.warns(
+        DeprecationWarning, match=re.escape("Use open_group() or create_group() instead")
+    ):
+        grp = await group(store=path)
     assert grp.attrs == {"a": 1}

tests/test_array.py

@@ -1784,7 +1784,7 @@ def test_roundtrip_numcodecs() -> None:
     ]
 
     # Create the array with the correct codecs
-    root = zarr.group(store)
+    root = zarr.create_group(store)
     warn_msg = "Numcodecs codecs are not in the Zarr version 3 specification and may not be supported by other zarr implementations."
     with pytest.warns(ZarrUserWarning, match=warn_msg):
         root.create_array(

tests/test_group.py

@@ -1662,7 +1662,7 @@ def test_from_dict_extra_fields(self):
 class TestInfo:
     def test_info(self):
         store = zarr.storage.MemoryStore()
-        A = zarr.group(store=store, path="A")
+        A = zarr.create_group(store=store, path="A")
         B = A.create_group(name="B")
 
         B.create_array(name="x", shape=(1,), dtype="uint8")
@@ -1702,7 +1702,7 @@ def test_update_attrs() -> None:
 @pytest.mark.parametrize("store", ["local", "memory"], indirect=["store"])
 def test_delitem_removes_children(store: Store, zarr_format: ZarrFormat) -> None:
     # https://github.com/zarr-developers/zarr-python/issues/2191
-    g1 = zarr.group(store=store, zarr_format=zarr_format)
+    g1 = zarr.create_group(store=store, zarr_format=zarr_format)
     g1.create_group("0")
     g1.create_group("0/0")
     arr = g1.create_array("0/0/0", shape=(1,), dtype="uint8")
@@ -2228,7 +2228,7 @@ def test_group_members_performance(store: Store) -> None:
     get_latency = 0.1
 
     # use the input store to create some groups
-    group_create = zarr.group(store=store)
+    group_create = zarr.create_group(store=store)
     num_groups = 10
 
     # Create some groups
@@ -2237,7 +2237,7 @@ def test_group_members_performance(store: Store) -> None:
 
     latency_store = LatencyStore(store, get_latency=get_latency)
     # create a group with some latency on get operations
-    group_read = zarr.group(store=latency_store)
+    group_read = zarr.open_group(store=latency_store)
 
     # check how long it takes to iterate over the groups
     # if .members is sensitive to IO latency,
@@ -2259,7 +2259,7 @@ def test_group_members_concurrency_limit(store: MemoryStore) -> None:
     get_latency = 0.02
 
     # use the input store to create some groups
-    group_create = zarr.group(store=store)
+    group_create = zarr.create_group(store=store)
     num_groups = 10
 
     # Create some groups
@@ -2268,7 +2268,7 @@ def test_group_members_concurrency_limit(store: MemoryStore) -> None:
 
     latency_store = LatencyStore(store, get_latency=get_latency)
     # create a group with some latency on get operations
-    group_read = zarr.group(store=latency_store)
+    group_read = zarr.open_group(store=latency_store)
 
     # check how long it takes to iterate over the groups
     # if .members is sensitive to IO latency,