From 7dbbe70cf7c2750eae349cc934117d011c96ca39 Mon Sep 17 00:00:00 2001 From: David Stansby Date: Mon, 21 Jul 2025 16:50:43 +0100 Subject: [PATCH] Improve migration guide for codecs --- changes/3273.doc.rst | 1 + docs/user-guide/v3_migration.rst | 14 +++++++++++++- 2 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 changes/3273.doc.rst diff --git a/changes/3273.doc.rst b/changes/3273.doc.rst new file mode 100644 index 0000000000..b63b9c3fa3 --- /dev/null +++ b/changes/3273.doc.rst @@ -0,0 +1 @@ +Add a section on codecs to the migration guide. diff --git a/docs/user-guide/v3_migration.rst b/docs/user-guide/v3_migration.rst index a6258534e4..2b53e39b83 100644 --- a/docs/user-guide/v3_migration.rst +++ b/docs/user-guide/v3_migration.rst @@ -58,7 +58,7 @@ the following actions in order: vendor the parts of the specific modules that you need. * ``zarr.attrs`` has gone, with no replacement - * ``zarr.codecs`` has gone, use ``numcodecs`` instead + * ``zarr.codecs`` has changed, see "Codecs" section below for more information * ``zarr.context`` has gone, with no replacement * ``zarr.core`` remains but should be considered private API * ``zarr.hierarchy`` has gone, with no replacement (use ``zarr.Group`` inplace of ``zarr.hierarchy.Group``) @@ -178,6 +178,18 @@ If you are interested in developing a custom store that targets these backends, :ref:`developing custom stores ` or open an `issue `_ to discuss your use case. + +Codecs +~~~~~~ +Codecs defined in ``numcodecs`` (and also imported into the ``zarr.codecs`` namespace in Zarr-Python 2) +should still be used when creating Zarr format 2 arrays. + +Codecs for creating Zarr format 3 arrays are available in two locations: + +- `zarr.codecs` contains Zarr format 3 codecs that are defined in the `codecs section of the Zarr format 3 specification `_. +- `numcodecs.zarr3` contains codecs from ``numcodecs`` that can be used to create Zarr format 3 arrays, but are not necessarily part of the Zarr format 3 specification. + + Dependencies ~~~~~~~~~~~~