zarr-developers · d-v-b · Jul 15, 2025 · Jul 14, 2025 · Jul 14, 2025 · Jul 14, 2025
diff --git a/changes/2871.feature.rst b/changes/2871.feature.rst
diff --git a/changes/2874.feature.rst b/changes/2874.feature.rst
diff --git a/changes/3157.doc.rst b/changes/3157.doc.rst
diff --git a/changes/3170.bugfix.rst b/changes/3170.bugfix.rst
diff --git a/changes/3190.bugfix.rst b/changes/3190.bugfix.rst
diff --git a/changes/3191.feature.rst b/changes/3191.feature.rst
diff --git a/changes/3198.bugfix.rst b/changes/3198.bugfix.rst
diff --git a/changes/3212.doc.rst b/changes/3212.doc.rst
diff --git a/changes/3228.removal.rst b/changes/3228.removal.rst
diff --git a/changes/3232.bugfix.rst b/changes/3232.bugfix.rst
diff --git a/changes/3233.feature.rst b/changes/3233.feature.rst
diff --git a/changes/xxxx.feature.rst b/changes/xxxx.feature.rst
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
@@ -3,6 +3,104 @@ Release notes
 
 .. towncrier release notes start
 
+3.1.0 (2025-07-14)
+------------------
+
+Features
+~~~~~~~~
+
+- Added public API for Buffer ABCs and implementations.
+
+  Use :mod:`zarr.buffer` to access buffer implementations, and
+  :mod:`zarr.abc.buffer` for the interface to implement new buffer types.
+
+  Users previously importing buffer from ``zarr.core.buffer`` should update their
+  imports to use :mod:`zarr.buffer`. As a reminder, all of ``zarr.core`` is
+  considered a private API that's not covered by zarr-python's versioning policy. (:issue:`2871`)
+- Adds zarr-specific data type classes.
+
+  This change adds a ``ZDType`` base class for Zarr V2 and Zarr V3 data types. Child classes are
+  defined for each NumPy data type. Each child class defines routines for ``JSON`` serialization.
+  New data types can be created and registered dynamically.
+
+  Prior to this change, Zarr Python had two streams for handling data types. For Zarr V2 arrays,
+  we used NumPy data type identifiers. For Zarr V3 arrays, we used a fixed set of string enums. Both
+  of these systems proved hard to extend.
+
+  This change is largely internal, but it does change the type of the ``dtype`` and ``data_type``
+  fields on the ``ArrayV2Metadata`` and ``ArrayV3Metadata`` classes. Previously, ``ArrayV2Metadata.dtype``
+  was a NumPy ``dtype`` object, and ``ArrayV3Metadata.data_type`` was an internally-defined ``enum``.
+  After this change, both ``ArrayV2Metadata.dtype`` and ``ArrayV3Metadata.data_type`` are instances of
+  ``ZDType``. A NumPy data type can be generated from a ``ZDType`` via the ``ZDType.to_native_dtype()``
+  method. The internally-defined Zarr V3 ``enum`` class is gone entirely, but the ``ZDType.to_json(zarr_format=3)``
+  method can be used to generate either a string, or dictionary that has a string ``name`` field, that
+  represents the string value previously associated with that ``enum``.
+
+  For more on this new feature, see the `documentation </user-guide/data_types.html>`_ (:issue:`2874`)
+- Added `NDBuffer.empty` method for faster ndbuffer initialization. (:issue:`3191`)
+- The minimum version of NumPy has increased to 1.26. (:issue:`3226`)
+- Add an alternate `from_array_metadata_and_store` constructor to `CodecPipeline`. (:issue:`3233`)
+
+
+Bugfixes
+~~~~~~~~
+
+- Fixes a variety of issues related to string data types.
+
+  - Brings the ``VariableLengthUTF8`` data type Zarr V3 identifier in alignment with Zarr Python 3.0.8
+  - Disallows creation of 0-length fixed-length data types
+  - Adds a regression test for the ``VariableLengthUTF8`` data type that checks against version 3.0.8
+  - Allows users to request the ``VariableLengthUTF8`` data type with ``str``, ``"str"``, or ``"string"``. (:issue:`3170`)
+- Add human readable size for No. bytes stored to `info_complete` (:issue:`3190`)
+- Restores the ability to create a Zarr V2 array with a ``null`` fill value by introducing a new
+  class ``DefaultFillValue``, and setting the default value of the ``fill_value`` parameter in array
+  creation routines to an instance of ``DefaultFillValue``. For Zarr V3 arrays, ``None`` will act as an
+  alias for a ``DefaultFillValue`` instance, thus preserving compatibility with existing code. (:issue:`3198`)
+- Fix the type of ``ArrayV2Metadata.codec`` to constrain it to ``numcodecs.abc.Codec | None``.
+  Previously the type was more permissive, allowing objects that can be parsed into Codecs (e.g., the codec name).
+  The constructor of ``ArrayV2Metadata`` still allows the permissive input when creating new objects. (:issue:`3232`)
+
+
+Improved Documentation
+~~~~~~~~~~~~~~~~~~~~~~
+
+- Add a self-contained example of data type extension to the ``examples`` directory, and expanded
+  the documentation for data types. (:issue:`3157`)
+- - Add a description on how to create a RemoteStore of a specific filesystem to the `Remote Store` section in `docs\user-guide\storage.rst`.
+  - State in the docstring of `FsspecStore.from_url` that the filesystem type is inferred from the URL scheme.
+
+  It should help a user handling the case when the type of FsspecStore doesn't match the URL scheme. (:issue:`3212`)
+
+
+Deprecations and Removals
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Removes default chunk encoding settings (filters, serializer, compressors) from the global
+  configuration object.
+
+  This removal is justified on the basis that storing chunk encoding settings in the config required
+  a brittle, confusing, and inaccurate categorization of array data types, which was particularly
+  unsuitable after the recent addition of new data types that didn't fit naturally into the
+  pre-existing categories.
+
+  The default chunk encoding is the same (Zstandard compression, and the required object codecs for
+  variable length data types), but the chunk encoding is now generated by functions that cannot be
+  reconfigured at runtime. Users who relied on setting the default chunk encoding via the global configuration object should
+  instead specify the desired chunk encoding explicitly when creating an array.
+
+  This change also adds an extra validation step to the creation of Zarr V2 arrays, which ensures that
+  arrays with a ``VariableLengthUTF8`` or ``VariableLengthBytes`` data type cannot be created without the
+  correct "object codec". (:issue:`3228`)
+- Removes support for passing certain arguments positionally to the following functions and methods:
+  ``save_array``, ``open``, ``group``, ``open_group``, ``create``, ``get_basic_selection``, ``set_basic_selection``,
+  ``get_orthogonal_selection``,  ``set_orthogonal_selection``, ``get_mask_selection``, ``set_mask_selection``,
+  ``get_coordinate_selection``, ``set_coordinate_selection``, ``get_block_selection``, ``set_block_selection``,
+  ``Group.create_array``, ``Group.empty``, ``Group.zeroes``, ``Group.ones``, ``Group.empty_like``, ``Group.full``,
+  ``Group.zeros_like``, ``Group.ones_like``, ``Group.full_like``, ``Group.array``. Prior to this change,
+  we allowed arguments to these routines annotated as keyword-only to be passed positionally, with
+  a deprecation warning. That warning is now gone, and passing keyword-only arguments to these functions
+  and methods is now an error.
+
 3.0.10 (2025-07-03)
 -------------------