Merge branch 'main' of https://github.com/zarr-developers/zarr-python into widen-parse-data-type

d-v-b · d-v-b · commit ca6196d3ecac · 2025-07-17T16:19:17.000+02:00
diff --git a/changes/+c563f4d4.bugfix.rst b/changes/+c563f4d4.bugfix.rst
@@ -0,0 +1 @@
+Register 'gpu' marker with pytest for downstream StoreTests.
diff --git a/changes/2819.chore.rst b/changes/2819.chore.rst
diff --git a/changes/3249.doc.rst b/changes/3249.doc.rst
@@ -0,0 +1,2 @@
+Expand the data type docs to include a demonstration of the ``parse_data_type`` function.
+Expand the docstring for the ``parse_data_type`` function.
diff --git a/changes/3251.fix.rst b/changes/3251.fix.rst
@@ -0,0 +1 @@
+Ensure that all abstract methods of ``ZDType`` raise a ``NotImplementedError`` when invoked.
diff --git a/docs/about.rst b/docs/about.rst
@@ -18,7 +18,7 @@ Funding
 -------
 The project is fiscally sponsored by `NumFOCUS <https://numfocus.org/>`_, a US
 501(c)(3) public charity, and development is supported by the
-`MRC Centre for Genomics and Global Health <https://www.cggh.org>`_
+`MRC Centre for Genomics and Global Health <https://github.com/cggh/>`_
 and the `Chan Zuckerberg Initiative <https://chanzuckerberg.com/>`_.
 
 .. _NumCodecs: https://numcodecs.readthedocs.io/
diff --git a/docs/conf.py b/docs/conf.py
@@ -167,8 +167,17 @@ def skip_submodules(
 # documentation.
 html_theme_options = {
     "github_url": "https://github.com/zarr-developers/zarr-python",
-    "twitter_url": "https://twitter.com/zarr_dev",
     "icon_links": [
+        {
+            "name": "Bluesky",
+            "url": "https://bsky.app/profile/zarr.dev",
+            "icon": "fa-brands fa-bluesky",
+        },
+        {
+            "name": "Mastodon",
+            "url": "https://fosstodon.org/@zarr",
+            "icon": "fa-brands fa-mastodon",
+        },
         {
             "name": "Zarr Dev",
             "url": "https://zarr.dev/",
@@ -178,7 +187,6 @@ def skip_submodules(
     ],
     "collapse_navigation": True,
     "navigation_with_keys": False,
-    "announcement": "Zarr-Python 3 is here! Check out the release announcement <a href='https://zarr.dev/blog/zarr-python-3-release/'>here.</a>",
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
@@ -8,7 +8,24 @@ Release notes
 
 Features
 ~~~~~~~~
-
+- Ensure that invocations of ``create_array`` use consistent keyword arguments, with consistent defaults.
+
+  ``zarr.api.synchronous.create_array`` now takes a ``write_data`` keyword argument
+  The ``Group.create_array`` method takes ``data`` and ``write_data`` keyword arguments.
+  The functions ``api.asynchronous.create``, ``api.asynchronous.create_array``
+  and the methods ``Group.create_array``, ``Group.array``, had the default
+  ``fill_value`` changed from ``0`` to the ``DEFAULT_FILL_VALUE`` value, which instructs Zarr to
+  use the default scalar value associated with the array's data type as the fill value. These are
+  all functions or methods for array creation that mirror, wrap or are wrapped by, another function
+  that already has a default ``fill_value`` set to ``DEFAULT_FILL_VALUE``. This change is necessary
+  to make these functions consistent across the entire codebase, but as this changes default values,
+  new data might have a different fill value than expected after this change.
+
+  For data types where 0 is meaningful, like integers or floats, the default scalar is 0, so this
+  change should not be noticeable. For data types where 0 is ambiguous, like fixed-length unicode
+  strings, the default fill value might be different after this change. Users who were relying on how
+  Zarr interpreted ``0`` as a non-numeric scalar value should set their desired fill value explicitly
+  after this change.
 - Added public API for Buffer ABCs and implementations.
 
   Use :mod:`zarr.buffer` to access buffer implementations, and
diff --git a/docs/user-guide/data_types.rst b/docs/user-guide/data_types.rst
@@ -409,4 +409,47 @@ We want to avoid a situation where the same native data type matches multiple Za
 a NumPy data type should *uniquely* specify a single Zarr data type. But data type resolution is
 dynamic, so it's not possible to statically guarantee this uniqueness constraint. Therefore, we
 attempt data type resolution against *every* data type class, and if, for some reason, a native data
-type matches multiple Zarr data types, we treat this as an error and raise an exception.
+type matches multiple Zarr data types, we treat this as an error and raise an exception.
+
+If you have a NumPy data type and you want to get the corresponding ``ZDType`` instance, you can use
+the ``parse_data_type`` function, which will use the dynamic resolution described above. ``parse_data_type``
+handles a range of input types:
+
+- NumPy data types:
+
+  .. code-block:: python
+
+    >>> import numpy as np
+    >>> from zarr.dtype import parse_data_type
+    >>> my_dtype = np.dtype('>M8[10s]')
+    >>> parse_data_type(my_dtype, zarr_format=2)
+    DateTime64(endianness='big', scale_factor=10, unit='s')
+
+
+- NumPy data type-compatible strings:
+
+  .. code-block:: python
+
+    >>> dtype_str = '>M8[10s]'
+    >>> parse_data_type(dtype_str, zarr_format=2)
+    DateTime64(endianness='big', scale_factor=10, unit='s')
+
+- ``ZDType`` instances:
+
+  .. code-block:: python
+
+    >>> from zarr.dtype import DateTime64
+    >>> zdt = DateTime64(endianness='big', scale_factor=10, unit='s')
+    >>> parse_data_type(zdt, zarr_format=2) # Use a ZDType (this is a no-op)
+    DateTime64(endianness='big', scale_factor=10, unit='s')
+
+- Python dictionaries (requires ``zarr_format=3``). These dictionaries must be consistent with the
+  ``JSON`` form of the data type:
+
+  .. code-block:: python
+
+    >>> dt_dict = {"name": "numpy.datetime64", "configuration": {"unit": "s", "scale_factor": 10}}
+    >>> parse_data_type(dt_dict, zarr_format=3)
+    DateTime64(endianness='little', scale_factor=10, unit='s')
+    >>> parse_data_type(dt_dict, zarr_format=3).to_json(zarr_format=3)
+    {'name': 'numpy.datetime64', 'configuration': {'unit': 's', 'scale_factor': 10}}
diff --git a/pyproject.toml b/pyproject.toml
@@ -138,6 +138,7 @@ exclude_lines = [
 [tool.coverage.run]
 omit = [
     "bench/compress_normal.py",
+    "src/zarr/testing/conftest.py",  # only for downstream projects
 ]
 
 [tool.hatch]
@@ -455,3 +456,6 @@ issue_format = ":issue:`{issue}`"
 
 [tool.codespell]
 ignore-words-list = "astroid"
+
+[project.entry-points.pytest11]
+zarr = "zarr.testing"
diff --git a/src/zarr/core/dtype/wrapper.py b/src/zarr/core/dtype/wrapper.py
@@ -102,9 +102,6 @@ def from_native_dtype(cls: type[Self], dtype: TBaseDType) -> Self:
         """
         Create a ZDType instance from a native data type.
 
-        The base implementation first performs a type check via ``cls._check_native_dtype``.
-        If that type check succeeds, the ZDType class instance is created.
-
         This method is used when taking a user-provided native data type, like a NumPy data type,
         and creating the corresponding ZDType instance from them.
 
@@ -123,7 +120,7 @@ def from_native_dtype(cls: type[Self], dtype: TBaseDType) -> Self:
         TypeError
             If the native data type is not consistent with the wrapped data type.
         """
-        ...
+        raise NotImplementedError  # pragma: no cover
 
     @abstractmethod
     def to_native_dtype(self: Self) -> TDType_co:
@@ -135,15 +132,17 @@ def to_native_dtype(self: Self) -> TDType_co:
         TDType
             The native data type wrapped by this ZDType.
         """
-        ...
+        raise NotImplementedError  # pragma: no cover
 
     @classmethod
     @abstractmethod
-    def _from_json_v2(cls: type[Self], data: DTypeJSON) -> Self: ...
+    def _from_json_v2(cls: type[Self], data: DTypeJSON) -> Self:
+        raise NotImplementedError  # pragma: no cover
 
     @classmethod
     @abstractmethod
-    def _from_json_v3(cls: type[Self], data: DTypeJSON) -> Self: ...
+    def _from_json_v3(cls: type[Self], data: DTypeJSON) -> Self:
+        raise NotImplementedError  # pragma: no cover
 
     @classmethod
     def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
@@ -190,7 +189,7 @@ def to_json(self, zarr_format: ZarrFormat) -> DTypeSpec_V2 | DTypeSpec_V3:
         DTypeJSON_V2 | DTypeJSON_V3
             The JSON-serializable representation of the wrapped data type
         """
-        ...
+        raise NotImplementedError  # pragma: no cover
 
     @abstractmethod
     def _check_scalar(self, data: object) -> bool:
@@ -207,7 +206,7 @@ def _check_scalar(self, data: object) -> bool:
         Bool
             True if the object is valid, False otherwise.
         """
-        ...
+        raise NotImplementedError  # pragma: no cover
 
     @abstractmethod
     def cast_scalar(self, data: object) -> TScalar_co:
@@ -227,6 +226,7 @@ def cast_scalar(self, data: object) -> TScalar_co:
         TScalar
             The cast value.
         """
+        raise NotImplementedError  # pragma: no cover
 
     @abstractmethod
     def default_scalar(self) -> TScalar_co:
@@ -242,7 +242,7 @@ def default_scalar(self) -> TScalar_co:
         TScalar
             The default value for this data type.
         """
-        ...
+        raise NotImplementedError  # pragma: no cover
 
     @abstractmethod
     def from_json_scalar(self: Self, data: JSON, *, zarr_format: ZarrFormat) -> TScalar_co:
@@ -262,7 +262,7 @@ def from_json_scalar(self: Self, data: JSON, *, zarr_format: ZarrFormat) -> TSca
         TScalar
             The deserialized scalar value.
         """
-        ...
+        raise NotImplementedError  # pragma: no cover
 
     @abstractmethod
     def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> JSON:
@@ -285,7 +285,7 @@ def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> JSON:
         JSON
             The JSON-serialized scalar.
         """
-        ...
+        raise NotImplementedError  # pragma: no cover
 
 
 def scalar_failed_type_check_msg(
diff --git a/src/zarr/testing/conftest.py b/src/zarr/testing/conftest.py
@@ -0,0 +1,9 @@
+import pytest
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    # The tests in zarr.testing are intended to be run by downstream projects.
+    # To allow those downstream projects to run with `--strict-markers`, we need
+    # to register an entry point with pytest11 and register our "plugin" with it,
+    # which just registers the markers used in zarr.testing
+    config.addinivalue_line("markers", "gpu: mark a test as requiring CuPy and GPU")
diff --git a/tests/package_with_entrypoint/__init__.py b/tests/package_with_entrypoint/__init__.py
@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Literal, Self
+from typing import TYPE_CHECKING
 
 import numpy as np
 import numpy.typing as npt
@@ -14,7 +14,7 @@
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
-    from typing import ClassVar, Literal
+    from typing import Any, ClassVar, Literal, Self
 
     from zarr.core.array_spec import ArraySpec
     from zarr.core.common import ZarrFormat
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -1,16 +1,15 @@
 from __future__ import annotations
 
 import inspect
-import pathlib
 import re
 from typing import TYPE_CHECKING
 
 import zarr.codecs
 import zarr.storage
 
 if TYPE_CHECKING:
-    import pathlib
     from collections.abc import Callable
+    from pathlib import Path
 
     from zarr.abc.store import Store
     from zarr.core.common import JSON, MemoryOrder, ZarrFormat
@@ -45,10 +44,6 @@
 from zarr.storage._utils import normalize_path
 from zarr.testing.utils import gpu_test
 
-if TYPE_CHECKING:
-    from collections.abc import Callable
-    from pathlib import Path
-
 
 def test_create(memory_store: Store) -> None:
     store = memory_store
@@ -209,9 +204,7 @@ async def test_open_group(memory_store: MemoryStore) -> None:
 
 
 @pytest.mark.parametrize("zarr_format", [None, 2, 3])
-async def test_open_group_unspecified_version(
-    tmpdir: pathlib.Path, zarr_format: ZarrFormat
-) -> None:
+async def test_open_group_unspecified_version(tmpdir: Path, zarr_format: ZarrFormat) -> None:
     """Regression test for https://github.com/zarr-developers/zarr-python/issues/2175"""
 
     # create a group with specified zarr format (could be 2, 3, or None)
@@ -272,7 +265,7 @@ def test_save_errors() -> None:
         zarr.save("data/example.zarr", a, mode="w")
 
 
-def test_open_with_mode_r(tmp_path: pathlib.Path) -> None:
+def test_open_with_mode_r(tmp_path: Path) -> None:
     # 'r' means read only (must exist)
     with pytest.raises(FileNotFoundError):
         zarr.open(store=tmp_path, mode="r")
@@ -288,7 +281,7 @@ def test_open_with_mode_r(tmp_path: pathlib.Path) -> None:
         z2[:] = 3
 
 
-def test_open_with_mode_r_plus(tmp_path: pathlib.Path) -> None:
+def test_open_with_mode_r_plus(tmp_path: Path) -> None:
     # 'r+' means read/write (must exist)
     with pytest.raises(FileNotFoundError):
         zarr.open(store=tmp_path, mode="r+")
@@ -301,7 +294,7 @@ def test_open_with_mode_r_plus(tmp_path: pathlib.Path) -> None:
     z2[:] = 3
 
 
-async def test_open_with_mode_a(tmp_path: pathlib.Path) -> None:
+async def test_open_with_mode_a(tmp_path: Path) -> None:
     # Open without shape argument should default to group
     g = zarr.open(store=tmp_path, mode="a")
     assert isinstance(g, Group)
@@ -319,7 +312,7 @@ async def test_open_with_mode_a(tmp_path: pathlib.Path) -> None:
     z2[:] = 3
 
 
-def test_open_with_mode_w(tmp_path: pathlib.Path) -> None:
+def test_open_with_mode_w(tmp_path: Path) -> None:
     # 'w' means create (overwrite if exists);
     arr = zarr.open(store=tmp_path, mode="w", shape=(3, 3))
     assert isinstance(arr, Array)
@@ -333,7 +326,7 @@ def test_open_with_mode_w(tmp_path: pathlib.Path) -> None:
     z2[:] = 3
 
 
-def test_open_with_mode_w_minus(tmp_path: pathlib.Path) -> None:
+def test_open_with_mode_w_minus(tmp_path: Path) -> None:
     # 'w-' means create  (fail if exists)
     arr = zarr.open(store=tmp_path, mode="w-", shape=(3, 3))
     assert isinstance(arr, Array)
@@ -405,7 +398,7 @@ def test_load_array(sync_store: Store) -> None:
 
 @pytest.mark.parametrize("path", ["data", None])
 @pytest.mark.parametrize("load_read_only", [True, False, None])
-def test_load_zip(tmp_path: pathlib.Path, path: str | None, load_read_only: bool | None) -> None:
+def test_load_zip(tmp_path: Path, path: str | None, load_read_only: bool | None) -> None:
     file = tmp_path / "test.zip"
     data = np.arange(100).reshape(10, 10)
 
@@ -423,7 +416,7 @@ def test_load_zip(tmp_path: pathlib.Path, path: str | None, load_read_only: bool
 
 @pytest.mark.parametrize("path", ["data", None])
 @pytest.mark.parametrize("load_read_only", [True, False])
-def test_load_local(tmp_path: pathlib.Path, path: str | None, load_read_only: bool) -> None:
+def test_load_local(tmp_path: Path, path: str | None, load_read_only: bool) -> None:
     file = tmp_path / "test.zip"
     data = np.arange(100).reshape(10, 10)
 
@@ -1139,7 +1132,7 @@ async def test_open_falls_back_to_open_group_async(zarr_format: ZarrFormat) -> N
 
 
 @pytest.mark.parametrize("mode", ["r", "r+", "w", "a"])
-def test_open_modes_creates_group(tmp_path: pathlib.Path, mode: str) -> None:
+def test_open_modes_creates_group(tmp_path: Path, mode: str) -> None:
     # https://github.com/zarr-developers/zarr-python/issues/2490
     zarr_dir = tmp_path / f"mode-{mode}-test.zarr"
     if mode in ["r", "r+"]:

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Register 'gpu' marker with pytest for downstream StoreTests.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Expand the data type docs to include a demonstration of the ``parse_data_type`` function.
	`2`	+Expand the docstring for the ``parse_data_type`` function.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Ensure that all abstract methods of ``ZDType`` raise a ``NotImplementedError`` when invoked.