add missing docstring and re-parametrize test

Author: d-v-b

src/zarr/core/group.py

@@ -2439,9 +2439,149 @@ def require_groups(self, *names: str) -> tuple[Group, ...]:
         """
         return tuple(map(Group, self._sync(self._async_group.require_groups(*names))))
 
-    def create(self, *args: Any, **kwargs: Any) -> Array:
-        # Backwards compatibility for 2.x
-        return self.create_array(*args, **kwargs)
+    def create(
+        self,
+        name: str,
+        *,
+        shape: ShapeLike | None = None,
+        dtype: ZDTypeLike | None = None,
+        data: np.ndarray[Any, np.dtype[Any]] | None = None,
+        chunks: tuple[int, ...] | Literal["auto"] = "auto",
+        shards: ShardsLike | None = None,
+        filters: FiltersLike = "auto",
+        compressors: CompressorsLike = "auto",
+        compressor: CompressorLike = "auto",
+        serializer: SerializerLike = "auto",
+        fill_value: Any | None = DEFAULT_FILL_VALUE,
+        order: MemoryOrder | None = None,
+        attributes: dict[str, JSON] | None = None,
+        chunk_key_encoding: ChunkKeyEncodingLike | None = None,
+        dimension_names: DimensionNames = None,
+        storage_options: dict[str, Any] | None = None,
+        overwrite: bool = False,
+        config: ArrayConfigLike | None = None,
+        write_data: bool = True,
+    ) -> Array:
+        """Create an array within this group.
+
+        This method lightly wraps :func:`zarr.core.array.create_array`.
+
+        Parameters
+        ----------
+        name : str
+            The name of the array relative to the group. If ``path`` is ``None``, the array will be located
+            at the root of the store.
+        shape : ShapeLike, optional
+            Shape of the array. Must be ``None`` if ``data`` is provided.
+        dtype : npt.DTypeLike | None
+            Data type of the array. Must be ``None`` if ``data`` is provided.
+        data : Array-like data to use for initializing the array. If this parameter is provided, the
+            ``shape`` and ``dtype`` parameters must be ``None``.
+        chunks : tuple[int, ...], optional
+            Chunk shape of the array.
+            If not specified, default are guessed based on the shape and dtype.
+        shards : tuple[int, ...], optional
+            Shard shape of the array. The default value of ``None`` results in no sharding at all.
+        filters : Iterable[Codec] | Literal["auto"], optional
+            Iterable of filters to apply to each chunk of the array, in order, before serializing that
+            chunk to bytes.
+
+            For Zarr format 3, a "filter" is a codec that takes an array and returns an array,
+            and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a
+            dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`.
+
+            For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the
+            the order if your filters is consistent with the behavior of each filter.
+
+            The default value of ``"auto"`` instructs Zarr to use a default used based on the data
+            type of the array and the Zarr format specified. For all data types in Zarr V3, and most
+            data types in Zarr V2, the default filters are empty. The only cases where default filters
+            are not empty is when the Zarr format is 2, and the data type is a variable-length data type like
+            `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases,
+            the default filters contains a single element which is a codec specific to that particular data type.
+
+            To create an array with no filters, provide an empty iterable or the value ``None``.
+        compressors : Iterable[Codec], optional
+            List of compressors to apply to the array. Compressors are applied in order, and after any
+            filters are applied (if any are specified) and the data is serialized into bytes.
+
+            For Zarr format 3, a "compressor" is a codec that takes a bytestream, and
+            returns another bytestream. Multiple compressors my be provided for Zarr format 3.
+            If no ``compressors`` are provided, a default set of compressors will be used.
+            These defaults can be changed by modifying the value of ``array.v3_default_compressors``
+            in :mod:`zarr.core.config`.
+            Use ``None`` to omit default compressors.
+
+            For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may
+            be provided for Zarr format 2.
+            If no ``compressor`` is provided, a default compressor will be used.
+            in :mod:`zarr.core.config`.
+            Use ``None`` to omit the default compressor.
+        compressor : Codec, optional
+            Deprecated in favor of ``compressors``.
+        serializer : dict[str, JSON] | ArrayBytesCodec, optional
+            Array-to-bytes codec to use for encoding the array data.
+            Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion.
+            If no ``serializer`` is provided, a default serializer will be used.
+            These defaults can be changed by modifying the value of ``array.v3_default_serializer``
+            in :mod:`zarr.core.config`.
+        fill_value : Any, optional
+            Fill value for the array.
+        order : {"C", "F"}, optional
+            The memory of the array (default is "C").
+            For Zarr format 2, this parameter sets the memory order of the array.
+            For Zarr format 3, this parameter is deprecated, because memory order
+            is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory
+            order for Zarr format 3 arrays is via the ``config`` parameter, e.g. ``{'config': 'C'}``.
+            If no ``order`` is provided, a default order will be used.
+            This default can be changed by modifying the value of ``array.order`` in :mod:`zarr.core.config`.
+        attributes : dict, optional
+            Attributes for the array.
+        chunk_key_encoding : ChunkKeyEncoding, optional
+            A specification of how the chunk keys are represented in storage.
+            For Zarr format 3, the default is ``{"name": "default", "separator": "/"}}``.
+            For Zarr format 2, the default is ``{"name": "v2", "separator": "."}}``.
+        dimension_names : Iterable[str], optional
+            The names of the dimensions (default is None).
+            Zarr format 3 only. Zarr format 2 arrays should not use this parameter.
+        storage_options : dict, optional
+            If using an fsspec URL to create the store, these will be passed to the backend implementation.
+            Ignored otherwise.
+        overwrite : bool, default False
+            Whether to overwrite an array with the same name in the store, if one exists.
+        config : ArrayConfig or ArrayConfigLike, optional
+            Runtime configuration for the array.
+        write_data : bool
+            If a pre-existing array-like object was provided to this function via the ``data`` parameter
+            then ``write_data`` determines whether the values in that array-like object should be
+            written to the Zarr array created by this function. If ``write_data`` is ``False``, then the
+            array will be left empty.
+
+        Returns
+        -------
+        AsyncArray
+        """
+        return self.create_array(
+            name,
+            shape=shape,
+            dtype=dtype,
+            data=data,
+            chunks=chunks,
+            shards=shards,
+            filters=filters,
+            compressors=compressors,
+            compressor=compressor,
+            serializer=serializer,
+            fill_value=fill_value,
+            order=order,
+            attributes=attributes,
+            chunk_key_encoding=chunk_key_encoding,
+            dimension_names=dimension_names,
+            storage_options=storage_options,
+            overwrite=overwrite,
+            config=config,
+            write_data=write_data,
+        )
 
     def create_array(
         self,

tests/test_api/test_synchronous.py

@@ -5,6 +5,7 @@
 import pytest
 from numpydoc.docscrape import NumpyDocString
 
+import zarr
 from zarr.api import asynchronous, synchronous
 
 if TYPE_CHECKING:
@@ -37,37 +38,73 @@ def test_docstring_match(callable_name: str) -> None:
 
 
 @pytest.mark.parametrize(
-    "parameter_name",
-    [
-        "store",
-        "path",
-        "filters",
-        "codecs",
-        "compressors",
-        "compressor",
-        "chunks",
-        "shape",
-        "dtype",
-        "fill_value",
-    ],
-)
-@pytest.mark.parametrize(
-    "array_creation_routines",
+    ("parameter_name", "array_creation_routines"),
     [
         (
-            asynchronous.create_array,
-            synchronous.create_array,
-            asynchronous.create_group,
-            synchronous.create_group,
+            ("store", "path"),
+            (
+                asynchronous.create_array,
+                synchronous.create_array,
+                asynchronous.create_group,
+                synchronous.create_group,
+                zarr.AsyncGroup.create_array,
+                zarr.Group.create_array,
+            ),
+        ),
+        (
+            (
+                "store",
+                "path",
+            ),
+            (
+                asynchronous.create,
+                synchronous.create,
+                zarr.Group.create,
+                zarr.AsyncArray.create,
+                zarr.Array.create,
+            ),
+        ),
+        (
+            (
+                (
+                    "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,
+                zarr.AsyncGroup.create_dataset,
+                zarr.Group.create_dataset,
+            ),
         ),
-        (asynchronous.create, synchronous.create),
     ],
+    ids=str,
 )
 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 inspecs 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, ...]] = {}
@@ -85,6 +122,5 @@ def test_docstring_consistent_parameters(
                 types[val.type] = types[val.type] + (key,)
             else:
                 types[val.type] = (key,)
-
     assert len(descs) <= 1
     assert len(types) <= 1