diff --git a/changes/2819.chore.rst b/changes/2819.chore.rst index f9a3358309..7fa68f86ef 100644 --- a/changes/2819.chore.rst +++ b/changes/2819.chore.rst @@ -1,4 +1,18 @@ Ensure that invocations of ``create_array`` use consistent keyword arguments, with consistent defaults. -Specifically, ``zarr.api.synchronous.create_array`` now takes a ``write_data`` keyword argument; The -``create_array`` method on ``zarr.Group`` takes ``data`` and ``write_data`` keyword arguments. The ``fill_value`` -keyword argument of the various invocations of ``create_array`` has been consistently set to ``None``, where previously it was either ``None`` or ``0``. \ No newline at end of file + +- ``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.