Upload folder using huggingface_hub (part 19)

.venv/lib/python3.11/site-packages/zarr-3.1.6.dist-info/INSTALLER

@@ -0,0 +1 @@
+uv

.venv/lib/python3.11/site-packages/zarr-3.1.6.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: zarr
+Version: 3.1.6
+Summary: An implementation of chunked, compressed, N-dimensional arrays for Python
+Project-URL: issues, https://github.com/zarr-developers/zarr-python/issues
+Project-URL: changelog, https://zarr.readthedocs.io/en/stable/release-notes.html
+Project-URL: Discussions, https://github.com/zarr-developers/zarr-python/discussions
+Project-URL: documentation, https://zarr.readthedocs.io/
+Project-URL: homepage, https://github.com/zarr-developers/zarr-python
+Author-email: Alistair Miles <alimanfoo@googlemail.com>
+Maintainer: jakirkham, Norman Rzepka, Ryan Abernathey, David Stansby, Deepak Cherian
+Maintainer-email: Davis Bennett <davis.v.bennett@gmail.com>, Josh Moore <josh@openmicroscopy.org>, Joe Hamman <joe@earthmover.io>, Juan Nunez-Iglesias <juan.nunez-iglesias@monash.edu>, Martin Durant <mdurant@anaconda.com>, Tom Augspurger <tom.w.augspurger@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: Python,compressed,ndimensional-arrays,zarr
+Classifier: Development Status :: 6 - Mature
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: donfig>=0.8
+Requires-Dist: google-crc32c>=1.5
+Requires-Dist: numcodecs>=0.14
+Requires-Dist: numpy>=2.0
+Requires-Dist: packaging>=22.0
+Requires-Dist: typing-extensions>=4.12
+Provides-Extra: cli
+Requires-Dist: typer; extra == 'cli'
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x; extra == 'gpu'
+Provides-Extra: optional
+Requires-Dist: universal-pathlib; extra == 'optional'
+Provides-Extra: remote
+Requires-Dist: fsspec>=2023.10.0; extra == 'remote'
+Requires-Dist: obstore>=0.5.1; extra == 'remote'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/zarr-developers/community/main/logos/logo2.png"><br>
+</div>
+
+# Zarr
+
+<table>
+<tr>
+  <td>Latest Release</td>
+  <td>
+    <a href="https://pypi.org/project/zarr/">
+    <img src="https://badge.fury.io/py/zarr.svg" alt="latest release" />
+    </a>
+  </td>
+</tr>
+<tr>
+  <td></td>
+  <td>
+    <a href="https://anaconda.org/anaconda/zarr/">
+    <img src="https://anaconda.org/conda-forge/zarr/badges/version.svg" alt="latest release" />
+    </a>
+</td>
+</tr>
+<tr>
+  <td>Package Status</td>
+  <td>
+    <a href="https://pypi.org/project/zarr/">
+    <img src="https://img.shields.io/pypi/status/zarr.svg" alt="status" />
+    </a>
+  </td>
+</tr>
+<tr>
+  <td>License</td>
+  <td>
+    <a href="https://github.com/zarr-developers/zarr-python/blob/main/LICENSE.txt">
+    <img src="https://img.shields.io/pypi/l/zarr.svg" alt="license" />
+    </a>
+</td>
+</tr>
+<tr>
+  <td>Build Status</td>
+  <td>
+    <a href="https://github.com/zarr-developers/zarr-python/blob/main/.github/workflows/python-package.yml">
+    <img src="https://github.com/zarr-developers/zarr-python/actions/workflows/python-package.yml/badge.svg" alt="build status" />
+    </a>
+  </td>
+</tr>
+<tr>
+  <td>Pre-commit Status</td>
+  <td>
+    <a href="https://github.com/zarr-developers/zarr-python/blob/main/.pre-commit-config.yaml">
+    <img src="https://results.pre-commit.ci/badge/github/zarr-developers/zarr-python/main.svg" alt="pre-commit status" />
+    </a>
+  </td>
+</tr>
+<tr>
+  <td>Coverage</td>
+  <td>
+    <a href="https://codecov.io/gh/zarr-developers/zarr-python">
+    <img src="https://codecov.io/gh/zarr-developers/zarr-python/branch/main/graph/badge.svg" alt="coverage" />
+    </a>
+  </td>
+</tr>
+<tr>
+  <td>Downloads</td>
+  <td>
+    <a href="https://zarr.readthedocs.io">
+    <img src="https://pepy.tech/badge/zarr" alt="pypi downloads" />
+    </a>
+  </td>
+</tr>
+<tr>
+  <td>Developer Chat</td>
+  <td>
+    <a href="https://ossci.zulipchat.com/">
+    <img src="https://img.shields.io/badge/zulip-join_chat-brightgreen.svg" />
+    </a>
+  </td>
+</tr>
+<tr>
+  <td>Funding</td>
+  <td>
+    <a href="https://chanzuckerberg.com/eoss/">
+    <img src="https://img.shields.io/badge/funded%20by-EOSS-FF414B.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI0NSIgaGVpZ2h0PSI0NSI+PHBhdGggZD0iTTIyLjA5OCAyMS4wNzRjLTEuMjM1Ljg2LTIuNjggMS4zOTktNC42ODggMS40MzgtMi40MjYuMDUtNC4yMzgtMS41NTEtNC40MDYtMy45MThhNC40NjUgNC40NjUgMCAwIDEgMS4xODctMy4zOCA0LjQ4IDQuNDggMCAwIDEgMy4yODYtMS40NDQgNC42NzQgNC42NzQgMCAwIDEgMS44OTQuMzc1cy0uMTU2IDEuMzItLjIxIDEuOTE0bDEuOTg3LjAxNS4zNTYtMi45NzYtLjU2My0uMzU2YTYuNTQxIDYuNTQxIDAgMCAwLTMuNDg0LS45NjkgNi41OTMgNi41OTMgMCAwIDAtNC43NSAyLjA4NiA2LjQxNSA2LjQxNSAwIDAgMC0xLjcxNSA0Ljg3NWMuMTEzIDEuNjEuODA5IDMuMDc4IDEuOTUgNC4xNDEgMS4xNTYgMS4wNyAyLjcxNCAxLjY0NSA0LjM5OCAxLjYzMy4wMzkgMCAuMDc4IDAgLjEyNS0uMDA0YTkuOTE4IDkuOTE4IDAgMCAwIDMuNDMzLS43MjNsMS40MzQtMi43ODlzLS4wMjctLjA2Mi0uMjM0LjA3OCIgc3R5bGU9InN0cm9rZTpub25lO2ZpbGwtcnVsZTpub256ZXJvO2ZpbGw6I2ZmZjtmaWxsLW9wYWNpdHk6MSIvPjxwYXRoIGQ9Im0yOC44NjMgMjguMjE1LS4yNDIgMi43NDJ2LjAzMWMtLjEwMSAxLjAzNS0uNjUyIDEuOTE0LTEuNDg0IDIuMzUyLS42Ni4zNDctMS4zOC4zNDctMi4wMjgtLjAwOC0uNjc1LS4zNjMtLjk5Mi0uOTE4LTEuMTE3LTEuNjEzLS4xODctMS4xMDIuNDM4LTIuMjU0IDEuMjkzLTIuODMybDEzLjM1Mi04LjY4OGMuMDk3LjczOC4xNTIgMS40ODUuMTUyIDIuMjUgMCA4Ljk5Mi03LjMwOSAxNi4zMDUtMTYuMjkzIDE2LjMwNS04Ljk4OCAwLTE2LjI4OS03LjMxMy0xNi4yODktMTYuMzA1IDAtOC45ODggNy4zMDUtMTYuMyAxNi4yOTMtMTYuM3MxMi40OTYgNC4wOSAxNC45ODQgOS45MUwzOS4xMTQgMTVDMzYuMjYxIDguNjY0IDI5Ljg5MyA0LjIzNCAyMi41IDQuMjM0Yy03LjM5NSAwLTE4LjIxNSA4LjE3Mi0xOC4yMTUgMTguMjE1IDAgMTAuMDQ3IDguMTcyIDE4LjIxMSAxOC4yMTEgMTguMjExIDEwLjA0IDAgMTguMjE1LTguMTcyIDE4LjIxNS0xOC4yMSAwLTEwLjA0LS4xMS0yLjI5NC0uMzEzLTMuMzkxYTE5Ljk5NyAxOS45OTcgMCAwIDAtLjQ1My0xLjgzMmwtMy43OTMgMi4zNy01LjAyIDMuMThjLS4xNzUtLjY2OC0uNTgxLTEuMzQzLTEuNDQtMS43My0xLjAxMi0uNDY1LTIuNjYtLjExLTMuODY4LjU4MiAwIDAgMy4zMDUtNi40MDIgMy44Ni03LjQ1LjAzNS0uMDY2LS4wMTYtLjE0OC0uMDk4LS4xNDhoLTYuMThsLS4yNSAyLjA2N0gyNi41MDhsLTQuNzMgOS4wNjJjLS4wOTQuMTc2LjA5Ny4zNjMuMjc3LjI3NGwyLjUyMy0xLjM0YzEuMjE5LS42MjUgMy4yNS0xLjkxIDQuMjU0LTEuMTY4LjE0NS4xMS4zMzIuMzk4LjM0OC42OTVhLjM1Ny4zNTcgMCAwIDEtLjE0OS4yOTNsLTUuMDQzIDMuNDA2Yy0xLjYzNiAxLjE2OC0yLjI3NyAyLjkxLTIuMTIgNC41NTUuMTI0IDEuMzc1Ljk4NCAyLjU2NiAyLjI1NyAzLjI2MmE0LjE3IDQuMTcgMCAwIDAgMi4xMTMuNTE1IDQuMTY5IDQuMTY5IDAgMCAwIDEuODY0LS41YzEuNDM3LS43NTQgMi4zOTQtMi4yMzQgMi41NjItMy45NDVsLjQwMi00LjYxMy0yLjE5OSAxLjYzM1ptMCAwIiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOm5vbnplcm87ZmlsbDojZmZmO2ZpbGwtb3BhY2l0eToxIi8+PC9zdmc+" alt="CZI's Essential Open Source Software for Science" />
+    </a>
+  </td>
+</tr>
+<tr>
+  <td>Citation</td>
+  <td>
+    <a href="https://doi.org/10.5281/zenodo.3773450">
+    <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.3773450.svg" alt="DOI" />
+    </a>
+  </td>
+</tr>
+
+</table>
+
+## What is it?
+
+Zarr is a Python package providing an implementation of compressed, chunked, N-dimensional arrays, designed for use in parallel computing. See the [documentation](https://zarr.readthedocs.io) for more information.
+
+## Main Features
+
+- [**Create**](https://zarr.readthedocs.io/en/stable/user-guide/arrays.html#creating-an-array) N-dimensional arrays with any NumPy `dtype`.
+- [**Chunk arrays**](https://zarr.readthedocs.io/en/stable/user-guide/performance.html#chunk-optimizations) along any dimension.
+- [**Compress**](https://zarr.readthedocs.io/en/stable/user-guide/arrays.html#compressors) and/or filter chunks using any NumCodecs codec.
+- [**Store arrays**](https://zarr.readthedocs.io/en/stable/user-guide/storage.html) in memory, on disk, inside a zip file, on S3, etc...
+- [**Read**](https://zarr.readthedocs.io/en/stable/user-guide/arrays.html#reading-and-writing-data) an array [**concurrently**](https://zarr.readthedocs.io/en/stable/user-guide/performance.html#parallel-computing-and-synchronization) from multiple threads or processes.
+- [**Write**](https://zarr.readthedocs.io/en/stable/user-guide/arrays.html#reading-and-writing-data) to an array concurrently from multiple threads or processes.
+- Organize arrays into hierarchies via [**groups**](https://zarr.readthedocs.io/en/stable/quickstart.html#hierarchical-groups).
+
+## Where to get it
+
+Zarr can be installed from PyPI using `pip`:
+
+```bash
+pip install zarr
+```
+
+or via `conda`:
+
+```bash
+conda install -c conda-forge zarr
+```
+
+For more details, including how to install from source, see the [installation documentation](https://zarr.readthedocs.io/en/stable/index.html#installation).

.venv/lib/python3.11/site-packages/zarr-3.1.6.dist-info/RECORD

@@ -0,0 +1,103 @@
+../../../bin/zarr,sha256=PG0LRLGAhLssz-2QBC3m0yp4HOpbKfCfrnf235ik8hE,342
+zarr-3.1.6.dist-info/INSTALLER,sha256=5hhM4Q4mYTT9z6QB6PGpUAW81PGNFrYrdXMj4oM_6ak,2
+zarr-3.1.6.dist-info/METADATA,sha256=-diAtnIVxk9WPannPXucRNDlga_53MNQVUfW6VAPRUM,8608
+zarr-3.1.6.dist-info/RECORD,,
+zarr-3.1.6.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zarr-3.1.6.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+zarr-3.1.6.dist-info/entry_points.txt,sha256=87EDiIFOzr9bpH-HNPSQRDKM-p9unAZrBvybRDNCEcw,75
+zarr-3.1.6.dist-info/licenses/LICENSE.txt,sha256=HXdW8z09og1TsWLC65vrqR7g3BrrRllyi23I8vdZQcs,1124
+zarr/__init__.py,sha256=s8jh56_lxQLeevIDxX93X5wsmTOrx17NWoQ6rjQd24A,4270
+zarr/_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zarr/_cli/cli.py,sha256=uTI0eBKOkh8Lanr1DyX2HxgcWeVbtpVnSrYGis5Hg2E,5852
+zarr/_compat.py,sha256=a6rDJz6Z7R4wcFgfkOw8BmgPb20CwO0tfE7fU1h4d6c,3589
+zarr/_version.py,sha256=LCICTIfLZ__LkFNkrPDD-bSal5fP2QP0iQ5beTR8e2Y,704
+zarr/abc/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zarr/abc/buffer.py,sha256=EHVr5Dwg759DzFEqwN2diAaNeUcXlF68lvyFBbaCJbA,196
+zarr/abc/codec.py,sha256=GI34j_VwNVPMaIkyLqWryhKMPKDfD7-D-SkIkrDw5Qw,16290
+zarr/abc/metadata.py,sha256=c1IkPTX3rEO_5pY9T05OH6uZbnhVvGHUV--GbMxpzoM,1405
+zarr/abc/numcodec.py,sha256=pJbdF-NqsJZEu_TvuEZj3QJManR6wXNRCaVOTfLBa40,2814
+zarr/abc/store.py,sha256=MkpqzxU7zb7cxrBAj_JGBX0lq-72k1Hrg0ajzaILYTo,23663
+zarr/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zarr/api/asynchronous.py,sha256=CFNu9K7_tfs0HXdJz-ApqrNNVZ1069qNRiSKulnVNb0,49204
+zarr/api/synchronous.py,sha256=1MHbYAq6rGbThqa5HWBhCGZlwx34gD1PIi-CGEh3NFM,54557
+zarr/buffer/__init__.py,sha256=qJ_P2iFiWwwW1EnNJzJnRlv0JWgZQR09OCYDOeOr6E4,283
+zarr/buffer/cpu.py,sha256=ZMXfM3bgxk_Dar9R9BaNtt2oaF9D34p2_Bz_CHsgDYE,270
+zarr/buffer/gpu.py,sha256=6CjqB7BFb4oG1QkqF1O2VF8lT3Set2i4PDPhgbWYXpw,137
+zarr/codecs/__init__.py,sha256=QhbUyxk17cwe9Ag7Xc70xSuW35YyYrvG9QJ_idfrs78,3410
+zarr/codecs/_v2.py,sha256=fwymGyufsW5dd6Ba2y_EF0oLRLSfw50Yy1p9wy0lzZE,3649
+zarr/codecs/blosc.py,sha256=64fw9-OFH94Mcv8rNeymocRxTY5AMMkQGlerEshjyaY,11074
+zarr/codecs/bytes.py,sha256=d7iMb0G4hb71Ll2H4S3PgjMwSw8Sdy1v_ssXhTgGenU,4183
+zarr/codecs/crc32c_.py,sha256=2c5QCjLSbEgvbU3cWSrgM2HH9vxGkuHYL0afpsZzbg0,2572
+zarr/codecs/gzip.py,sha256=1TjO91IVemCIfQ5BwMexzcNcvXAJmQXzfI0Qnw_FZhM,2503
+zarr/codecs/numcodecs/__init__.py,sha256=9E4nPdDj10lgCEsqNlcfAg8X4MPmVk_VsnfOBM8d0bI,901
+zarr/codecs/numcodecs/_codecs.py,sha256=P13EXUHc-o0Kqoj2zLuyrS8Dm-czpR1pXA1yn5BIZJY,11953
+zarr/codecs/sharding.py,sha256=pDxta4FW4laLjsDDHwQS5E-rKf38H8msi4bkrLJzgZo,28162
+zarr/codecs/transpose.py,sha256=ZluSDxmHBzIySLOvSmvcusqGTKHO-lUkiErrJVdEe3I,4463
+zarr/codecs/vlen_utf8.py,sha256=CoOfIqma7THsLQOnlFSh60ulvk2vYDIMfe8sgnVa-KA,4536
+zarr/codecs/zstd.py,sha256=groE9suVC8Imuzg5eprg4HXIfCwGp96s40NvXG9TK6Y,3324
+zarr/convenience.py,sha256=ysKzQGUWaSey7I9LJMYhK3NSgJW0iRBoF8RI_FV0uYQ,800
+zarr/core/__init__.py,sha256=vPyRTNVnQXIblFLBgdbcs9CBGsL6xa3RmEGrQbHVXQY,283
+zarr/core/_info.py,sha256=yPWnlqPSryJXy2tCnyxiYt7spG4oSIuJJIMmCNw09eo,5015
+zarr/core/_tree.py,sha256=WTv5vafZOTu4YIzEJe_WtSH7e59nx6zPfvrxsVnmSLU,5074
+zarr/core/array.py,sha256=ff-XPTnzvGK3JNcn4uWf3MPtYzfInDY6Sncl9q-JTLM,222706
+zarr/core/array_spec.py,sha256=URY0qzEz13wxoYSEfER8ofUUFqqZGa0f8ajJLI6oz5s,3855
+zarr/core/attributes.py,sha256=wRNaIjvLMW8tgh1iw4dB1s08xvgEF4DMhW0a9HR81CE,1687
+zarr/core/buffer/__init__.py,sha256=jnvcnaKdaWfOpmNPOdf4adFeYnh2gTaK-dFI0dVzJxc,421
+zarr/core/buffer/core.py,sha256=IJxnBEY8RJsT6BxQ5LvyiXIhIsuym3MJKQuMqk3XzUs,18024
+zarr/core/buffer/cpu.py,sha256=k2uLEcE10_bb3UPpOp_AGvA4aPCDT-17luF5zDr69o4,7690
+zarr/core/buffer/gpu.py,sha256=4hCdSBtDzLWyyXeTehHSEqqjqQyrk6NAVOO6hT0D48Q,7777
+zarr/core/chunk_grids.py,sha256=H0bwdTOsQH5okmpBZEE1yS-hhZ4FVV8I9nOnPoBdo7U,10655
+zarr/core/chunk_key_encodings.py,sha256=s0NDx4bAjWHRE_Epk3EPJoZhQkHomasJNcrmX-o-dd0,4379
+zarr/core/codec_pipeline.py,sha256=aYadeiOGNNfhIbSpiAKp9FbaPqlODr7geQYdWI-y0Ng,22003
+zarr/core/common.py,sha256=AFi00SCRtsfRSxsqmjUWi9Z4s7NzYX8U5NO7qE8ikj4,7834
+zarr/core/config.py,sha256=lWPBGQm4xrwQd9Woye7Ok0RRE-mjdfLARvE4KSWD1m4,6283
+zarr/core/dtype/__init__.py,sha256=tO6uM5pxHie1tuEosYNRm5M9lMMi29gJeSQznoj0Dfc,9111
+zarr/core/dtype/common.py,sha256=HIbGlU1Ja_3G7FcF3wuNuJkebu_Bn9seLRWKRCehukc,8651
+zarr/core/dtype/npy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zarr/core/dtype/npy/bool.py,sha256=HRUqa-DtUpTAm9nZcrOg7ikQ-tNy3AwHHn_yPbVy41c,8908
+zarr/core/dtype/npy/bytes.py,sha256=7h_uA75HyX7uJ5frcgZMeeNsjoHnreUMvpElFVNDE9c,39979
+zarr/core/dtype/npy/common.py,sha256=-mQSr44DuJ-Emp_enxPNIq3-E37Ia6Mj8WMHlPgwAu0,14314
+zarr/core/dtype/npy/complex.py,sha256=o0-2hlqQx7rB2UhvaVj0JdawEw7QUWCYFXJlTXIhVL4,12928
+zarr/core/dtype/npy/float.py,sha256=BCBZj9oLVjwpYZT3pb2aA-sBeWyfffHzOcXw_Xgu3GU,13631
+zarr/core/dtype/npy/int.py,sha256=PbUz-OEQkdCb6X_K4soF1wVYvU7BWLF6mhYsTgOdCFw,47134
+zarr/core/dtype/npy/string.py,sha256=IYsgr8asN8yYG_YOFbtLgk11iV8O27bZKG3dD4ZdkqM,24952
+zarr/core/dtype/npy/structured.py,sha256=y2k6fJd8G9iVq6oF0neyBeygCazdWAS-8Z01ayI-Z0Q,15332
+zarr/core/dtype/npy/time.py,sha256=8tTA2jMtLPMN1BHuibUjdjUmnboQ-4Z7Hy2r4O7iw8U,27921
+zarr/core/dtype/registry.py,sha256=m-edO29HLCAdPdWpAy_Eph5L_YTS0kMsw2E2gk17e2E,7396
+zarr/core/dtype/wrapper.py,sha256=xJvjMDWm0T_ArG3eD_qnzZ0IyYOm5m038EzovHu6-OU,9724
+zarr/core/group.py,sha256=vLoumjmvibKg-0nFDQ_yiNzHWcHbSqrsGgHKMlCNzEI,150283
+zarr/core/indexing.py,sha256=TynMb87bWmL6XJ31UzPn6PmpNitJxIyeL7U00yY-ST8,60057
+zarr/core/metadata/__init__.py,sha256=ej8tBNY67cbFAQdjQo8akiyFgdnNFXtN5SzaRD0cDk4,539
+zarr/core/metadata/common.py,sha256=r2w276Hnok9EWqb2D8uWKMqq7PhUKhc7PvQOX3W44SE,255
+zarr/core/metadata/io.py,sha256=2EiPzMtqv-AD5xEIiZqepMuV34yiqR3vxSdNESXHxro,3194
+zarr/core/metadata/v2.py,sha256=PJk-Tb2pl2cawRMbzNaHoA779LLAWKVWpe0FrKkxVy0,12557
+zarr/core/metadata/v3.py,sha256=wIEDF621hb9brc_aSCJH8UVPwWripHK265n8duG2RZ8,17250
+zarr/core/sync.py,sha256=YW6RRuupot1GbOBA7hXDfp3SsFRKyI8cKcTY2koPSSk,7319
+zarr/core/sync_group.py,sha256=EC-s7osWK6Csj0yCTwaTV814pwi92XLm-LD5JYnMAyY,6063
+zarr/creation.py,sha256=qkqT4ibcoE1ovVLvOD_m7ja_TVKJLhPsMc169M0A4Zo,802
+zarr/dtype.py,sha256=6UirY7ewXg4Oa7BSLKuVB_klwrUWI3EY7AKkzGaIH8Q,1828
+zarr/errors.py,sha256=9rGz46pr1VMQKCkWv65MRc2h5M0YlxWriHMEg17OlYU,3679
+zarr/experimental/__init__.py,sha256=d5z1ssdeTxAhWIUFQ9c5vWSd4FlBJBDVeLhAGfXegZE,89
+zarr/experimental/cache_store.py,sha256=_7rqe82js0ZZHZZoZXTMxAmdHeyGcyCxuywjIYbjw68,17282
+zarr/metadata/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zarr/metadata/migrate_v3.py,sha256=5IqCWcqDZQmNbRKdeTOzyyRY51uu9wqXXsx4DcEqVAY,10453
+zarr/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zarr/registry.py,sha256=rbJnN7QZL-Vb1pQTyjGAFEDTTkVzQPdi1pKgFJhvZmI,11490
+zarr/storage/__init__.py,sha256=u3WB2W2ufq-zveezvceyfMBtlbvsO8sQeBBmqNvIIis,1331
+zarr/storage/_common.py,sha256=8vEsKZCT1nA4dMMD30emCTR1jkMwbCvzeS0iy2GAALk,22615
+zarr/storage/_fsspec.py,sha256=FI9kJ-XC38ONObOACsJWQ68IURtqO5zj0OgDWZciZgw,14702
+zarr/storage/_local.py,sha256=NChyhZkaPs4NNzMXLrYDAHEbQd7vkotZsnKrLSCY07Y,20278
+zarr/storage/_logging.py,sha256=9rWvjpZLtvi0fs9Lu30YZ6EvwZqBNaucLO6WTpER1PU,7546
+zarr/storage/_memory.py,sha256=OseWGwGvT6S_Lvg8eGoo4twjtOsaeV37_NdLgrmPONo,17582
+zarr/storage/_obstore.py,sha256=8T17S05SrS80NOJUGauhpU8IPWo_FXyrmmpRh1ppr8w,17505
+zarr/storage/_utils.py,sha256=FkoUnXY7wEZTHiL-bdnkThGqQRPhSbQp8csEVc4o6Ng,4969
+zarr/storage/_wrapper.py,sha256=OBh6r1WNGeQqtYlxewrkN-JXJzoRvrkn40WOW3UG_ZQ,4876
+zarr/storage/_zip.py,sha256=Yc2RKoNFhOKkQq4XBNvvyB3cuyQUsjjQRAViy1hGMSY,9232
+zarr/testing/__init__.py,sha256=d1QaEs3zOnKTEQSDX1Z62HgsEEGQnjM7RjH3UU1Jkfg,436
+zarr/testing/buffer.py,sha256=r2E0FMSomfPaXocxs0t07xotgoClEdkpYbH70v6hLig,2330
+zarr/testing/conftest.py,sha256=IxBNMxVMC_PNze4KoSdnjWsMgrA8iU_aHBuiHJFq0lk,456
+zarr/testing/stateful.py,sha256=TFQYgsGlqNcGkpt9PR_py8H9croxdkmryiJoYwQ_Yhs,24665
+zarr/testing/store.py,sha256=Lo3gTsk33eIJUqZFHvcbVnZSXAobQ1c_QOeNbvHK9BM,27570
+zarr/testing/strategies.py,sha256=GlFnSvJ76Y7ayslJXP6zygGiXczlJvRPc-mfDhpMmSU,15509
+zarr/testing/utils.py,sha256=C0CMZsoDm4MfWWo00m2ZdH2JAmVZ4DrKvt3K5N7kGgs,1121
+zarr/types.py,sha256=lSktZQyOx7yn-BKrJZvxdpP-SDQkrFBfBxUhJDyb1Bk,664

.venv/lib/python3.11/site-packages/zarr-3.1.6.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

.venv/lib/python3.11/site-packages/zarr-3.1.6.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+zarr = zarr._cli.cli:app
+
+[pytest11]
+zarr = zarr.testing

.venv/lib/python3.11/site-packages/zarr-3.1.6.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2025 Zarr Developers <https://github.com/zarr-developers>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.venv/lib/python3.11/site-packages/zarr/core/attributes.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import TYPE_CHECKING
+
+from zarr.core.common import JSON
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from zarr.core.group import Group
+    from zarr.types import AnyArray
+
+
+class Attributes(MutableMapping[str, JSON]):
+    def __init__(self, obj: AnyArray | Group) -> None:
+        # key=".zattrs", read_only=False, cache=True, synchronizer=None
+        self._obj = obj
+
+    def __getitem__(self, key: str) -> JSON:
+        return self._obj.metadata.attributes[key]
+
+    def __setitem__(self, key: str, value: JSON) -> None:
+        new_attrs = dict(self._obj.metadata.attributes)
+        new_attrs[key] = value
+        self._obj = self._obj.update_attributes(new_attrs)
+
+    def __delitem__(self, key: str) -> None:
+        new_attrs = dict(self._obj.metadata.attributes)
+        del new_attrs[key]
+        self.put(new_attrs)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._obj.metadata.attributes)
+
+    def __len__(self) -> int:
+        return len(self._obj.metadata.attributes)
+
+    def put(self, d: dict[str, JSON]) -> None:
+        """
+        Overwrite all attributes with the values from `d`.
+
+        Equivalent to the following pseudo-code, but performed atomically.
+
+        ```python
+        attrs = {"a": 1, "b": 2}
+        attrs.clear()
+        attrs.update({"a": "3", "c": 4})
+        print(attrs)
+        #> {'a': '3', 'c': 4}
+        ```
+        """
+        self._obj.metadata.attributes.clear()
+        self._obj = self._obj.update_attributes(d)
+
+    def asdict(self) -> dict[str, JSON]:
+        return dict(self._obj.metadata.attributes)

.venv/lib/python3.11/site-packages/zarr/core/buffer/__init__.py

@@ -0,0 +1,21 @@
+from zarr.core.buffer.core import (
+    ArrayLike,
+    Buffer,
+    BufferPrototype,
+    NDArrayLike,
+    NDArrayLikeOrScalar,
+    NDBuffer,
+    default_buffer_prototype,
+)
+from zarr.core.buffer.cpu import numpy_buffer_prototype
+
+__all__ = [
+    "ArrayLike",
+    "Buffer",
+    "BufferPrototype",
+    "NDArrayLike",
+    "NDArrayLikeOrScalar",
+    "NDBuffer",
+    "default_buffer_prototype",
+    "numpy_buffer_prototype",
+]

.venv/lib/python3.11/site-packages/zarr/core/buffer/core.py

@@ -0,0 +1,586 @@
+from __future__ import annotations
+
+import sys
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    NamedTuple,
+    Protocol,
+    SupportsIndex,
+    cast,
+    runtime_checkable,
+)
+
+import numpy as np
+import numpy.typing as npt
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+    from typing import Self
+
+    from zarr.codecs.bytes import Endian
+    from zarr.core.common import BytesLike
+
+# Everything here is imported into ``zarr.core.buffer`` namespace.
+__all__: list[str] = []
+
+
+@runtime_checkable
+class ArrayLike(Protocol):
+    """Protocol for the array-like type that underlie Buffer"""
+
+    @property
+    def dtype(self) -> np.dtype[Any]: ...
+
+    @property
+    def ndim(self) -> int: ...
+
+    @property
+    def size(self) -> int: ...
+
+    def __getitem__(self, key: slice) -> Self: ...
+
+    def __setitem__(self, key: slice, value: Any) -> None: ...
+
+
+@runtime_checkable
+class NDArrayLike(Protocol):
+    """Protocol for the nd-array-like type that underlie NDBuffer"""
+
+    @property
+    def dtype(self) -> np.dtype[Any]: ...
+
+    @property
+    def ndim(self) -> int: ...
+
+    @property
+    def size(self) -> int: ...
+
+    @property
+    def shape(self) -> tuple[int, ...]: ...
+
+    def __len__(self) -> int: ...
+
+    def __getitem__(self, key: slice) -> Self: ...
+
+    def __setitem__(self, key: slice, value: Any) -> None: ...
+
+    def __array__(self) -> npt.NDArray[Any]: ...
+
+    def reshape(
+        self, shape: tuple[int, ...] | Literal[-1], *, order: Literal["A", "C", "F"] = ...
+    ) -> Self: ...
+
+    def view(self, dtype: npt.DTypeLike) -> Self: ...
+
+    def astype(
+        self,
+        dtype: npt.DTypeLike,
+        order: Literal["K", "A", "C", "F"] = ...,
+        *,
+        copy: bool = ...,
+    ) -> Self: ...
+
+    def fill(self, value: Any) -> None: ...
+
+    def copy(self) -> Self: ...
+
+    def transpose(self, axes: SupportsIndex | Sequence[SupportsIndex] | None) -> Self: ...
+
+    def ravel(self, order: Literal["K", "A", "C", "F"] = ...) -> Self: ...
+
+    def all(self) -> bool: ...
+
+    def __eq__(self, other: object) -> Self:  # type: ignore[override]
+        """Element-wise equal
+
+        Notes
+        -----
+        Type checkers such as mypy complains because the return type isn't a bool like
+        its supertype "object", which violates the Liskov substitution principle.
+        This is true, but since NumPy's ndarray is defined as an element-wise equal,
+        our hands are tied.
+        """
+
+
+ScalarType = int | float | complex | bytes | str | bool | np.generic
+NDArrayLikeOrScalar = ScalarType | NDArrayLike
+
+
+def check_item_key_is_1d_contiguous(key: Any) -> None:
+    """Raises error if `key` isn't a 1d contiguous slice"""
+    if not isinstance(key, slice):
+        raise TypeError(
+            f"Item key has incorrect type (expected slice, got {key.__class__.__name__})"
+        )
+    if not (key.step is None or key.step == 1):
+        raise ValueError("slice must be contiguous")
+
+
+class Buffer(ABC):
+    """A flat contiguous memory block
+
+    We use Buffer throughout Zarr to represent a contiguous block of memory.
+
+    A Buffer is backed by an underlying array-like instance that represents
+    the memory. The memory type is unspecified; can be regular host memory,
+    CUDA device memory, or something else. The only requirement is that the
+    array-like instance can be copied/converted to a regular Numpy array
+    (host memory).
+
+    Notes
+    -----
+    This buffer is untyped, so all indexing and sizes are in bytes.
+
+    Parameters
+    ----------
+    array_like
+        array-like object that must be 1-dim, contiguous, and byte dtype.
+    """
+
+    def __init__(self, array_like: ArrayLike) -> None:
+        if array_like.ndim != 1:
+            raise ValueError("array_like: only 1-dim allowed")
+        if array_like.dtype != np.dtype("B"):
+            raise ValueError("array_like: only byte dtype allowed")
+        self._data = array_like
+
+    @classmethod
+    @abstractmethod
+    def create_zero_length(cls) -> Self:
+        """Create an empty buffer with length zero
+
+        Returns
+        -------
+            New empty 0-length buffer
+        """
+        if cls is Buffer:
+            raise NotImplementedError("Cannot call abstract method on the abstract class 'Buffer'")
+        return cls(
+            cast("ArrayLike", None)
+        )  # This line will never be reached, but it satisfies the type checker
+
+    @classmethod
+    def from_array_like(cls, array_like: ArrayLike) -> Self:
+        """Create a new buffer of an array-like object
+
+        Parameters
+        ----------
+        array_like
+            array-like object that must be 1-dim, contiguous, and byte dtype.
+
+        Returns
+        -------
+            New buffer representing `array_like`
+        """
+        return cls(array_like)
+
+    @classmethod
+    @abstractmethod
+    def from_buffer(cls, buffer: Buffer) -> Self:
+        """Create a new buffer of an existing Buffer
+
+        This is useful if you want to ensure that an existing buffer is
+        of the correct subclass of Buffer. E.g., MemoryStore uses this
+        to return a buffer instance of the subclass specified by its
+        BufferPrototype argument.
+
+        Typically, this only copies data if the data has to be moved between
+        memory types, such as from host to device memory.
+
+        Parameters
+        ----------
+        buffer
+            buffer object.
+
+        Returns
+        -------
+            A new buffer representing the content of the input buffer
+
+        Notes
+        -----
+        Subclasses of `Buffer` must override this method to implement
+        more optimal conversions that avoid copies where possible
+        """
+        if cls is Buffer:
+            raise NotImplementedError("Cannot call abstract method on the abstract class 'Buffer'")
+        return cls(
+            cast("ArrayLike", None)
+        )  # This line will never be reached, but it satisfies the type checker
+
+    @classmethod
+    @abstractmethod
+    def from_bytes(cls, bytes_like: BytesLike) -> Self:
+        """Create a new buffer of a bytes-like object (host memory)
+
+        Parameters
+        ----------
+        bytes_like
+            bytes-like object
+
+        Returns
+        -------
+            New buffer representing `bytes_like`
+        """
+        if cls is Buffer:
+            raise NotImplementedError("Cannot call abstract method on the abstract class 'Buffer'")
+        return cls(
+            cast("ArrayLike", None)
+        )  # This line will never be reached, but it satisfies the type checker
+
+    def as_array_like(self) -> ArrayLike:
+        """Returns the underlying array (host or device memory) of this buffer
+
+        This will never copy data.
+
+        Returns
+        -------
+            The underlying 1d array such as a NumPy or CuPy array.
+        """
+        return self._data
+
+    @abstractmethod
+    def as_numpy_array(self) -> npt.NDArray[Any]:
+        """Returns the buffer as a NumPy array (host memory).
+
+        Notes
+        -----
+        Might have to copy data, consider using `.as_array_like()` instead.
+
+        Returns
+        -------
+            NumPy array of this buffer (might be a data copy)
+        """
+        ...
+
+    def as_buffer_like(self) -> BytesLike:
+        """Returns the buffer as an object that implements the Python buffer protocol.
+
+        Notes
+        -----
+        Might have to copy data, since the implementation uses `.as_numpy_array()`.
+
+        Returns
+        -------
+            An object that implements the Python buffer protocol
+        """
+        return memoryview(self.as_numpy_array())  # type: ignore[arg-type]
+
+    def to_bytes(self) -> bytes:
+        """Returns the buffer as `bytes` (host memory).
+
+        Warnings
+        --------
+        Will always copy data, only use this method for small buffers such as metadata
+        buffers. If possible, use `.as_numpy_array()` or `.as_array_like()` instead.
+
+        Returns
+        -------
+            `bytes` of this buffer (data copy)
+        """
+        return bytes(self.as_numpy_array())
+
+    def __getitem__(self, key: slice) -> Self:
+        check_item_key_is_1d_contiguous(key)
+        return self.__class__(self._data.__getitem__(key))
+
+    def __setitem__(self, key: slice, value: Any) -> None:
+        check_item_key_is_1d_contiguous(key)
+        self._data.__setitem__(key, value)
+
+    def __len__(self) -> int:
+        return self._data.size
+
+    @abstractmethod
+    def combine(self, others: Iterable[Buffer]) -> Self:
+        """Concatenate many buffers"""
+        ...
+
+    def __add__(self, other: Buffer) -> Self:
+        """Concatenate two buffers"""
+        return self.combine([other])
+
+    def __eq__(self, other: object) -> bool:
+        # Another Buffer class can override this to choose a more efficient path
+        return isinstance(other, Buffer) and np.array_equal(
+            self.as_numpy_array(), other.as_numpy_array()
+        )
+
+
+class NDBuffer:
+    """An n-dimensional memory block
+
+    We use NDBuffer throughout Zarr to represent a n-dimensional memory block.
+
+    An NDBuffer is backed by an underlying ndarray-like instance that represents
+    the memory. The memory type is unspecified; can be regular host memory,
+    CUDA device memory, or something else. The only requirement is that the
+    ndarray-like instance can be copied/converted to a regular Numpy array
+    (host memory).
+
+    Notes
+    -----
+    The two buffer classes Buffer and NDBuffer are very similar. In fact, Buffer
+    is a special case of NDBuffer where dim=1, stride=1, and dtype="B". However,
+    in order to use Python's type system to differentiate between the contiguous
+    Buffer and the n-dim (non-contiguous) NDBuffer, we keep the definition of the
+    two classes separate.
+
+    Parameters
+    ----------
+    array : ndarray_like
+        ndarray-like object that is convertible to a regular Numpy array.
+    """
+
+    def __init__(self, array: NDArrayLike) -> None:
+        self._data = array
+
+    @classmethod
+    @abstractmethod
+    def create(
+        cls,
+        *,
+        shape: Iterable[int],
+        dtype: npt.DTypeLike,
+        order: Literal["C", "F"] = "C",
+        fill_value: Any | None = None,
+    ) -> Self:
+        """Create a new buffer and its underlying ndarray-like object
+
+        Parameters
+        ----------
+        shape
+            The shape of the buffer and its underlying ndarray-like object
+        dtype
+            The datatype of the buffer and its underlying ndarray-like object
+        order
+            Whether to store multi-dimensional data in row-major (C-style) or
+            column-major (Fortran-style) order in memory.
+        fill_value
+            If not None, fill the new buffer with a scalar value.
+
+        Returns
+        -------
+            New buffer representing a new ndarray_like object
+
+        Notes
+        -----
+        A subclass can overwrite this method to create an ndarray-like object
+        other then the default Numpy array.
+        """
+        if cls is NDBuffer:
+            raise NotImplementedError(
+                "Cannot call abstract method on the abstract class 'NDBuffer'"
+            )
+        return cls(
+            cast("NDArrayLike", None)
+        )  # This line will never be reached, but it satisfies the type checker
+
+    @classmethod
+    def empty(
+        cls, shape: tuple[int, ...], dtype: npt.DTypeLike, order: Literal["C", "F"] = "C"
+    ) -> Self:
+        """
+        Create an empty buffer with the given shape, dtype, and order.
+
+        This method can be faster than ``NDBuffer.create`` because it doesn't
+        have to initialize the memory used by the underlying ndarray-like
+        object.
+
+        Parameters
+        ----------
+        shape
+            The shape of the buffer and its underlying ndarray-like object
+        dtype
+            The datatype of the buffer and its underlying ndarray-like object
+        order
+            Whether to store multi-dimensional data in row-major (C-style) or
+            column-major (Fortran-style) order in memory.
+
+        Returns
+        -------
+        buffer
+            New buffer representing a new ndarray_like object with empty data.
+
+        See Also
+        --------
+        NDBuffer.create
+            Create a new buffer with some initial fill value.
+        """
+        # Implementations should override this method if they have a faster way
+        # to allocate an empty buffer.
+        return cls.create(shape=shape, dtype=dtype, order=order)
+
+    @classmethod
+    def from_ndarray_like(cls, ndarray_like: NDArrayLike) -> Self:
+        """Create a new buffer of an ndarray-like object
+
+        Parameters
+        ----------
+        ndarray_like
+            ndarray-like object
+
+        Returns
+        -------
+            New buffer representing `ndarray_like`
+        """
+        return cls(ndarray_like)
+
+    @classmethod
+    @abstractmethod
+    def from_numpy_array(cls, array_like: npt.ArrayLike) -> Self:
+        """Create a new buffer of Numpy array-like object
+
+        Parameters
+        ----------
+        array_like
+            Object that can be coerced into a Numpy array
+
+        Returns
+        -------
+            New buffer representing `array_like`
+        """
+        if cls is NDBuffer:
+            raise NotImplementedError(
+                "Cannot call abstract method on the abstract class 'NDBuffer'"
+            )
+        return cls(
+            cast("NDArrayLike", None)
+        )  # This line will never be reached, but it satisfies the type checker
+
+    def as_ndarray_like(self) -> NDArrayLike:
+        """Returns the underlying array (host or device memory) of this buffer
+
+        This will never copy data.
+
+        Returns
+        -------
+            The underlying array such as a NumPy or CuPy array.
+        """
+        return self._data
+
+    @abstractmethod
+    def as_numpy_array(self) -> npt.NDArray[Any]:
+        """Returns the buffer as a NumPy array (host memory).
+
+        Warnings
+        --------
+        Might have to copy data, consider using `.as_ndarray_like()` instead.
+
+        Returns
+        -------
+            NumPy array of this buffer (might be a data copy)
+        """
+        ...
+
+    def as_scalar(self) -> ScalarType:
+        """Returns the buffer as a scalar value"""
+        if self._data.size != 1:
+            raise ValueError("Buffer does not contain a single scalar value")
+        return cast("ScalarType", self.as_numpy_array()[()])
+
+    @property
+    def dtype(self) -> np.dtype[Any]:
+        return self._data.dtype
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        return self._data.shape
+
+    @property
+    def byteorder(self) -> Endian:
+        from zarr.codecs.bytes import Endian
+
+        if self.dtype.byteorder == "<":
+            return Endian.little
+        elif self.dtype.byteorder == ">":
+            return Endian.big
+        else:
+            return Endian(sys.byteorder)
+
+    def reshape(self, newshape: tuple[int, ...] | Literal[-1]) -> Self:
+        return self.__class__(self._data.reshape(newshape))
+
+    def squeeze(self, axis: tuple[int, ...]) -> Self:
+        newshape = tuple(a for i, a in enumerate(self.shape) if i not in axis)
+        return self.__class__(self._data.reshape(newshape))
+
+    def astype(self, dtype: npt.DTypeLike, order: Literal["K", "A", "C", "F"] = "K") -> Self:
+        return self.__class__(self._data.astype(dtype=dtype, order=order))
+
+    @abstractmethod
+    def __getitem__(self, key: Any) -> Self: ...
+
+    @abstractmethod
+    def __setitem__(self, key: Any, value: Any) -> None: ...
+
+    def __len__(self) -> int:
+        return self._data.__len__()
+
+    def __repr__(self) -> str:
+        return f"<NDBuffer shape={self.shape} dtype={self.dtype} {self._data!r}>"
+
+    def all_equal(self, other: Any, equal_nan: bool = True) -> bool:
+        """Compare to `other` using np.array_equal."""
+        if other is None:
+            # Handle None fill_value for Zarr V2
+            return False
+        # Handle positive and negative zero by comparing bit patterns:
+        if (
+            np.asarray(other).dtype.kind == "f"
+            and other == 0.0
+            and self._data.dtype.kind not in ("U", "S", "T", "O", "V")
+        ):
+            _data, other = np.broadcast_arrays(self._data, np.asarray(other, self._data.dtype))
+            void_dtype = "V" + str(_data.dtype.itemsize)
+            return np.array_equal(_data.view(void_dtype), other.view(void_dtype))
+        # use array_equal to obtain equal_nan=True functionality
+        # Since fill-value is a scalar, isn't there a faster path than allocating a new array for fill value
+        # every single time we have to write data?
+        _data, other = np.broadcast_arrays(self._data, other)
+        return np.array_equal(
+            _data,
+            other,
+            equal_nan=equal_nan
+            if self._data.dtype.kind not in ("U", "S", "T", "O", "V")
+            else False,
+        )
+
+    def fill(self, value: Any) -> None:
+        self._data.fill(value)
+
+    def copy(self) -> Self:
+        return self.__class__(self._data.copy())
+
+    def transpose(self, axes: SupportsIndex | Sequence[SupportsIndex] | None) -> Self:
+        return self.__class__(self._data.transpose(axes))
+
+
+class BufferPrototype(NamedTuple):
+    """Prototype of the Buffer and NDBuffer class
+
+    The protocol must be pickable.
+
+    Attributes
+    ----------
+    buffer
+        The Buffer class to use when Zarr needs to create new Buffer.
+    nd_buffer
+        The NDBuffer class to use when Zarr needs to create new NDBuffer.
+    """
+
+    buffer: type[Buffer]
+    nd_buffer: type[NDBuffer]
+
+
+# The default buffer prototype used throughout the Zarr codebase.
+def default_buffer_prototype() -> BufferPrototype:
+    from zarr.registry import (
+        get_buffer_class,
+        get_ndbuffer_class,
+    )
+
+    return BufferPrototype(buffer=get_buffer_class(), nd_buffer=get_ndbuffer_class())

.venv/lib/python3.11/site-packages/zarr/core/buffer/cpu.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+)
+
+import numpy as np
+import numpy.typing as npt
+
+from zarr.core.buffer import core
+from zarr.registry import (
+    register_buffer,
+    register_ndbuffer,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+    from typing import Self
+
+    from zarr.core.buffer.core import ArrayLike, NDArrayLike
+    from zarr.core.common import BytesLike
+
+
+class Buffer(core.Buffer):
+    """A flat contiguous memory block
+
+    We use Buffer throughout Zarr to represent a contiguous block of memory.
+
+    A Buffer is backed by an underlying array-like instance that represents
+    the memory. The memory type is unspecified; can be regular host memory,
+    CUDA device memory, or something else. The only requirement is that the
+    array-like instance can be copied/converted to a regular Numpy array
+    (host memory).
+
+    Notes
+    -----
+    This buffer is untyped, so all indexing and sizes are in bytes.
+
+    Parameters
+    ----------
+    array_like
+        array-like object that must be 1-dim, contiguous, and byte dtype.
+    """
+
+    def __init__(self, array_like: ArrayLike) -> None:
+        super().__init__(array_like)
+
+    @classmethod
+    def create_zero_length(cls) -> Self:
+        return cls(np.array([], dtype="B"))
+
+    @classmethod
+    def from_buffer(cls, buffer: core.Buffer) -> Self:
+        """Create a new buffer of an existing Buffer
+
+        This is useful if you want to ensure that an existing buffer is
+        of the correct subclass of Buffer. E.g., MemoryStore uses this
+        to return a buffer instance of the subclass specified by its
+        BufferPrototype argument.
+
+        Typically, this only copies data if the data has to be moved between
+        memory types, such as from host to device memory.
+
+        Parameters
+        ----------
+        buffer
+            buffer object.
+
+        Returns
+        -------
+            A new buffer representing the content of the input buffer
+
+        Notes
+        -----
+        Subclasses of `Buffer` must override this method to implement
+        more optimal conversions that avoid copies where possible
+        """
+        return cls.from_array_like(buffer.as_numpy_array())
+
+    @classmethod
+    def from_bytes(cls, bytes_like: BytesLike) -> Self:
+        """Create a new buffer of a bytes-like object (host memory)
+
+        Parameters
+        ----------
+        bytes_like
+            bytes-like object
+
+        Returns
+        -------
+            New buffer representing `bytes_like`
+        """
+        return cls.from_array_like(np.frombuffer(bytes_like, dtype="B"))
+
+    def as_numpy_array(self) -> npt.NDArray[Any]:
+        """Returns the buffer as a NumPy array (host memory).
+
+        Notes
+        -----
+        Might have to copy data, consider using `.as_array_like()` instead.
+
+        Returns
+        -------
+            NumPy array of this buffer (might be a data copy)
+        """
+        return np.asanyarray(self._data)
+
+    def combine(self, others: Iterable[core.Buffer]) -> Self:
+        data = [np.asanyarray(self._data)]
+        for buf in others:
+            other_array = buf.as_array_like()
+            assert other_array.dtype == np.dtype("B")
+            data.append(np.asanyarray(other_array))
+        return self.__class__(np.concatenate(data))
+
+
+class NDBuffer(core.NDBuffer):
+    """An n-dimensional memory block
+
+    We use NDBuffer throughout Zarr to represent a n-dimensional memory block.
+
+    An NDBuffer is backed by an underlying ndarray-like instance that represents
+    the memory. The memory type is unspecified; can be regular host memory,
+    CUDA device memory, or something else. The only requirement is that the
+    ndarray-like instance can be copied/converted to a regular Numpy array
+    (host memory).
+
+    Notes
+    -----
+    The two buffer classes Buffer and NDBuffer are very similar. In fact, Buffer
+    is a special case of NDBuffer where dim=1, stride=1, and dtype="B". However,
+    in order to use Python's type system to differentiate between the contiguous
+    Buffer and the n-dim (non-contiguous) NDBuffer, we keep the definition of the
+    two classes separate.
+
+    Parameters
+    ----------
+    array
+        ndarray-like object that is convertible to a regular Numpy array.
+    """
+
+    def __init__(self, array: NDArrayLike) -> None:
+        super().__init__(array)
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        shape: Iterable[int],
+        dtype: npt.DTypeLike,
+        order: Literal["C", "F"] = "C",
+        fill_value: Any | None = None,
+    ) -> Self:
+        # np.zeros is much faster than np.full, and therefore using it when possible is better.
+        if fill_value is None or (isinstance(fill_value, int) and fill_value == 0):
+            return cls(np.zeros(shape=tuple(shape), dtype=dtype, order=order))
+        else:
+            return cls(np.full(shape=tuple(shape), fill_value=fill_value, dtype=dtype, order=order))
+
+    @classmethod
+    def empty(
+        cls, shape: tuple[int, ...], dtype: npt.DTypeLike, order: Literal["C", "F"] = "C"
+    ) -> Self:
+        return cls(np.empty(shape=shape, dtype=dtype, order=order))
+
+    @classmethod
+    def from_numpy_array(cls, array_like: npt.ArrayLike) -> Self:
+        return cls.from_ndarray_like(np.asanyarray(array_like))
+
+    def as_numpy_array(self) -> npt.NDArray[Any]:
+        """Returns the buffer as a NumPy array (host memory).
+
+        Warnings
+        --------
+        Might have to copy data, consider using `.as_ndarray_like()` instead.
+
+        Returns
+        -------
+            NumPy array of this buffer (might be a data copy)
+        """
+        return np.asanyarray(self._data)
+
+    def __getitem__(self, key: Any) -> Self:
+        return self.__class__(np.asanyarray(self._data.__getitem__(key)))
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        if isinstance(value, NDBuffer):
+            value = value._data
+        self._data.__setitem__(key, value)
+
+
+def as_numpy_array_wrapper(
+    func: Callable[[npt.NDArray[Any]], bytes], buf: core.Buffer, prototype: core.BufferPrototype
+) -> core.Buffer:
+    """Converts the input of `func` to a numpy array and the output back to `Buffer`.
+
+    This function is useful when calling a `func` that only support host memory such
+    as `GZip.decode` and `Blosc.decode`. In this case, use this wrapper to convert
+    the input `buf` to a Numpy array and convert the result back into a `Buffer`.
+
+    Parameters
+    ----------
+    func
+        The callable that will be called with the converted `buf` as input.
+        `func` must return bytes, which will be converted into a `Buffer`
+        before returned.
+    buf
+        The buffer that will be converted to a Numpy array before given as
+        input to `func`.
+    prototype
+        The prototype of the output buffer.
+
+    Returns
+    -------
+        The result of `func` converted to a `Buffer`
+    """
+    return prototype.buffer.from_bytes(func(buf.as_numpy_array()))
+
+
+# CPU buffer prototype using numpy arrays
+buffer_prototype = core.BufferPrototype(buffer=Buffer, nd_buffer=NDBuffer)
+# default_buffer_prototype = buffer_prototype
+
+
+# The numpy prototype used for E.g. when reading the shard index
+def numpy_buffer_prototype() -> core.BufferPrototype:
+    return core.BufferPrototype(buffer=Buffer, nd_buffer=NDBuffer)
+
+
+register_buffer(Buffer, qualname="zarr.buffer.cpu.Buffer")
+register_ndbuffer(NDBuffer, qualname="zarr.buffer.cpu.NDBuffer")
+
+
+# backwards compatibility
+register_buffer(Buffer, qualname="zarr.core.buffer.cpu.Buffer")
+register_ndbuffer(NDBuffer, qualname="zarr.core.buffer.cpu.NDBuffer")

.venv/lib/python3.11/site-packages/zarr/core/buffer/gpu.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import warnings
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    cast,
+)
+
+import numpy as np
+import numpy.typing as npt
+
+from zarr.core.buffer import core
+from zarr.core.buffer.core import ArrayLike, BufferPrototype, NDArrayLike
+from zarr.errors import ZarrUserWarning
+from zarr.registry import (
+    register_buffer,
+    register_ndbuffer,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from typing import Self
+
+    from zarr.core.common import BytesLike
+
+try:
+    import cupy as cp
+except ImportError:
+    cp = None
+
+
+class Buffer(core.Buffer):
+    """A flat contiguous memory block on the GPU
+
+    We use Buffer throughout Zarr to represent a contiguous block of memory.
+
+    A Buffer is backed by an underlying array-like instance that represents
+    the memory. The memory type is unspecified; can be regular host memory,
+    CUDA device memory, or something else. The only requirement is that the
+    array-like instance can be copied/converted to a regular Numpy array
+    (host memory).
+
+    Notes
+    -----
+    This buffer is untyped, so all indexing and sizes are in bytes.
+
+    Parameters
+    ----------
+    array_like
+        array-like object that must be 1-dim, contiguous, and byte dtype.
+    """
+
+    def __init__(self, array_like: ArrayLike) -> None:
+        if cp is None:
+            raise ImportError(
+                "Cannot use zarr.buffer.gpu.Buffer without cupy. Please install cupy."
+            )
+
+        if array_like.ndim != 1:
+            raise ValueError("array_like: only 1-dim allowed")
+        if array_like.dtype != np.dtype("B"):
+            raise ValueError("array_like: only byte dtype allowed")
+
+        if not hasattr(array_like, "__cuda_array_interface__"):
+            # Slow copy based path for arrays that don't support the __cuda_array_interface__
+            # TODO: Add a fast zero-copy path for arrays that support the dlpack protocol
+            msg = (
+                "Creating a zarr.buffer.gpu.Buffer with an array that does not support the "
+                "__cuda_array_interface__ for zero-copy transfers, "
+                "falling back to slow copy based path"
+            )
+            warnings.warn(
+                msg,
+                category=ZarrUserWarning,
+                stacklevel=2,
+            )
+        self._data = cp.asarray(array_like)
+
+    @classmethod
+    def create_zero_length(cls) -> Self:
+        """Create an empty buffer with length zero
+
+        Returns
+        -------
+            New empty 0-length buffer
+        """
+        return cls(cp.array([], dtype="B"))
+
+    @classmethod
+    def from_buffer(cls, buffer: core.Buffer) -> Self:
+        """Create a GPU Buffer given an arbitrary Buffer
+        This will try to be zero-copy if `buffer` is already on the
+        GPU and will trigger a copy if not.
+
+        Returns
+        -------
+            New GPU Buffer constructed from `buffer`
+        """
+        return cls(buffer.as_array_like())
+
+    @classmethod
+    def from_bytes(cls, bytes_like: BytesLike) -> Self:
+        return cls.from_array_like(cp.frombuffer(bytes_like, dtype="B"))
+
+    def as_numpy_array(self) -> npt.NDArray[Any]:
+        return cast("npt.NDArray[Any]", cp.asnumpy(self._data))
+
+    def combine(self, others: Iterable[core.Buffer]) -> Self:
+        data = [cp.asanyarray(self._data)]
+        for other in others:
+            other_array = other.as_array_like()
+            assert other_array.dtype == np.dtype("B")
+            gpu_other = Buffer(other_array)
+            gpu_other_array = gpu_other.as_array_like()
+            data.append(cp.asanyarray(gpu_other_array))
+        return self.__class__(cp.concatenate(data))
+
+
+class NDBuffer(core.NDBuffer):
+    """A n-dimensional memory block on the GPU
+
+    We use NDBuffer throughout Zarr to represent a n-dimensional memory block.
+
+    An NDBuffer is backed by an underlying ndarray-like instance that represents
+    the memory. The memory type is unspecified; can be regular host memory,
+    CUDA device memory, or something else. The only requirement is that the
+    ndarray-like instance can be copied/converted to a regular Numpy array
+    (host memory).
+
+    Notes
+    -----
+    The two buffer classes Buffer and NDBuffer are very similar. In fact, Buffer
+    is a special case of NDBuffer where dim=1, stride=1, and dtype="B". However,
+    in order to use Python's type system to differentiate between the contiguous
+    Buffer and the n-dim (non-contiguous) NDBuffer, we keep the definition of the
+    two classes separate.
+
+    Parameters
+    ----------
+    array
+        ndarray-like object that is convertible to a regular Numpy array.
+    """
+
+    def __init__(self, array: NDArrayLike) -> None:
+        if cp is None:
+            raise ImportError(
+                "Cannot use zarr.buffer.gpu.NDBuffer without cupy. Please install cupy."
+            )
+
+        # assert array.ndim > 0
+        assert array.dtype != object
+        self._data = array
+
+        if not hasattr(array, "__cuda_array_interface__"):
+            # Slow copy based path for arrays that don't support the __cuda_array_interface__
+            # TODO: Add a fast zero-copy path for arrays that support the dlpack protocol
+            msg = (
+                "Creating a zarr.buffer.gpu.NDBuffer with an array that does not support the "
+                "__cuda_array_interface__ for zero-copy transfers, "
+                "falling back to slow copy based path"
+            )
+            warnings.warn(
+                msg,
+                stacklevel=2,
+            )
+        self._data = cp.asarray(array)
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        shape: Iterable[int],
+        dtype: npt.DTypeLike,
+        order: Literal["C", "F"] = "C",
+        fill_value: Any | None = None,
+    ) -> Self:
+        ret = cls(cp.empty(shape=tuple(shape), dtype=dtype, order=order))
+        if fill_value is not None:
+            ret.fill(fill_value)
+        return ret
+
+    @classmethod
+    def empty(
+        cls, shape: tuple[int, ...], dtype: npt.DTypeLike, order: Literal["C", "F"] = "C"
+    ) -> Self:
+        return cls(cp.empty(shape=shape, dtype=dtype, order=order))
+
+    @classmethod
+    def from_numpy_array(cls, array_like: npt.ArrayLike) -> Self:
+        """Create a new buffer of Numpy array-like object
+
+        Parameters
+        ----------
+        array_like
+            Object that can be coerced into a Numpy array
+
+        Returns
+        -------
+            New buffer representing `array_like`
+        """
+        return cls(cp.asarray(array_like))
+
+    def as_numpy_array(self) -> npt.NDArray[Any]:
+        """Returns the buffer as a NumPy array (host memory).
+
+        Warnings
+        --------
+        Might have to copy data, consider using `.as_ndarray_like()` instead.
+
+        Returns
+        -------
+            NumPy array of this buffer (might be a data copy)
+        """
+        return cast("npt.NDArray[Any]", cp.asnumpy(self._data))
+
+    def __getitem__(self, key: Any) -> Self:
+        return self.__class__(self._data.__getitem__(key))
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        if isinstance(value, NDBuffer):
+            value = value._data
+        elif isinstance(value, core.NDBuffer):
+            gpu_value = NDBuffer(value.as_ndarray_like())
+            value = gpu_value._data
+        self._data.__setitem__(key, value)
+
+
+buffer_prototype = BufferPrototype(buffer=Buffer, nd_buffer=NDBuffer)
+
+register_buffer(Buffer, qualname="zarr.buffer.gpu.Buffer")
+register_ndbuffer(NDBuffer, qualname="zarr.buffer.gpu.NDBuffer")
+
+# backwards compatibility
+register_buffer(Buffer, qualname="zarr.core.buffer.gpu.Buffer")
+register_ndbuffer(NDBuffer, qualname="zarr.core.buffer.gpu.NDBuffer")

.venv/lib/python3.11/site-packages/zarr/core/chunk_grids.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+import itertools
+import math
+import numbers
+import operator
+import warnings
+from abc import abstractmethod
+from dataclasses import dataclass
+from functools import reduce
+from typing import TYPE_CHECKING, Any, Literal
+
+import numpy as np
+
+import zarr
+from zarr.abc.metadata import Metadata
+from zarr.core.common import (
+    JSON,
+    NamedConfig,
+    ShapeLike,
+    ceildiv,
+    parse_named_configuration,
+    parse_shapelike,
+)
+from zarr.errors import ZarrUserWarning
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from typing import Self
+
+    from zarr.core.array import ShardsLike
+
+
+def _guess_chunks(
+    shape: tuple[int, ...] | int,
+    typesize: int,
+    *,
+    increment_bytes: int = 256 * 1024,
+    min_bytes: int = 128 * 1024,
+    max_bytes: int = 64 * 1024 * 1024,
+) -> tuple[int, ...]:
+    """
+    Iteratively guess an appropriate chunk layout for an array, given its shape and
+    the size of each element in bytes, and size constraints expressed in bytes. This logic is
+    adapted from h5py.
+
+    Parameters
+    ----------
+    shape : tuple[int, ...]
+        The chunk shape.
+    typesize : int
+        The size, in bytes, of each element of the chunk.
+    increment_bytes : int = 256 * 1024
+        The number of bytes used to increment or decrement the target chunk size in bytes.
+    min_bytes : int = 128 * 1024
+        The soft lower bound on the final chunk size in bytes.
+    max_bytes : int = 64 * 1024 * 1024
+        The hard upper bound on the final chunk size in bytes.
+
+    Returns
+    -------
+    tuple[int, ...]
+
+    """
+    if min_bytes >= max_bytes:
+        raise ValueError(f"Cannot have more min_bytes ({min_bytes}) than max_bytes ({max_bytes})")
+    if isinstance(shape, int):
+        shape = (shape,)
+
+    if typesize == 0:
+        return shape
+
+    ndims = len(shape)
+    # require chunks to have non-zero length for all dimensions
+    chunks = np.maximum(np.array(shape, dtype="=f8"), 1)
+
+    # Determine the optimal chunk size in bytes using a PyTables expression.
+    # This is kept as a float.
+    dset_size = np.prod(chunks) * typesize
+    target_size = increment_bytes * (2 ** np.log10(dset_size / (1024.0 * 1024)))
+
+    if target_size > max_bytes:
+        target_size = max_bytes
+    elif target_size < min_bytes:
+        target_size = min_bytes
+
+    idx = 0
+    while True:
+        # Repeatedly loop over the axes, dividing them by 2.  Stop when:
+        # 1a. We're smaller than the target chunk size, OR
+        # 1b. We're within 50% of the target chunk size, AND
+        # 2. The chunk is smaller than the maximum chunk size
+
+        chunk_bytes = np.prod(chunks) * typesize
+
+        if (
+            chunk_bytes < target_size or abs(chunk_bytes - target_size) / target_size < 0.5
+        ) and chunk_bytes < max_bytes:
+            break
+
+        if np.prod(chunks) == 1:
+            break  # Element size larger than max_bytes
+
+        chunks[idx % ndims] = math.ceil(chunks[idx % ndims] / 2.0)
+        idx += 1
+
+    return tuple(int(x) for x in chunks)
+
+
+def normalize_chunks(chunks: Any, shape: tuple[int, ...], typesize: int) -> tuple[int, ...]:
+    """Convenience function to normalize the `chunks` argument for an array
+    with the given `shape`."""
+
+    # N.B., expect shape already normalized
+
+    # handle auto-chunking
+    if chunks is None or chunks is True:
+        return _guess_chunks(shape, typesize)
+
+    # handle no chunking
+    if chunks is False:
+        return shape
+
+    # handle 1D convenience form
+    if isinstance(chunks, numbers.Integral):
+        chunks = tuple(int(chunks) for _ in shape)
+
+    # handle dask-style chunks (iterable of iterables)
+    if all(isinstance(c, (tuple, list)) for c in chunks):
+        for i, c in enumerate(chunks):
+            if any(x != y for x, y in itertools.pairwise(c[:-1])) or (len(c) > 1 and c[-1] > c[0]):
+                raise ValueError(
+                    f"Irregular chunk sizes in dimension {i}: {tuple(c)}. "
+                    "Only uniform chunks (with an optional smaller final chunk) are supported."
+                )
+        chunks = tuple(c[0] for c in chunks)
+
+    # handle bad dimensionality
+    if len(chunks) > len(shape):
+        raise ValueError("too many dimensions in chunks")
+
+    # handle underspecified chunks
+    if len(chunks) < len(shape):
+        # assume chunks across remaining dimensions
+        chunks += shape[len(chunks) :]
+
+    # handle None or -1 in chunks
+    if -1 in chunks or None in chunks:
+        chunks = tuple(
+            s if c == -1 or c is None else int(c) for s, c in zip(shape, chunks, strict=False)
+        )
+
+    if not all(isinstance(c, numbers.Integral) for c in chunks):
+        raise TypeError("non integer value in chunks")
+
+    return tuple(int(c) for c in chunks)
+
+
+@dataclass(frozen=True)
+class ChunkGrid(Metadata):
+    @classmethod
+    def from_dict(cls, data: dict[str, JSON] | ChunkGrid | NamedConfig[str, Any]) -> ChunkGrid:
+        if isinstance(data, ChunkGrid):
+            return data
+
+        name_parsed, _ = parse_named_configuration(data)
+        if name_parsed == "regular":
+            return RegularChunkGrid._from_dict(data)
+        raise ValueError(f"Unknown chunk grid. Got {name_parsed}.")
+
+    @abstractmethod
+    def all_chunk_coords(self, array_shape: tuple[int, ...]) -> Iterator[tuple[int, ...]]:
+        pass
+
+    @abstractmethod
+    def get_nchunks(self, array_shape: tuple[int, ...]) -> int:
+        pass
+
+
+@dataclass(frozen=True)
+class RegularChunkGrid(ChunkGrid):
+    chunk_shape: tuple[int, ...]
+
+    def __init__(self, *, chunk_shape: ShapeLike) -> None:
+        chunk_shape_parsed = parse_shapelike(chunk_shape)
+
+        object.__setattr__(self, "chunk_shape", chunk_shape_parsed)
+
+    @classmethod
+    def _from_dict(cls, data: dict[str, JSON] | NamedConfig[str, Any]) -> Self:
+        _, configuration_parsed = parse_named_configuration(data, "regular")
+
+        return cls(**configuration_parsed)  # type: ignore[arg-type]
+
+    def to_dict(self) -> dict[str, JSON]:
+        return {"name": "regular", "configuration": {"chunk_shape": tuple(self.chunk_shape)}}
+
+    def all_chunk_coords(self, array_shape: tuple[int, ...]) -> Iterator[tuple[int, ...]]:
+        return itertools.product(
+            *(range(ceildiv(s, c)) for s, c in zip(array_shape, self.chunk_shape, strict=False))
+        )
+
+    def get_nchunks(self, array_shape: tuple[int, ...]) -> int:
+        return reduce(
+            operator.mul,
+            itertools.starmap(ceildiv, zip(array_shape, self.chunk_shape, strict=True)),
+            1,
+        )
+
+
+def _guess_num_chunks_per_axis_shard(
+    chunk_shape: tuple[int, ...], item_size: int, max_bytes: int, array_shape: tuple[int, ...]
+) -> int:
+    """Generate the number of chunks per axis to hit a target max byte size for a shard.
+
+    For example, for a (2,2,2) chunk size and item size 4, maximum bytes of 256 would return 2.
+    In other words the shard would be a (2,2,2) grid of (2,2,2) chunks
+    i.e., prod(chunk_shape) * (returned_val * len(chunk_shape)) * item_size = 256 bytes.
+
+    Parameters
+    ----------
+    chunk_shape
+        The shape of the (inner) chunks.
+    item_size
+        The item size of the data i.e., 2 for uint16.
+    max_bytes
+        The maximum number of bytes per shard to allow.
+    array_shape
+        The shape of the underlying array.
+
+    Returns
+    -------
+        The number of chunks per axis.
+    """
+    bytes_per_chunk = np.prod(chunk_shape) * item_size
+    if max_bytes < bytes_per_chunk:
+        return 1
+    num_axes = len(chunk_shape)
+    chunks_per_shard = 1
+    # First check for byte size, second check to make sure we don't go bigger than the array shape
+    while (bytes_per_chunk * ((chunks_per_shard + 1) ** num_axes)) <= max_bytes and all(
+        c * (chunks_per_shard + 1) <= a for c, a in zip(chunk_shape, array_shape, strict=True)
+    ):
+        chunks_per_shard += 1
+    return chunks_per_shard
+
+
+def _auto_partition(
+    *,
+    array_shape: tuple[int, ...],
+    chunk_shape: tuple[int, ...] | Literal["auto"],
+    shard_shape: ShardsLike | None,
+    item_size: int,
+) -> tuple[tuple[int, ...] | None, tuple[int, ...]]:
+    """
+    Automatically determine the shard shape and chunk shape for an array, given the shape and dtype of the array.
+    If `shard_shape` is `None` and the chunk_shape is "auto", the chunks will be set heuristically based
+    on the dtype and shape of the array.
+    If `shard_shape` is "auto", then the shard shape will be set heuristically from the dtype and shape
+    of the array; if the `chunk_shape` is also "auto", then the chunks will be set heuristically as well,
+    given the dtype and shard shape. Otherwise, the chunks will be returned as-is.
+    """
+    if shard_shape is None:
+        _shards_out: None | tuple[int, ...] = None
+        if chunk_shape == "auto":
+            _chunks_out = _guess_chunks(array_shape, item_size)
+        else:
+            _chunks_out = chunk_shape
+    else:
+        if chunk_shape == "auto":
+            # aim for a 1MiB chunk
+            _chunks_out = _guess_chunks(array_shape, item_size, max_bytes=1048576)
+        else:
+            _chunks_out = chunk_shape
+
+        if shard_shape == "auto":
+            warnings.warn(
+                "Automatic shard shape inference is experimental and may change without notice.",
+                ZarrUserWarning,
+                stacklevel=2,
+            )
+            _shards_out = ()
+            target_shard_size_bytes = zarr.config.get("array.target_shard_size_bytes", None)
+            num_chunks_per_shard_axis = (
+                _guess_num_chunks_per_axis_shard(
+                    chunk_shape=_chunks_out,
+                    item_size=item_size,
+                    max_bytes=target_shard_size_bytes,
+                    array_shape=array_shape,
+                )
+                if (has_auto_shard := (target_shard_size_bytes is not None))
+                else 2
+            )
+            for a_shape, c_shape in zip(array_shape, _chunks_out, strict=True):
+                # The previous heuristic was `a_shape // c_shape > 8` and now, with target_shard_size_bytes, we only check that the shard size is less than the array size.
+                can_shard_axis = a_shape // c_shape > 8 if not has_auto_shard else True
+                if can_shard_axis:
+                    _shards_out += (c_shape * num_chunks_per_shard_axis,)
+                else:
+                    _shards_out += (c_shape,)
+        elif isinstance(shard_shape, dict):
+            _shards_out = tuple(shard_shape["shape"])
+        else:
+            _shards_out = shard_shape
+
+    return _shards_out, _chunks_out

.venv/lib/python3.11/site-packages/zarr/core/chunk_key_encodings.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeAlias, TypedDict, cast
+
+if TYPE_CHECKING:
+    from typing import NotRequired, Self
+
+from zarr.abc.metadata import Metadata
+from zarr.core.common import (
+    JSON,
+    NamedConfig,
+    parse_named_configuration,
+)
+from zarr.registry import get_chunk_key_encoding_class, register_chunk_key_encoding
+
+SeparatorLiteral = Literal[".", "/"]
+
+
+def parse_separator(data: JSON) -> SeparatorLiteral:
+    if data not in (".", "/"):
+        raise ValueError(f"Expected an '.' or '/' separator. Got {data} instead.")
+    return cast("SeparatorLiteral", data)
+
+
+class ChunkKeyEncodingParams(TypedDict):
+    name: Literal["v2", "default"]
+    separator: NotRequired[SeparatorLiteral]
+
+
+@dataclass(frozen=True)
+class ChunkKeyEncoding(ABC, Metadata):
+    """
+    Defines how chunk coordinates are mapped to store keys.
+
+    Subclasses must define a class variable `name` and implement `encode_chunk_key`.
+    """
+
+    name: ClassVar[str]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, JSON]) -> Self:
+        _, config_parsed = parse_named_configuration(data, require_configuration=False)
+        return cls(**config_parsed or {})
+
+    def to_dict(self) -> dict[str, JSON]:
+        return {"name": self.name, "configuration": super().to_dict()}
+
+    def decode_chunk_key(self, chunk_key: str) -> tuple[int, ...]:
+        """
+        Optional: decode a chunk key string into chunk coordinates.
+        Not required for normal operation; override if needed for testing or debugging.
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement decode_chunk_key.")
+
+    @abstractmethod
+    def encode_chunk_key(self, chunk_coords: tuple[int, ...]) -> str:
+        """
+        Encode chunk coordinates into a chunk key string.
+        Must be implemented by subclasses.
+        """
+
+
+ChunkKeyEncodingLike: TypeAlias = (
+    dict[str, JSON] | ChunkKeyEncodingParams | ChunkKeyEncoding | NamedConfig[str, Any]
+)
+
+
+@dataclass(frozen=True)
+class DefaultChunkKeyEncoding(ChunkKeyEncoding):
+    name: ClassVar[Literal["default"]] = "default"
+    separator: SeparatorLiteral = "/"
+
+    def __post_init__(self) -> None:
+        separator_parsed = parse_separator(self.separator)
+        object.__setattr__(self, "separator", separator_parsed)
+
+    def decode_chunk_key(self, chunk_key: str) -> tuple[int, ...]:
+        if chunk_key == "c":
+            return ()
+        return tuple(map(int, chunk_key[1:].split(self.separator)))
+
+    def encode_chunk_key(self, chunk_coords: tuple[int, ...]) -> str:
+        return self.separator.join(map(str, ("c",) + chunk_coords))
+
+
+@dataclass(frozen=True)
+class V2ChunkKeyEncoding(ChunkKeyEncoding):
+    name: ClassVar[Literal["v2"]] = "v2"
+    separator: SeparatorLiteral = "."
+
+    def __post_init__(self) -> None:
+        separator_parsed = parse_separator(self.separator)
+        object.__setattr__(self, "separator", separator_parsed)
+
+    def decode_chunk_key(self, chunk_key: str) -> tuple[int, ...]:
+        return tuple(map(int, chunk_key.split(self.separator)))
+
+    def encode_chunk_key(self, chunk_coords: tuple[int, ...]) -> str:
+        chunk_identifier = self.separator.join(map(str, chunk_coords))
+        return "0" if chunk_identifier == "" else chunk_identifier
+
+
+def parse_chunk_key_encoding(data: ChunkKeyEncodingLike) -> ChunkKeyEncoding:
+    """
+    Take an implicit specification of a chunk key encoding and parse it into a ChunkKeyEncoding object.
+    """
+    if isinstance(data, ChunkKeyEncoding):
+        return data
+
+    # handle ChunkKeyEncodingParams
+    if "name" in data and "separator" in data:
+        data = {"name": data["name"], "configuration": {"separator": data["separator"]}}  # type: ignore[typeddict-item]
+
+    # Now must be a named config
+    data = cast("dict[str, JSON]", data)
+
+    name_parsed, _ = parse_named_configuration(data, require_configuration=False)
+    try:
+        chunk_key_encoding = get_chunk_key_encoding_class(name_parsed).from_dict(data)
+    except KeyError as e:
+        raise ValueError(f"Unknown chunk key encoding: {e.args[0]!r}") from e
+
+    return chunk_key_encoding
+
+
+register_chunk_key_encoding("default", DefaultChunkKeyEncoding)
+register_chunk_key_encoding("v2", V2ChunkKeyEncoding)

.venv/lib/python3.11/site-packages/zarr/core/codec_pipeline.py

@@ -0,0 +1,562 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import islice, pairwise
+from typing import TYPE_CHECKING, Any, TypeVar
+from warnings import warn
+
+from zarr.abc.codec import (
+    ArrayArrayCodec,
+    ArrayBytesCodec,
+    ArrayBytesCodecPartialDecodeMixin,
+    ArrayBytesCodecPartialEncodeMixin,
+    BytesBytesCodec,
+    Codec,
+    CodecPipeline,
+)
+from zarr.core.common import concurrent_map
+from zarr.core.config import config
+from zarr.core.indexing import SelectorTuple, is_scalar
+from zarr.errors import ZarrUserWarning
+from zarr.registry import register_pipeline
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+    from typing import Self
+
+    from zarr.abc.store import ByteGetter, ByteSetter
+    from zarr.core.array_spec import ArraySpec
+    from zarr.core.buffer import Buffer, BufferPrototype, NDBuffer
+    from zarr.core.chunk_grids import ChunkGrid
+    from zarr.core.dtype.wrapper import TBaseDType, TBaseScalar, ZDType
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+def _unzip2(iterable: Iterable[tuple[T, U]]) -> tuple[list[T], list[U]]:
+    out0: list[T] = []
+    out1: list[U] = []
+    for item0, item1 in iterable:
+        out0.append(item0)
+        out1.append(item1)
+    return (out0, out1)
+
+
+def batched(iterable: Iterable[T], n: int) -> Iterable[tuple[T, ...]]:
+    if n < 1:
+        raise ValueError("n must be at least one")
+    it = iter(iterable)
+    while batch := tuple(islice(it, n)):
+        yield batch
+
+
+def resolve_batched(codec: Codec, chunk_specs: Iterable[ArraySpec]) -> Iterable[ArraySpec]:
+    return [codec.resolve_metadata(chunk_spec) for chunk_spec in chunk_specs]
+
+
+def fill_value_or_default(chunk_spec: ArraySpec) -> Any:
+    fill_value = chunk_spec.fill_value
+    if fill_value is None:
+        # Zarr V2 allowed `fill_value` to be null in the metadata.
+        # Zarr V3 requires it to be set. This has already been
+        # validated when decoding the metadata, but we support reading
+        # Zarr V2 data and need to support the case where fill_value
+        # is None.
+        return chunk_spec.dtype.default_scalar()
+    else:
+        return fill_value
+
+
+@dataclass(frozen=True)
+class BatchedCodecPipeline(CodecPipeline):
+    """Default codec pipeline.
+
+    This batched codec pipeline divides the chunk batches into batches of a configurable
+    batch size ("mini-batch"). Fetching, decoding, encoding and storing are performed in
+    lock step for each mini-batch. Multiple mini-batches are processing concurrently.
+    """
+
+    array_array_codecs: tuple[ArrayArrayCodec, ...]
+    array_bytes_codec: ArrayBytesCodec
+    bytes_bytes_codecs: tuple[BytesBytesCodec, ...]
+    batch_size: int
+
+    def evolve_from_array_spec(self, array_spec: ArraySpec) -> Self:
+        return type(self).from_codecs(c.evolve_from_array_spec(array_spec=array_spec) for c in self)
+
+    @classmethod
+    def from_codecs(cls, codecs: Iterable[Codec], *, batch_size: int | None = None) -> Self:
+        array_array_codecs, array_bytes_codec, bytes_bytes_codecs = codecs_from_list(codecs)
+
+        return cls(
+            array_array_codecs=array_array_codecs,
+            array_bytes_codec=array_bytes_codec,
+            bytes_bytes_codecs=bytes_bytes_codecs,
+            batch_size=batch_size or config.get("codec_pipeline.batch_size"),
+        )
+
+    @property
+    def supports_partial_decode(self) -> bool:
+        """Determines whether the codec pipeline supports partial decoding.
+
+        Currently, only codec pipelines with a single ArrayBytesCodec that supports
+        partial decoding can support partial decoding. This limitation is due to the fact
+        that ArrayArrayCodecs can change the slice selection leading to non-contiguous
+        slices and BytesBytesCodecs can change the chunk bytes in a way that slice
+        selections cannot be attributed to byte ranges anymore which renders partial
+        decoding infeasible.
+
+        This limitation may softened in the future."""
+        return (len(self.array_array_codecs) + len(self.bytes_bytes_codecs)) == 0 and isinstance(
+            self.array_bytes_codec, ArrayBytesCodecPartialDecodeMixin
+        )
+
+    @property
+    def supports_partial_encode(self) -> bool:
+        """Determines whether the codec pipeline supports partial encoding.
+
+        Currently, only codec pipelines with a single ArrayBytesCodec that supports
+        partial encoding can support partial encoding. This limitation is due to the fact
+        that ArrayArrayCodecs can change the slice selection leading to non-contiguous
+        slices and BytesBytesCodecs can change the chunk bytes in a way that slice
+        selections cannot be attributed to byte ranges anymore which renders partial
+        encoding infeasible.
+
+        This limitation may softened in the future."""
+        return (len(self.array_array_codecs) + len(self.bytes_bytes_codecs)) == 0 and isinstance(
+            self.array_bytes_codec, ArrayBytesCodecPartialEncodeMixin
+        )
+
+    def __iter__(self) -> Iterator[Codec]:
+        yield from self.array_array_codecs
+        yield self.array_bytes_codec
+        yield from self.bytes_bytes_codecs
+
+    def validate(
+        self,
+        *,
+        shape: tuple[int, ...],
+        dtype: ZDType[TBaseDType, TBaseScalar],
+        chunk_grid: ChunkGrid,
+    ) -> None:
+        for codec in self:
+            codec.validate(shape=shape, dtype=dtype, chunk_grid=chunk_grid)
+
+    def compute_encoded_size(self, byte_length: int, array_spec: ArraySpec) -> int:
+        for codec in self:
+            byte_length = codec.compute_encoded_size(byte_length, array_spec)
+            array_spec = codec.resolve_metadata(array_spec)
+        return byte_length
+
+    def _codecs_with_resolved_metadata_batched(
+        self, chunk_specs: Iterable[ArraySpec]
+    ) -> tuple[
+        list[tuple[ArrayArrayCodec, list[ArraySpec]]],
+        tuple[ArrayBytesCodec, list[ArraySpec]],
+        list[tuple[BytesBytesCodec, list[ArraySpec]]],
+    ]:
+        aa_codecs_with_spec: list[tuple[ArrayArrayCodec, list[ArraySpec]]] = []
+        chunk_specs = list(chunk_specs)
+        for aa_codec in self.array_array_codecs:
+            aa_codecs_with_spec.append((aa_codec, chunk_specs))
+            chunk_specs = [aa_codec.resolve_metadata(chunk_spec) for chunk_spec in chunk_specs]
+
+        ab_codec_with_spec = (self.array_bytes_codec, chunk_specs)
+        chunk_specs = [
+            self.array_bytes_codec.resolve_metadata(chunk_spec) for chunk_spec in chunk_specs
+        ]
+
+        bb_codecs_with_spec: list[tuple[BytesBytesCodec, list[ArraySpec]]] = []
+        for bb_codec in self.bytes_bytes_codecs:
+            bb_codecs_with_spec.append((bb_codec, chunk_specs))
+            chunk_specs = [bb_codec.resolve_metadata(chunk_spec) for chunk_spec in chunk_specs]
+
+        return (aa_codecs_with_spec, ab_codec_with_spec, bb_codecs_with_spec)
+
+    async def decode_batch(
+        self,
+        chunk_bytes_and_specs: Iterable[tuple[Buffer | None, ArraySpec]],
+    ) -> Iterable[NDBuffer | None]:
+        chunk_bytes_batch: Iterable[Buffer | None]
+        chunk_bytes_batch, chunk_specs = _unzip2(chunk_bytes_and_specs)
+        (
+            aa_codecs_with_spec,
+            ab_codec_with_spec,
+            bb_codecs_with_spec,
+        ) = self._codecs_with_resolved_metadata_batched(chunk_specs)
+
+        for bb_codec, chunk_spec_batch in bb_codecs_with_spec[::-1]:
+            chunk_bytes_batch = await bb_codec.decode(
+                zip(chunk_bytes_batch, chunk_spec_batch, strict=False)
+            )
+
+        ab_codec, chunk_spec_batch = ab_codec_with_spec
+        chunk_array_batch = await ab_codec.decode(
+            zip(chunk_bytes_batch, chunk_spec_batch, strict=False)
+        )
+
+        for aa_codec, chunk_spec_batch in aa_codecs_with_spec[::-1]:
+            chunk_array_batch = await aa_codec.decode(
+                zip(chunk_array_batch, chunk_spec_batch, strict=False)
+            )
+
+        return chunk_array_batch
+
+    async def decode_partial_batch(
+        self,
+        batch_info: Iterable[tuple[ByteGetter, SelectorTuple, ArraySpec]],
+    ) -> Iterable[NDBuffer | None]:
+        assert self.supports_partial_decode
+        assert isinstance(self.array_bytes_codec, ArrayBytesCodecPartialDecodeMixin)
+        return await self.array_bytes_codec.decode_partial(batch_info)
+
+    async def encode_batch(
+        self,
+        chunk_arrays_and_specs: Iterable[tuple[NDBuffer | None, ArraySpec]],
+    ) -> Iterable[Buffer | None]:
+        chunk_array_batch: Iterable[NDBuffer | None]
+        chunk_specs: Iterable[ArraySpec]
+        chunk_array_batch, chunk_specs = _unzip2(chunk_arrays_and_specs)
+
+        for aa_codec in self.array_array_codecs:
+            chunk_array_batch = await aa_codec.encode(
+                zip(chunk_array_batch, chunk_specs, strict=False)
+            )
+            chunk_specs = resolve_batched(aa_codec, chunk_specs)
+
+        chunk_bytes_batch = await self.array_bytes_codec.encode(
+            zip(chunk_array_batch, chunk_specs, strict=False)
+        )
+        chunk_specs = resolve_batched(self.array_bytes_codec, chunk_specs)
+
+        for bb_codec in self.bytes_bytes_codecs:
+            chunk_bytes_batch = await bb_codec.encode(
+                zip(chunk_bytes_batch, chunk_specs, strict=False)
+            )
+            chunk_specs = resolve_batched(bb_codec, chunk_specs)
+
+        return chunk_bytes_batch
+
+    async def encode_partial_batch(
+        self,
+        batch_info: Iterable[tuple[ByteSetter, NDBuffer, SelectorTuple, ArraySpec]],
+    ) -> None:
+        assert self.supports_partial_encode
+        assert isinstance(self.array_bytes_codec, ArrayBytesCodecPartialEncodeMixin)
+        await self.array_bytes_codec.encode_partial(batch_info)
+
+    async def read_batch(
+        self,
+        batch_info: Iterable[tuple[ByteGetter, ArraySpec, SelectorTuple, SelectorTuple, bool]],
+        out: NDBuffer,
+        drop_axes: tuple[int, ...] = (),
+    ) -> None:
+        if self.supports_partial_decode:
+            chunk_array_batch = await self.decode_partial_batch(
+                [
+                    (byte_getter, chunk_selection, chunk_spec)
+                    for byte_getter, chunk_spec, chunk_selection, *_ in batch_info
+                ]
+            )
+            for chunk_array, (_, chunk_spec, _, out_selection, _) in zip(
+                chunk_array_batch, batch_info, strict=False
+            ):
+                if chunk_array is not None:
+                    if drop_axes:
+                        chunk_array = chunk_array.squeeze(axis=drop_axes)
+                    out[out_selection] = chunk_array
+                else:
+                    out[out_selection] = fill_value_or_default(chunk_spec)
+        else:
+            chunk_bytes_batch = await concurrent_map(
+                [(byte_getter, array_spec.prototype) for byte_getter, array_spec, *_ in batch_info],
+                lambda byte_getter, prototype: byte_getter.get(prototype),
+                config.get("async.concurrency"),
+            )
+            chunk_array_batch = await self.decode_batch(
+                [
+                    (chunk_bytes, chunk_spec)
+                    for chunk_bytes, (_, chunk_spec, *_) in zip(
+                        chunk_bytes_batch, batch_info, strict=False
+                    )
+                ],
+            )
+            for chunk_array, (_, chunk_spec, chunk_selection, out_selection, _) in zip(
+                chunk_array_batch, batch_info, strict=False
+            ):
+                if chunk_array is not None:
+                    tmp = chunk_array[chunk_selection]
+                    if drop_axes:
+                        tmp = tmp.squeeze(axis=drop_axes)
+                    out[out_selection] = tmp
+                else:
+                    out[out_selection] = fill_value_or_default(chunk_spec)
+
+    def _merge_chunk_array(
+        self,
+        existing_chunk_array: NDBuffer | None,
+        value: NDBuffer,
+        out_selection: SelectorTuple,
+        chunk_spec: ArraySpec,
+        chunk_selection: SelectorTuple,
+        is_complete_chunk: bool,
+        drop_axes: tuple[int, ...],
+    ) -> NDBuffer:
+        if (
+            is_complete_chunk
+            and value.shape == chunk_spec.shape
+            # Guard that this is not a partial chunk at the end with is_complete_chunk=True
+            and value[out_selection].shape == chunk_spec.shape
+        ):
+            return value
+        if existing_chunk_array is None:
+            chunk_array = chunk_spec.prototype.nd_buffer.create(
+                shape=chunk_spec.shape,
+                dtype=chunk_spec.dtype.to_native_dtype(),
+                order=chunk_spec.order,
+                fill_value=fill_value_or_default(chunk_spec),
+            )
+        else:
+            chunk_array = existing_chunk_array.copy()  # make a writable copy
+        if chunk_selection == () or is_scalar(
+            value.as_ndarray_like(), chunk_spec.dtype.to_native_dtype()
+        ):
+            chunk_value = value
+        else:
+            chunk_value = value[out_selection]
+            # handle missing singleton dimensions
+            if drop_axes:
+                item = tuple(
+                    None  # equivalent to np.newaxis
+                    if idx in drop_axes
+                    else slice(None)
+                    for idx in range(chunk_spec.ndim)
+                )
+                chunk_value = chunk_value[item]
+        chunk_array[chunk_selection] = chunk_value
+        return chunk_array
+
+    async def write_batch(
+        self,
+        batch_info: Iterable[tuple[ByteSetter, ArraySpec, SelectorTuple, SelectorTuple, bool]],
+        value: NDBuffer,
+        drop_axes: tuple[int, ...] = (),
+    ) -> None:
+        if self.supports_partial_encode:
+            # Pass scalar values as is
+            if len(value.shape) == 0:
+                await self.encode_partial_batch(
+                    [
+                        (byte_setter, value, chunk_selection, chunk_spec)
+                        for byte_setter, chunk_spec, chunk_selection, out_selection, _ in batch_info
+                    ],
+                )
+            else:
+                await self.encode_partial_batch(
+                    [
+                        (byte_setter, value[out_selection], chunk_selection, chunk_spec)
+                        for byte_setter, chunk_spec, chunk_selection, out_selection, _ in batch_info
+                    ],
+                )
+
+        else:
+            # Read existing bytes if not total slice
+            async def _read_key(
+                byte_setter: ByteSetter | None, prototype: BufferPrototype
+            ) -> Buffer | None:
+                if byte_setter is None:
+                    return None
+                return await byte_setter.get(prototype=prototype)
+
+            chunk_bytes_batch: Iterable[Buffer | None]
+            chunk_bytes_batch = await concurrent_map(
+                [
+                    (
+                        None if is_complete_chunk else byte_setter,
+                        chunk_spec.prototype,
+                    )
+                    for byte_setter, chunk_spec, chunk_selection, _, is_complete_chunk in batch_info
+                ],
+                _read_key,
+                config.get("async.concurrency"),
+            )
+            chunk_array_decoded = await self.decode_batch(
+                [
+                    (chunk_bytes, chunk_spec)
+                    for chunk_bytes, (_, chunk_spec, *_) in zip(
+                        chunk_bytes_batch, batch_info, strict=False
+                    )
+                ],
+            )
+
+            chunk_array_merged = [
+                self._merge_chunk_array(
+                    chunk_array,
+                    value,
+                    out_selection,
+                    chunk_spec,
+                    chunk_selection,
+                    is_complete_chunk,
+                    drop_axes,
+                )
+                for chunk_array, (
+                    _,
+                    chunk_spec,
+                    chunk_selection,
+                    out_selection,
+                    is_complete_chunk,
+                ) in zip(chunk_array_decoded, batch_info, strict=False)
+            ]
+            chunk_array_batch: list[NDBuffer | None] = []
+            for chunk_array, (_, chunk_spec, *_) in zip(
+                chunk_array_merged, batch_info, strict=False
+            ):
+                if chunk_array is None:
+                    chunk_array_batch.append(None)  # type: ignore[unreachable]
+                else:
+                    if not chunk_spec.config.write_empty_chunks and chunk_array.all_equal(
+                        fill_value_or_default(chunk_spec)
+                    ):
+                        chunk_array_batch.append(None)
+                    else:
+                        chunk_array_batch.append(chunk_array)
+
+            chunk_bytes_batch = await self.encode_batch(
+                [
+                    (chunk_array, chunk_spec)
+                    for chunk_array, (_, chunk_spec, *_) in zip(
+                        chunk_array_batch, batch_info, strict=False
+                    )
+                ],
+            )
+
+            async def _write_key(byte_setter: ByteSetter, chunk_bytes: Buffer | None) -> None:
+                if chunk_bytes is None:
+                    await byte_setter.delete()
+                else:
+                    await byte_setter.set(chunk_bytes)
+
+            await concurrent_map(
+                [
+                    (byte_setter, chunk_bytes)
+                    for chunk_bytes, (byte_setter, *_) in zip(
+                        chunk_bytes_batch, batch_info, strict=False
+                    )
+                ],
+                _write_key,
+                config.get("async.concurrency"),
+            )
+
+    async def decode(
+        self,
+        chunk_bytes_and_specs: Iterable[tuple[Buffer | None, ArraySpec]],
+    ) -> Iterable[NDBuffer | None]:
+        output: list[NDBuffer | None] = []
+        for batch_info in batched(chunk_bytes_and_specs, self.batch_size):
+            output.extend(await self.decode_batch(batch_info))
+        return output
+
+    async def encode(
+        self,
+        chunk_arrays_and_specs: Iterable[tuple[NDBuffer | None, ArraySpec]],
+    ) -> Iterable[Buffer | None]:
+        output: list[Buffer | None] = []
+        for single_batch_info in batched(chunk_arrays_and_specs, self.batch_size):
+            output.extend(await self.encode_batch(single_batch_info))
+        return output
+
+    async def read(
+        self,
+        batch_info: Iterable[tuple[ByteGetter, ArraySpec, SelectorTuple, SelectorTuple, bool]],
+        out: NDBuffer,
+        drop_axes: tuple[int, ...] = (),
+    ) -> None:
+        await concurrent_map(
+            [
+                (single_batch_info, out, drop_axes)
+                for single_batch_info in batched(batch_info, self.batch_size)
+            ],
+            self.read_batch,
+            config.get("async.concurrency"),
+        )
+
+    async def write(
+        self,
+        batch_info: Iterable[tuple[ByteSetter, ArraySpec, SelectorTuple, SelectorTuple, bool]],
+        value: NDBuffer,
+        drop_axes: tuple[int, ...] = (),
+    ) -> None:
+        await concurrent_map(
+            [
+                (single_batch_info, value, drop_axes)
+                for single_batch_info in batched(batch_info, self.batch_size)
+            ],
+            self.write_batch,
+            config.get("async.concurrency"),
+        )
+
+
+def codecs_from_list(
+    codecs: Iterable[Codec],
+) -> tuple[tuple[ArrayArrayCodec, ...], ArrayBytesCodec, tuple[BytesBytesCodec, ...]]:
+    from zarr.codecs.sharding import ShardingCodec
+
+    array_array: tuple[ArrayArrayCodec, ...] = ()
+    array_bytes_maybe: ArrayBytesCodec | None = None
+    bytes_bytes: tuple[BytesBytesCodec, ...] = ()
+
+    if any(isinstance(codec, ShardingCodec) for codec in codecs) and len(tuple(codecs)) > 1:
+        warn(
+            "Combining a `sharding_indexed` codec disables partial reads and "
+            "writes, which may lead to inefficient performance.",
+            category=ZarrUserWarning,
+            stacklevel=3,
+        )
+
+    for prev_codec, cur_codec in pairwise((None, *codecs)):
+        if isinstance(cur_codec, ArrayArrayCodec):
+            if isinstance(prev_codec, ArrayBytesCodec | BytesBytesCodec):
+                msg = (
+                    f"Invalid codec order. ArrayArrayCodec {cur_codec}"
+                    "must be preceded by another ArrayArrayCodec. "
+                    f"Got {type(prev_codec)} instead."
+                )
+                raise TypeError(msg)
+            array_array += (cur_codec,)
+
+        elif isinstance(cur_codec, ArrayBytesCodec):
+            if isinstance(prev_codec, BytesBytesCodec):
+                msg = (
+                    f"Invalid codec order. ArrayBytes codec {cur_codec}"
+                    f" must be preceded by an ArrayArrayCodec. Got {type(prev_codec)} instead."
+                )
+                raise TypeError(msg)
+
+            if array_bytes_maybe is not None:
+                msg = (
+                    f"Got two instances of ArrayBytesCodec: {array_bytes_maybe} and {cur_codec}. "
+                    "Only one array-to-bytes codec is allowed."
+                )
+                raise ValueError(msg)
+
+            array_bytes_maybe = cur_codec
+
+        elif isinstance(cur_codec, BytesBytesCodec):
+            if isinstance(prev_codec, ArrayArrayCodec):
+                msg = (
+                    f"Invalid codec order. BytesBytesCodec {cur_codec}"
+                    "must be preceded by either another BytesBytesCodec, or an ArrayBytesCodec. "
+                    f"Got {type(prev_codec)} instead."
+                )
+            bytes_bytes += (cur_codec,)
+        else:
+            raise TypeError
+
+    if array_bytes_maybe is None:
+        raise ValueError("Required ArrayBytesCodec was not found.")
+    else:
+        return array_array, array_bytes_maybe, bytes_bytes
+
+
+register_pipeline(BatchedCodecPipeline)

.venv/lib/python3.11/site-packages/zarr/core/common.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import asyncio
+import functools
+import math
+import operator
+import warnings
+from collections.abc import Iterable, Mapping, Sequence
+from enum import Enum
+from itertools import starmap
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Final,
+    Generic,
+    Literal,
+    NotRequired,
+    TypedDict,
+    TypeVar,
+    cast,
+    overload,
+)
+
+import numpy as np
+from typing_extensions import ReadOnly
+
+from zarr.core.config import config as zarr_config
+from zarr.errors import ZarrRuntimeWarning
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Iterator
+
+
+ZARR_JSON = "zarr.json"
+ZARRAY_JSON = ".zarray"
+ZGROUP_JSON = ".zgroup"
+ZATTRS_JSON = ".zattrs"
+ZMETADATA_V2_JSON = ".zmetadata"
+
+BytesLike = bytes | bytearray | memoryview
+ShapeLike = Iterable[int | np.integer[Any]] | int | np.integer[Any]
+# For backwards compatibility
+ChunkCoords = tuple[int, ...]
+ZarrFormat = Literal[2, 3]
+NodeType = Literal["array", "group"]
+JSON = str | int | float | bool | Mapping[str, "JSON"] | Sequence["JSON"] | None
+MemoryOrder = Literal["C", "F"]
+AccessModeLiteral = Literal["r", "r+", "a", "w", "w-"]
+ANY_ACCESS_MODE: Final = "r", "r+", "a", "w", "w-"
+DimensionNames = Iterable[str | None] | None
+
+TName = TypeVar("TName", bound=str)
+TConfig = TypeVar("TConfig", bound=Mapping[str, object])
+
+
+class NamedConfig(TypedDict, Generic[TName, TConfig]):
+    """
+    A typed dictionary representing an object with a name and configuration, where the configuration
+    is an optional mapping of string keys to values, e.g. another typed dictionary or a JSON object.
+
+    This class is generic with two type parameters: the type of the name (``TName``) and the type of
+    the configuration (``TConfig``).
+    """
+
+    name: ReadOnly[TName]
+    """The name of the object."""
+
+    configuration: NotRequired[ReadOnly[TConfig]]
+    """The configuration of the object. Not required."""
+
+
+class NamedRequiredConfig(TypedDict, Generic[TName, TConfig]):
+    """
+    A typed dictionary representing an object with a name and configuration, where the configuration
+    is a mapping of string keys to values, e.g. another typed dictionary or a JSON object.
+
+    This class is generic with two type parameters: the type of the name (``TName``) and the type of
+    the configuration (``TConfig``).
+    """
+
+    name: ReadOnly[TName]
+    """The name of the object."""
+
+    configuration: ReadOnly[TConfig]
+    """The configuration of the object."""
+
+
+def product(tup: tuple[int, ...]) -> int:
+    return functools.reduce(operator.mul, tup, 1)
+
+
+def ceildiv(a: float, b: float) -> int:
+    if a == 0:
+        return 0
+    return math.ceil(a / b)
+
+
+T = TypeVar("T", bound=tuple[Any, ...])
+V = TypeVar("V")
+
+
+async def concurrent_map(
+    items: Iterable[T],
+    func: Callable[..., Awaitable[V]],
+    limit: int | None = None,
+) -> list[V]:
+    if limit is None:
+        return await asyncio.gather(*list(starmap(func, items)))
+
+    else:
+        sem = asyncio.Semaphore(limit)
+
+        async def run(item: tuple[Any]) -> V:
+            async with sem:
+                return await func(*item)
+
+        return await asyncio.gather(*[asyncio.ensure_future(run(item)) for item in items])
+
+
+E = TypeVar("E", bound=Enum)
+
+
+def enum_names(enum: type[E]) -> Iterator[str]:
+    for item in enum:
+        yield item.name
+
+
+def parse_enum(data: object, cls: type[E]) -> E:
+    if isinstance(data, cls):
+        return data
+    if not isinstance(data, str):
+        raise TypeError(f"Expected str, got {type(data)}")
+    if data in enum_names(cls):
+        return cls(data)
+    raise ValueError(f"Value must be one of {list(enum_names(cls))!r}. Got {data} instead.")
+
+
+def parse_name(data: JSON, expected: str | None = None) -> str:
+    if isinstance(data, str):
+        if expected is None or data == expected:
+            return data
+        raise ValueError(f"Expected '{expected}'. Got {data} instead.")
+    else:
+        raise TypeError(f"Expected a string, got an instance of {type(data)}.")
+
+
+def parse_configuration(data: JSON) -> JSON:
+    if not isinstance(data, dict):
+        raise TypeError(f"Expected dict, got {type(data)}")
+    return data
+
+
+@overload
+def parse_named_configuration(
+    data: JSON | NamedConfig[str, Any], expected_name: str | None = None
+) -> tuple[str, dict[str, JSON]]: ...
+
+
+@overload
+def parse_named_configuration(
+    data: JSON | NamedConfig[str, Any],
+    expected_name: str | None = None,
+    *,
+    require_configuration: bool = True,
+) -> tuple[str, dict[str, JSON] | None]: ...
+
+
+def parse_named_configuration(
+    data: JSON | NamedConfig[str, Any],
+    expected_name: str | None = None,
+    *,
+    require_configuration: bool = True,
+) -> tuple[str, JSON | None]:
+    if not isinstance(data, dict):
+        raise TypeError(f"Expected dict, got {type(data)}")
+    if "name" not in data:
+        raise ValueError(f"Named configuration does not have a 'name' key. Got {data}.")
+    name_parsed = parse_name(data["name"], expected_name)
+    if "configuration" in data:
+        configuration_parsed = parse_configuration(data["configuration"])
+    elif require_configuration:
+        raise ValueError(f"Named configuration does not have a 'configuration' key. Got {data}.")
+    else:
+        configuration_parsed = None
+    return name_parsed, configuration_parsed
+
+
+def parse_shapelike(data: ShapeLike) -> tuple[int, ...]:
+    """
+    Parse a shape-like input into an explicit shape.
+    """
+    if isinstance(data, int | np.integer):
+        if data < 0:
+            raise ValueError(f"Expected a non-negative integer. Got {data} instead")
+        return (int(data),)
+    try:
+        data_tuple = tuple(data)
+    except TypeError as e:
+        msg = f"Expected an integer or an iterable of integers. Got {data} instead."
+        raise TypeError(msg) from e
+
+    if not all(isinstance(v, int | np.integer) for v in data_tuple):
+        msg = f"Expected an iterable of integers. Got {data} instead."
+        raise TypeError(msg)
+    if not all(v > -1 for v in data_tuple):
+        msg = f"Expected all values to be non-negative. Got {data} instead."
+        raise ValueError(msg)
+
+    # cast NumPy scalars to plain python ints
+    return tuple(int(x) for x in data_tuple)
+
+
+def parse_fill_value(data: Any) -> Any:
+    # todo: real validation
+    return data
+
+
+def parse_order(data: Any) -> Literal["C", "F"]:
+    if data in ("C", "F"):
+        return cast("Literal['C', 'F']", data)
+    raise ValueError(f"Expected one of ('C', 'F'), got {data} instead.")
+
+
+def parse_bool(data: Any) -> bool:
+    if isinstance(data, bool):
+        return data
+    raise ValueError(f"Expected bool, got {data} instead.")
+
+
+def _warn_write_empty_chunks_kwarg() -> None:
+    # TODO: link to docs page on array configuration in this message
+    msg = (
+        "The `write_empty_chunks` keyword argument is deprecated and will be removed in future versions. "
+        "To control whether empty chunks are written to storage, either use the `config` keyword "
+        "argument, as in `config={'write_empty_chunks': True}`,"
+        "or change the global 'array.write_empty_chunks' configuration variable."
+    )
+    warnings.warn(msg, ZarrRuntimeWarning, stacklevel=2)
+
+
+def _warn_order_kwarg() -> None:
+    # TODO: link to docs page on array configuration in this message
+    msg = (
+        "The `order` keyword argument has no effect for Zarr format 3 arrays. "
+        "To control the memory layout of the array, either use the `config` keyword "
+        "argument, as in `config={'order': 'C'}`,"
+        "or change the global 'array.order' configuration variable."
+    )
+    warnings.warn(msg, ZarrRuntimeWarning, stacklevel=2)
+
+
+def _default_zarr_format() -> ZarrFormat:
+    """Return the default zarr_version"""
+    return cast("ZarrFormat", int(zarr_config.get("default_zarr_format", 3)))

.venv/lib/python3.11/site-packages/zarr/core/config.py

@@ -0,0 +1,153 @@
+"""
+The config module is responsible for managing the configuration of zarr and is based on the Donfig python library.
+For selecting custom implementations of codecs, pipelines, buffers and ndbuffers, first register the implementations
+in the registry and then select them in the config.
+
+Example:
+    An implementation of the bytes codec in a class ``your.module.NewBytesCodec`` requires the value of ``codecs.bytes``
+    to be ``your.module.NewBytesCodec``. Donfig can be configured programmatically, by environment variables, or from
+    YAML files in standard locations.
+
+    ```python
+    from your.module import NewBytesCodec
+    from zarr.core.config import register_codec, config
+
+    register_codec("bytes", NewBytesCodec)
+    config.set({"codecs.bytes": "your.module.NewBytesCodec"})
+    ```
+
+    Instead of setting the value programmatically with ``config.set``, you can also set the value with an environment
+    variable. The environment variable ``ZARR_CODECS__BYTES`` can be set to ``your.module.NewBytesCodec``. The double
+    underscore ``__`` is used to indicate nested access.
+
+    ```bash
+    export ZARR_CODECS__BYTES="your.module.NewBytesCodec"
+    ```
+
+For more information, see the Donfig documentation at https://github.com/pytroll/donfig.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from donfig import Config as DConfig
+
+if TYPE_CHECKING:
+    from donfig.config_obj import ConfigSet
+
+
+class BadConfigError(ValueError):
+    _msg = "bad Config: %r"
+
+
+class Config(DConfig):  # type: ignore[misc]
+    """The Config will collect configuration from config files and environment variables
+
+    Example environment variables:
+    Grabs environment variables of the form "ZARR_FOO__BAR_BAZ=123" and
+    turns these into config variables of the form ``{"foo": {"bar-baz": 123}}``
+    It transforms the key and value in the following way:
+
+    -  Lower-cases the key text
+    -  Treats ``__`` (double-underscore) as nested access
+    -  Calls ``ast.literal_eval`` on the value
+
+    """
+
+    def reset(self) -> None:
+        self.clear()
+        self.refresh()
+
+    def enable_gpu(self) -> ConfigSet:
+        """
+        Configure Zarr to use GPUs where possible.
+        """
+        return self.set(
+            {"buffer": "zarr.buffer.gpu.Buffer", "ndbuffer": "zarr.buffer.gpu.NDBuffer"}
+        )
+
+
+# these keys were removed from the config as part of the 3.1.0 release.
+# these deprecations should be removed in 3.1.1 or thereabouts.
+deprecations = {
+    "array.v2_default_compressor.numeric": None,
+    "array.v2_default_compressor.string": None,
+    "array.v2_default_compressor.bytes": None,
+    "array.v2_default_filters.string": None,
+    "array.v2_default_filters.bytes": None,
+    "array.v3_default_filters.numeric": None,
+    "array.v3_default_filters.raw": None,
+    "array.v3_default_filters.bytes": None,
+    "array.v3_default_serializer.numeric": None,
+    "array.v3_default_serializer.string": None,
+    "array.v3_default_serializer.bytes": None,
+    "array.v3_default_compressors.string": None,
+    "array.v3_default_compressors.bytes": None,
+    "array.v3_default_compressors": None,
+}
+
+# The default configuration for zarr
+config = Config(
+    "zarr",
+    defaults=[
+        {
+            "default_zarr_format": 3,
+            "array": {
+                "order": "C",
+                "write_empty_chunks": False,
+                "target_shard_size_bytes": None,
+            },
+            "async": {"concurrency": 10, "timeout": None},
+            "threading": {"max_workers": None},
+            "json_indent": 2,
+            "codec_pipeline": {
+                "path": "zarr.core.codec_pipeline.BatchedCodecPipeline",
+                "batch_size": 1,
+            },
+            "codecs": {
+                "blosc": "zarr.codecs.blosc.BloscCodec",
+                "gzip": "zarr.codecs.gzip.GzipCodec",
+                "zstd": "zarr.codecs.zstd.ZstdCodec",
+                "bytes": "zarr.codecs.bytes.BytesCodec",
+                "endian": "zarr.codecs.bytes.BytesCodec",  # compatibility with earlier versions of ZEP1
+                "crc32c": "zarr.codecs.crc32c_.Crc32cCodec",
+                "sharding_indexed": "zarr.codecs.sharding.ShardingCodec",
+                "transpose": "zarr.codecs.transpose.TransposeCodec",
+                "vlen-utf8": "zarr.codecs.vlen_utf8.VLenUTF8Codec",
+                "vlen-bytes": "zarr.codecs.vlen_utf8.VLenBytesCodec",
+                "numcodecs.bz2": "zarr.codecs.numcodecs.BZ2",
+                "numcodecs.crc32": "zarr.codecs.numcodecs.CRC32",
+                "numcodecs.crc32c": "zarr.codecs.numcodecs.CRC32C",
+                "numcodecs.lz4": "zarr.codecs.numcodecs.LZ4",
+                "numcodecs.lzma": "zarr.codecs.numcodecs.LZMA",
+                "numcodecs.zfpy": "zarr.codecs.numcodecs.ZFPY",
+                "numcodecs.adler32": "zarr.codecs.numcodecs.Adler32",
+                "numcodecs.astype": "zarr.codecs.numcodecs.AsType",
+                "numcodecs.bitround": "zarr.codecs.numcodecs.BitRound",
+                "numcodecs.blosc": "zarr.codecs.numcodecs.Blosc",
+                "numcodecs.delta": "zarr.codecs.numcodecs.Delta",
+                "numcodecs.fixedscaleoffset": "zarr.codecs.numcodecs.FixedScaleOffset",
+                "numcodecs.fletcher32": "zarr.codecs.numcodecs.Fletcher32",
+                "numcodecs.gzip": "zarr.codecs.numcodecs.GZip",
+                "numcodecs.jenkins_lookup3": "zarr.codecs.numcodecs.JenkinsLookup3",
+                "numcodecs.pcodec": "zarr.codecs.numcodecs.PCodec",
+                "numcodecs.packbits": "zarr.codecs.numcodecs.PackBits",
+                "numcodecs.shuffle": "zarr.codecs.numcodecs.Shuffle",
+                "numcodecs.quantize": "zarr.codecs.numcodecs.Quantize",
+                "numcodecs.zlib": "zarr.codecs.numcodecs.Zlib",
+                "numcodecs.zstd": "zarr.codecs.numcodecs.Zstd",
+            },
+            "buffer": "zarr.buffer.cpu.Buffer",
+            "ndbuffer": "zarr.buffer.cpu.NDBuffer",
+        }
+    ],
+    deprecations=deprecations,
+)
+
+
+def parse_indexing_order(data: Any) -> Literal["C", "F"]:
+    if data in ("C", "F"):
+        return cast("Literal['C', 'F']", data)
+    msg = f"Expected one of ('C', 'F'), got {data} instead."
+    raise ValueError(msg)

.venv/lib/python3.11/site-packages/zarr/core/dtype/__init__.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Final, TypeAlias
+
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    DTypeJSON,
+)
+from zarr.core.dtype.npy.bool import Bool
+from zarr.core.dtype.npy.bytes import (
+    NullTerminatedBytes,
+    NullterminatedBytesJSON_V2,
+    NullTerminatedBytesJSON_V3,
+    RawBytes,
+    RawBytesJSON_V2,
+    RawBytesJSON_V3,
+    VariableLengthBytes,
+    VariableLengthBytesJSON_V2,
+)
+from zarr.core.dtype.npy.complex import Complex64, Complex128
+from zarr.core.dtype.npy.float import Float16, Float32, Float64
+from zarr.core.dtype.npy.int import Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64
+from zarr.core.dtype.npy.structured import Structured, StructuredJSON_V2, StructuredJSON_V3
+from zarr.core.dtype.npy.time import (
+    DateTime64,
+    DateTime64JSON_V2,
+    DateTime64JSON_V3,
+    TimeDelta64,
+    TimeDelta64JSON_V2,
+    TimeDelta64JSON_V3,
+)
+
+if TYPE_CHECKING:
+    from zarr.core.common import ZarrFormat
+
+from collections.abc import Mapping
+
+import numpy as np
+import numpy.typing as npt
+
+from zarr.core.common import JSON
+from zarr.core.dtype.npy.string import (
+    FixedLengthUTF32,
+    FixedLengthUTF32JSON_V2,
+    FixedLengthUTF32JSON_V3,
+    VariableLengthUTF8,
+    VariableLengthUTF8JSON_V2,
+)
+from zarr.core.dtype.registry import DataTypeRegistry
+from zarr.core.dtype.wrapper import TBaseDType, TBaseScalar, ZDType
+
+__all__ = [
+    "Bool",
+    "Complex64",
+    "Complex128",
+    "DataTypeRegistry",
+    "DataTypeValidationError",
+    "DateTime64",
+    "DateTime64JSON_V2",
+    "DateTime64JSON_V3",
+    "FixedLengthUTF32",
+    "FixedLengthUTF32JSON_V2",
+    "FixedLengthUTF32JSON_V3",
+    "Float16",
+    "Float32",
+    "Float64",
+    "Int8",
+    "Int16",
+    "Int32",
+    "Int64",
+    "NullTerminatedBytes",
+    "NullTerminatedBytesJSON_V3",
+    "NullterminatedBytesJSON_V2",
+    "RawBytes",
+    "RawBytesJSON_V2",
+    "RawBytesJSON_V3",
+    "Structured",
+    "StructuredJSON_V2",
+    "StructuredJSON_V3",
+    "TBaseDType",
+    "TBaseScalar",
+    "TimeDelta64",
+    "TimeDelta64JSON_V2",
+    "TimeDelta64JSON_V3",
+    "UInt8",
+    "UInt16",
+    "UInt32",
+    "UInt64",
+    "VariableLengthBytes",
+    "VariableLengthBytesJSON_V2",
+    "VariableLengthUTF8",
+    "VariableLengthUTF8JSON_V2",
+    "ZDType",
+    "data_type_registry",
+    "parse_data_type",
+    "parse_dtype",
+]
+
+data_type_registry = DataTypeRegistry()
+
+IntegerDType = Int8 | Int16 | Int32 | Int64 | UInt8 | UInt16 | UInt32 | UInt64
+INTEGER_DTYPE: Final = Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64
+
+FloatDType = Float16 | Float32 | Float64
+FLOAT_DTYPE: Final = Float16, Float32, Float64
+
+ComplexFloatDType = Complex64 | Complex128
+COMPLEX_FLOAT_DTYPE: Final = Complex64, Complex128
+
+StringDType = FixedLengthUTF32 | VariableLengthUTF8
+STRING_DTYPE: Final = FixedLengthUTF32, VariableLengthUTF8
+
+TimeDType = DateTime64 | TimeDelta64
+TIME_DTYPE: Final = DateTime64, TimeDelta64
+
+BytesDType = RawBytes | NullTerminatedBytes | VariableLengthBytes
+BYTES_DTYPE: Final = RawBytes, NullTerminatedBytes, VariableLengthBytes
+
+AnyDType = (
+    Bool
+    | IntegerDType
+    | FloatDType
+    | ComplexFloatDType
+    | StringDType
+    | BytesDType
+    | Structured
+    | TimeDType
+    | VariableLengthBytes
+)
+# mypy has trouble inferring the type of variablelengthstring dtype, because its class definition
+# depends on the installed numpy version. That's why the type: ignore statement is needed here.
+ANY_DTYPE: Final = (
+    Bool,
+    *INTEGER_DTYPE,
+    *FLOAT_DTYPE,
+    *COMPLEX_FLOAT_DTYPE,
+    *STRING_DTYPE,
+    *BYTES_DTYPE,
+    Structured,
+    *TIME_DTYPE,
+    VariableLengthBytes,
+)
+
+# These are aliases for variable-length UTF-8 strings
+# We handle them when a user requests a data type instead of using NumPy's dtype inferece because
+# the default NumPy behavior -- to inspect the user-provided array data and choose
+# an appropriately sized U dtype -- is unworkable for Zarr.
+VLEN_UTF8_ALIAS: Final = ("str", str, "string")
+
+# This type models inputs that can be coerced to a ZDType
+ZDTypeLike: TypeAlias = npt.DTypeLike | ZDType[TBaseDType, TBaseScalar] | Mapping[str, JSON] | str
+
+for dtype in ANY_DTYPE:
+    # mypy does not know that all the elements of ANY_DTYPE are subclasses of ZDType
+    data_type_registry.register(dtype._zarr_v3_name, dtype)  # type: ignore[arg-type]
+
+
+# TODO: find a better name for this function
+def get_data_type_from_native_dtype(dtype: npt.DTypeLike) -> ZDType[TBaseDType, TBaseScalar]:
+    """
+    Get a data type wrapper (an instance of ``ZDType``) from a native data type, e.g. a numpy dtype.
+    """
+    if not isinstance(dtype, np.dtype):
+        na_dtype: np.dtype[np.generic]
+        if isinstance(dtype, list):
+            # this is a valid _VoidDTypeLike check
+            na_dtype = np.dtype([tuple(d) for d in dtype])
+        else:
+            na_dtype = np.dtype(dtype)
+    else:
+        na_dtype = dtype
+    return data_type_registry.match_dtype(dtype=na_dtype)
+
+
+def get_data_type_from_json(
+    dtype_spec: DTypeJSON, *, zarr_format: ZarrFormat
+) -> ZDType[TBaseDType, TBaseScalar]:
+    """
+    Given a JSON representation of a data type and a Zarr format version,
+    attempt to create a ZDType instance from the registered ZDType classes.
+    """
+    return data_type_registry.match_json(dtype_spec, zarr_format=zarr_format)
+
+
+def parse_data_type(
+    dtype_spec: ZDTypeLike,
+    *,
+    zarr_format: ZarrFormat,
+) -> ZDType[TBaseDType, TBaseScalar]:
+    """
+    Interpret the input as a ZDType.
+
+    This function wraps ``parse_dtype``. The only difference is the function name. This function may
+    be deprecated in a future version of Zarr Python in favor of ``parse_dtype``.
+
+    Parameters
+    ----------
+    dtype_spec : ZDTypeLike
+        The input to be interpreted as a ZDType. This could be a ZDType, which will be returned
+        directly, or a JSON representation of a ZDType, or a native dtype, or a python object that
+        can be converted into a native dtype.
+    zarr_format : ZarrFormat
+        The Zarr format version. This parameter is required because this function will attempt to
+        parse the JSON representation of a data type, and the JSON representation of data types
+        varies between Zarr 2 and Zarr 3.
+
+    Returns
+    -------
+    ZDType[TBaseDType, TBaseScalar]
+        The ZDType corresponding to the input.
+
+    Examples
+    --------
+    ```python
+    from zarr.dtype import parse_data_type
+    import numpy as np
+    parse_data_type("int32", zarr_format=2)
+    # Int32(endianness='little')
+    parse_data_type(np.dtype('S10'), zarr_format=2)
+    # NullTerminatedBytes(length=10)
+    parse_data_type({"name": "numpy.datetime64", "configuration": {"unit": "s", "scale_factor": 10}}, zarr_format=3)
+    # DateTime64(endianness='little', scale_factor=10, unit='s')
+    ```
+    """
+    return parse_dtype(dtype_spec, zarr_format=zarr_format)
+
+
+def parse_dtype(
+    dtype_spec: ZDTypeLike,
+    *,
+    zarr_format: ZarrFormat,
+) -> ZDType[TBaseDType, TBaseScalar]:
+    """
+    Convert the input as a ZDType.
+
+    Parameters
+    ----------
+    dtype_spec : ZDTypeLike
+        The input to be converted to a ZDType. This could be a ZDType, which will be returned
+        directly, or a JSON representation of a ZDType, or a numpy dtype, or a python object that
+        can be converted into a native dtype.
+    zarr_format : ZarrFormat
+        The Zarr format version. This parameter is required because this function will attempt to
+        parse the JSON representation of a data type, and the JSON representation of data types
+        varies between Zarr 2 and Zarr 3.
+
+    Returns
+    -------
+    ZDType[TBaseDType, TBaseScalar]
+        The ZDType corresponding to the input.
+
+    Examples
+    --------
+    ```python
+    from zarr.dtype import parse_dtype
+    import numpy as np
+    parse_dtype("int32", zarr_format=2)
+    # Int32(endianness='little')
+    parse_dtype(np.dtype('S10'), zarr_format=2)
+    # NullTerminatedBytes(length=10)
+    parse_dtype({"name": "numpy.datetime64", "configuration": {"unit": "s", "scale_factor": 10}}, zarr_format=3)
+    # DateTime64(endianness='little', scale_factor=10, unit='s')
+    ```
+    """
+    if isinstance(dtype_spec, ZDType):
+        return dtype_spec
+    # First attempt to interpret the input as JSON
+    if isinstance(dtype_spec, Mapping | str | Sequence):
+        try:
+            return get_data_type_from_json(dtype_spec, zarr_format=zarr_format)  # type: ignore[arg-type]
+        except ValueError:
+            # no data type matched this JSON-like input
+            pass
+    if dtype_spec in VLEN_UTF8_ALIAS:
+        # If the dtype request is one of the aliases for variable-length UTF-8 strings,
+        # return that dtype.
+        return VariableLengthUTF8()  # type: ignore[return-value]
+    # otherwise, we have either a numpy dtype string, or a zarr v3 dtype string, and in either case
+    # we can create a native dtype from it, and do the dtype inference from that
+    return get_data_type_from_native_dtype(dtype_spec)  # type: ignore[arg-type]

.venv/lib/python3.11/site-packages/zarr/core/dtype/common.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import (
+    ClassVar,
+    Final,
+    Generic,
+    Literal,
+    TypedDict,
+    TypeGuard,
+    TypeVar,
+)
+
+from typing_extensions import ReadOnly
+
+from zarr.core.common import NamedConfig
+from zarr.errors import UnstableSpecificationWarning
+
+EndiannessStr = Literal["little", "big"]
+ENDIANNESS_STR: Final = "little", "big"
+
+SpecialFloatStrings = Literal["NaN", "Infinity", "-Infinity"]
+SPECIAL_FLOAT_STRINGS: Final = ("NaN", "Infinity", "-Infinity")
+
+JSONFloatV2 = float | SpecialFloatStrings
+JSONFloatV3 = float | SpecialFloatStrings | str
+
+ObjectCodecID = Literal["vlen-utf8", "vlen-bytes", "vlen-array", "pickle", "json2", "msgpack2"]
+# These are the ids of the known object codecs for zarr v2.
+OBJECT_CODEC_IDS: Final = ("vlen-utf8", "vlen-bytes", "vlen-array", "pickle", "json2", "msgpack2")
+
+# This is a wider type than our standard JSON type because we need
+# to work with typeddict objects which are assignable to Mapping[str, object]
+DTypeJSON = str | int | float | Sequence["DTypeJSON"] | None | Mapping[str, object]
+
+# The DTypeJSON_V2 type exists because ZDType.from_json takes a single argument, which must contain
+# all the information necessary to decode the data type. Zarr v2 supports multiple distinct
+# data types that all used the "|O" data type identifier. These data types can only be
+# discriminated on the basis of their "object codec", i.e. a special data type specific
+# compressor or filter. So to figure out what data type a zarr v2 array has, we need the
+# data type identifier from metadata, as well as an object codec id if the data type identifier
+# is "|O".
+# So we will pack the name of the dtype alongside the name of the object codec id, if applicable,
+# in a single dict, and pass that to the data type inference logic.
+# These type variables have a very wide bound because the individual zdtype
+# classes can perform a very specific type check.
+
+# This is the JSON representation of a structured dtype in zarr v2
+StructuredName_V2 = Sequence["str | StructuredName_V2"]
+
+# This models the type of the name a dtype might have in zarr v2 array metadata
+DTypeName_V2 = StructuredName_V2 | str
+
+TDTypeNameV2_co = TypeVar("TDTypeNameV2_co", bound=DTypeName_V2, covariant=True)
+TObjectCodecID_co = TypeVar("TObjectCodecID_co", bound=None | str, covariant=True)
+
+
+class DTypeConfig_V2(TypedDict, Generic[TDTypeNameV2_co, TObjectCodecID_co]):
+    name: ReadOnly[TDTypeNameV2_co]
+    object_codec_id: ReadOnly[TObjectCodecID_co]
+
+
+DTypeSpec_V2 = DTypeConfig_V2[DTypeName_V2, None | str]
+
+
+def check_structured_dtype_v2_inner(data: object) -> TypeGuard[StructuredName_V2]:
+    """
+    A type guard for the inner elements of a structured dtype. This is a recursive check because
+    the type is itself recursive.
+
+    This check ensures that all the elements are 2-element sequences beginning with a string
+    and ending with either another string or another 2-element sequence beginning with a string and
+    ending with another instance of that type.
+    """
+    if isinstance(data, (str, Mapping)):
+        return False
+    if not isinstance(data, Sequence):
+        return False
+    if len(data) != 2:
+        return False
+    if not (isinstance(data[0], str)):
+        return False
+    if isinstance(data[-1], str):
+        return True
+    elif isinstance(data[-1], Sequence):
+        return check_structured_dtype_v2_inner(data[-1])
+    return False
+
+
+def check_structured_dtype_name_v2(data: Sequence[object]) -> TypeGuard[StructuredName_V2]:
+    """
+    Check that all the elements of a sequence are valid zarr v2 structured dtype identifiers
+    """
+    return all(check_structured_dtype_v2_inner(d) for d in data)
+
+
+def check_dtype_name_v2(data: object) -> TypeGuard[DTypeName_V2]:
+    """
+    Type guard for narrowing the type of a python object to a valid zarr v2 dtype name.
+    """
+    if isinstance(data, str):
+        return True
+    elif isinstance(data, Sequence):
+        return check_structured_dtype_name_v2(data)
+    return False
+
+
+def check_dtype_spec_v2(data: object) -> TypeGuard[DTypeSpec_V2]:
+    """
+    Type guard for narrowing a python object to an instance of DTypeSpec_V2
+    """
+    if not isinstance(data, Mapping):
+        return False
+    if set(data.keys()) != {"name", "object_codec_id"}:
+        return False
+    if not check_dtype_name_v2(data["name"]):
+        return False
+    return isinstance(data["object_codec_id"], str | None)
+
+
+# By comparison, The JSON representation of a dtype in zarr v3 is much simpler.
+# It's either a string, or a structured dict
+DTypeSpec_V3 = str | NamedConfig[str, Mapping[str, object]]
+
+
+def check_dtype_spec_v3(data: object) -> TypeGuard[DTypeSpec_V3]:
+    """
+    Type guard for narrowing the type of a python object to an instance of
+    DTypeSpec_V3, i.e either a string or a dict with a "name" field that's a string and a
+    "configuration" field that's a mapping with string keys.
+    """
+    if isinstance(data, str) or (  # noqa: SIM103
+        isinstance(data, Mapping)
+        and set(data.keys()) == {"name", "configuration"}
+        and isinstance(data["configuration"], Mapping)
+        and all(isinstance(k, str) for k in data["configuration"])
+    ):
+        return True
+    return False
+
+
+def unpack_dtype_json(data: DTypeSpec_V2 | DTypeSpec_V3) -> DTypeJSON:
+    """
+    Return the array metadata form of the dtype JSON representation. For the Zarr V3 form of dtype
+    metadata, this is a no-op. For the Zarr V2 form of dtype metadata, this unpacks the dtype name.
+    """
+    if isinstance(data, Mapping) and set(data.keys()) == {"name", "object_codec_id"}:
+        return data["name"]
+    return data
+
+
+class DataTypeValidationError(ValueError): ...
+
+
+class ScalarTypeValidationError(ValueError): ...
+
+
+@dataclass(frozen=True, kw_only=True)
+class HasLength:
+    """
+    A mix-in class for data types with a length attribute, such as fixed-size collections
+    of unicode strings, or bytes.
+
+    Attributes
+    ----------
+    length : int
+        The length of the scalars belonging to this data type. Note that this class does not assign
+        a unit to the length. Child classes may assign units.
+    """
+
+    length: int
+
+
+@dataclass(frozen=True, kw_only=True)
+class HasEndianness:
+    """
+    A mix-in class for data types with an endianness attribute
+    """
+
+    endianness: EndiannessStr = "little"
+
+
+@dataclass(frozen=True, kw_only=True)
+class HasItemSize:
+    """
+    A mix-in class for data types with an item size attribute.
+    This mix-in bears a property ``item_size``, which denotes the size of each element of the data
+    type, in bytes.
+    """
+
+    @property
+    def item_size(self) -> int:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True, kw_only=True)
+class HasObjectCodec:
+    """
+    A mix-in class for data types that require an object codec id.
+    This class bears the property ``object_codec_id``, which is the string name of an object
+    codec that is required to encode and decode the data type.
+
+    In zarr-python 2.x certain data types like variable-length strings or variable-length arrays
+    used the catch-all numpy "object" data type for their in-memory representation. But these data
+    types cannot be stored as numpy object data types, because the object data type does not define
+    a fixed memory layout. So these data types required a special codec, called an "object codec",
+    that effectively defined a compact representation for the data type, which was used to encode
+    and decode the data type.
+
+    Zarr-python 2.x would not allow the creation of arrays with the "object" data type if an object
+    codec was not specified, and thus the name of the object codec is effectively part of the data
+    type model.
+    """
+
+    object_codec_id: ClassVar[str]
+
+
+def v3_unstable_dtype_warning(dtype: object) -> None:
+    """
+    Emit this warning when a data type does not have a stable zarr v3 spec
+    """
+    msg = (
+        f"The data type ({dtype}) does not have a Zarr V3 specification. "
+        "That means that the representation of arrays saved with this data type may change without "
+        "warning in a future version of Zarr Python. "
+        "Arrays stored with this data type may be unreadable by other Zarr libraries. "
+        "Use this data type at your own risk! "
+        "Check https://github.com/zarr-developers/zarr-extensions/tree/main/data-types for the "
+        "status of data type specifications for Zarr V3."
+    )
+    warnings.warn(msg, category=UnstableSpecificationWarning, stacklevel=2)

.venv/lib/python3.11/site-packages/zarr/core/dtype/npy/bool.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar, Literal, Self, TypeGuard, overload
+
+import numpy as np
+
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    DTypeConfig_V2,
+    DTypeJSON,
+    HasItemSize,
+    check_dtype_spec_v2,
+)
+from zarr.core.dtype.wrapper import TBaseDType, ZDType
+
+if TYPE_CHECKING:
+    from zarr.core.common import JSON, ZarrFormat
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class Bool(ZDType[np.dtypes.BoolDType, np.bool_], HasItemSize):
+    """
+    A Zarr data type for arrays containing booleans.
+
+    Wraps the [`np.dtypes.BoolDType`][numpy.dtypes.BoolDType] data type. Scalars for this data type are instances of
+    [`np.bool_`][numpy.bool_].
+
+    Attributes
+    ----------
+
+    _zarr_v3_name : Literal["bool"] = "bool"
+        The Zarr v3 name of the dtype.
+    _zarr_v2_name : ``Literal["|b1"]`` = ``"|b1"``
+        The Zarr v2 name of the dtype, which is also a string representation
+        of the boolean dtype used by NumPy.
+    dtype_cls : ClassVar[type[np.dtypes.BoolDType]] = np.dtypes.BoolDType
+        The NumPy dtype class.
+
+    References
+    ----------
+    This class implements the boolean data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding)and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    _zarr_v3_name: ClassVar[Literal["bool"]] = "bool"
+    _zarr_v2_name: ClassVar[Literal["|b1"]] = "|b1"
+    dtype_cls = np.dtypes.BoolDType
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of Bool from an instance of np.dtypes.BoolDType.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The NumPy boolean dtype instance to convert.
+
+        Returns
+        -------
+        Bool
+            An instance of Bool.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the provided dtype is not compatible with this ZDType.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls()
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self: Self) -> np.dtypes.BoolDType:
+        """
+        Create a NumPy boolean dtype instance from this ZDType.
+
+        Returns
+        -------
+        np.dtypes.BoolDType
+            The NumPy boolean dtype.
+        """
+        return self.dtype_cls()
+
+    @classmethod
+    def _check_json_v2(
+        cls,
+        data: DTypeJSON,
+    ) -> TypeGuard[DTypeConfig_V2[Literal["|b1"], None]]:
+        """
+        Check that the input is a valid JSON representation of a Bool.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        ``TypeGuard[DTypeConfig_V2[Literal["|b1"], None]]``
+            True if the input is a valid JSON representation, False otherwise.
+        """
+        return (
+            check_dtype_spec_v2(data)
+            and data["name"] == cls._zarr_v2_name
+            and data["object_codec_id"] is None
+        )
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[Literal["bool"]]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        bool
+            True if the input is a valid JSON representation, False otherwise.
+        """
+        return data == cls._zarr_v3_name
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of Bool from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Bool
+            An instance of Bool.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v2(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v2_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls: type[Self], data: DTypeJSON) -> Self:
+        """
+        Create an instance of Bool from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Bool
+            An instance of Bool.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal["|b1"], None]: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["bool"]: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[Literal["|b1"], None] | Literal["bool"]:
+        """
+        Serialize this Bool instance to JSON.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version (2 or 3).
+
+        Returns
+        -------
+        ``DTypeConfig_V2[Literal["|b1"], None] | Literal["bool"]``
+            The JSON representation of the Bool instance.
+
+        Raises
+        ------
+        ValueError
+            If the zarr_format is not 2 or 3.
+        """
+        if zarr_format == 2:
+            return {"name": self._zarr_v2_name, "object_codec_id": None}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def _check_scalar(self, data: object) -> bool:
+        """
+        Check if the input can be cast to a boolean scalar.
+
+        Parameters
+        ----------
+        data : object
+            The data to check.
+
+        Returns
+        -------
+        bool
+            True if the input can be cast to a boolean scalar, False otherwise.
+        """
+        return True
+
+    def cast_scalar(self, data: object) -> np.bool_:
+        """
+        Cast the input to a numpy boolean scalar.
+
+        Parameters
+        ----------
+        data : object
+            The data to cast.
+
+        Returns
+        -------
+        bool : np.bool_
+            The numpy boolean scalar.
+
+        Raises
+        ------
+        TypeError
+            If the input cannot be converted to a numpy boolean.
+        """
+        if self._check_scalar(data):
+            return np.bool_(data)
+        msg = (  # pragma: no cover
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)  # pragma: no cover
+
+    def default_scalar(self) -> np.bool_:
+        """
+        Get the default value for the boolean dtype.
+
+        Returns
+        -------
+        bool : np.bool_
+            The default value.
+        """
+        return np.False_
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> bool:
+        """
+        Convert a scalar to a python bool.
+
+        Parameters
+        ----------
+        data : object
+            The value to convert.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        bool
+            The JSON-serializable format.
+        """
+        return bool(data)
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.bool_:
+        """
+        Read a JSON-serializable value as a numpy boolean scalar.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON-serializable value.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        bool : np.bool_
+            The numpy boolean scalar.
+
+        Raises
+        ------
+        TypeError
+            If the input is not a valid boolean type.
+        """
+        if self._check_scalar(data):
+            return np.bool_(data)
+        raise TypeError(f"Invalid type: {data}. Expected a boolean.")  # pragma: no cover
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 1

.venv/lib/python3.11/site-packages/zarr/core/dtype/npy/bytes.py

@@ -0,0 +1,1279 @@
+from __future__ import annotations
+
+import base64
+import re
+from dataclasses import dataclass
+from typing import ClassVar, Literal, Self, TypedDict, TypeGuard, cast, overload
+
+import numpy as np
+
+from zarr.core.common import JSON, NamedConfig, ZarrFormat
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    DTypeConfig_V2,
+    DTypeJSON,
+    HasItemSize,
+    HasLength,
+    HasObjectCodec,
+    check_dtype_spec_v2,
+    v3_unstable_dtype_warning,
+)
+from zarr.core.dtype.npy.common import check_json_str
+from zarr.core.dtype.wrapper import TBaseDType, ZDType
+
+BytesLike = np.bytes_ | str | bytes | int
+
+
+class FixedLengthBytesConfig(TypedDict):
+    """
+    A configuration for a data type that takes a ``length_bytes`` parameter.
+
+    Attributes
+    ----------
+
+    length_bytes : int
+        The length in bytes of the data associated with this configuration.
+
+    Examples
+    --------
+    ```python
+    {
+        "length_bytes": 12
+    }
+    ```
+    """
+
+    length_bytes: int
+
+
+class NullterminatedBytesJSON_V2(DTypeConfig_V2[str, None]):
+    """
+    A wrapper around the JSON representation of the ``NullTerminatedBytes`` data type in Zarr V2.
+
+    The ``name`` field of this class contains the value that would appear under the
+    ``dtype`` field in Zarr V2 array metadata.
+
+    References
+    ----------
+    The structure of the ``name`` field is defined in the Zarr V2
+    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "|S10",
+        "object_codec_id": None
+    }
+    ```
+    """
+
+
+class NullTerminatedBytesJSON_V3(
+    NamedConfig[Literal["null_terminated_bytes"], FixedLengthBytesConfig]
+):
+    """
+    The JSON representation of the ``NullTerminatedBytes`` data type in Zarr V3.
+
+    References
+    ----------
+    This representation is not currently defined in an external specification.
+
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "null_terminated_bytes",
+        "configuration": {
+            "length_bytes": 12
+        }
+    }
+    ```
+
+    """
+
+
+class RawBytesJSON_V2(DTypeConfig_V2[str, None]):
+    """
+    A wrapper around the JSON representation of the ``RawBytes`` data type in Zarr V2.
+
+    The ``name`` field of this class contains the value that would appear under the
+    ``dtype`` field in Zarr V2 array metadata.
+
+    References
+    ----------
+    The structure of the ``name`` field is defined in the Zarr V2
+    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+
+
+    Examples
+    --------
+    ```python
+
+        {
+            "name": "|V10",
+            "object_codec_id": None
+        }
+    ```
+    """
+
+
+class RawBytesJSON_V3(NamedConfig[Literal["raw_bytes"], FixedLengthBytesConfig]):
+    """
+    The JSON representation of the ``RawBytes`` data type in Zarr V3.
+
+    References
+    ----------
+    This representation is not currently defined in an external specification.
+
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "raw_bytes",
+        "configuration": {
+            "length_bytes": 12
+        }
+    }
+    ```
+    """
+
+
+class VariableLengthBytesJSON_V2(DTypeConfig_V2[Literal["|O"], Literal["vlen-bytes"]]):
+    """
+    A wrapper around the JSON representation of the ``VariableLengthBytes`` data type in Zarr V2.
+
+    The ``name`` field of this class contains the value that would appear under the
+    ``dtype`` field in Zarr V2 array metadata. The ``object_codec_id`` field is always ``"vlen-bytes"``
+
+    References
+    ----------
+    The structure of the ``name`` field is defined in the Zarr V2
+    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "|O",
+        "object_codec_id": "vlen-bytes"
+    }
+    ```
+    """
+
+
+@dataclass(frozen=True, kw_only=True)
+class NullTerminatedBytes(ZDType[np.dtypes.BytesDType[int], np.bytes_], HasLength, HasItemSize):
+    """
+    A Zarr data type for arrays containing fixed-length null-terminated byte sequences.
+
+    Wraps the [`np.dtypes.BytesDType`][numpy.dtypes.BytesDType] data type. Scalars for this data type are instances of
+    [`np.bytes_`][numpy.bytes_].
+
+    This data type is parametrized by an integral length which specifies size in bytes of each
+    scalar. Because this data type uses null-terminated semantics, indexing into
+    NumPy arrays with this data type may return fewer than ``length`` bytes.
+
+    Attributes
+    ----------
+    dtype_cls: ClassVar[type[np.dtypes.BytesDType[int]]] = np.dtypes.BytesDType
+        The NumPy data type wrapped by this ZDType.
+    _zarr_v3_name : ClassVar[Literal["null_terminated_bytes"]]
+    length : int
+        The length of the bytes.
+
+    Notes
+    -----
+    This data type is designed for compatibility with NumPy arrays that use the NumPy ``bytes`` data type.
+    It may not be desirable for usage outside of that context. If compatibility
+    with the NumPy ``bytes`` data type is not essential, consider using the ``RawBytes``
+    or ``VariableLengthBytes`` data types instead.
+    """
+
+    dtype_cls = np.dtypes.BytesDType
+    _zarr_v3_name: ClassVar[Literal["null_terminated_bytes"]] = "null_terminated_bytes"
+
+    def __post_init__(self) -> None:
+        """
+        We don't allow instances of this class with length less than 1 because there is no way such
+        a data type can contain actual data.
+        """
+        if self.length < 1:
+            raise ValueError(f"length must be >= 1, got {self.length}.")
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of NullTerminatedBytes from an instance of np.dtypes.BytesDType.
+
+        This method checks if the provided data type is an instance of np.dtypes.BytesDType.
+        If so, it returns a new instance of NullTerminatedBytes with a length equal to the
+        length of input data type.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The native dtype to convert.
+
+        Returns
+        -------
+        NullTerminatedBytes
+            An instance of NullTerminatedBytes with the specified length.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the dtype is not compatible with NullTerminatedBytes.
+        """
+
+        if cls._check_native_dtype(dtype):
+            return cls(length=dtype.itemsize)
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> np.dtypes.BytesDType[int]:
+        """
+        Create a NumPy bytes dtype from this NullTerminatedBytes ZDType.
+
+        Returns
+        -------
+        np.dtypes.BytesDType[int]
+            A NumPy data type object representing null-terminated bytes with a specified length.
+        """
+
+        return self.dtype_cls(self.length)
+
+    @classmethod
+    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[NullterminatedBytesJSON_V2]:
+        """
+        Check that the input is a valid JSON representation of NullTerminatedBytes in Zarr V2.
+
+        The input data must be a mapping that contains a "name" key that matches the pattern
+        "|S<number>" and an "object_codec_id" key that is None.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        bool
+            True if the input data is a valid representation, False otherwise.
+        """
+
+        return (
+            check_dtype_spec_v2(data)
+            and isinstance(data["name"], str)
+            and re.match(r"^\|S\d+$", data["name"]) is not None
+            and data["object_codec_id"] is None
+        )
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[NullTerminatedBytesJSON_V3]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[NullTerminatedBytesJSON_V3]
+            True if the input is a valid representation of this class in Zarr V3, False
+            otherwise.
+        """
+        return (
+            isinstance(data, dict)
+            and set(data.keys()) == {"name", "configuration"}
+            and data["name"] == cls._zarr_v3_name
+            and isinstance(data["configuration"], dict)
+            and "length_bytes" in data["configuration"]
+            and isinstance(data["configuration"]["length_bytes"], int)
+        )
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this class from Zarr V2-flavored JSON.
+
+        This method checks if the input data is a valid representation of
+        this class in Zarr V2. If so, it returns a new instance of
+        this class with a ``length`` as specified in the input data.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to parse.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data is not a valid representation of this class.
+        """
+
+        if cls._check_json_v2(data):
+            name = data["name"]
+            return cls(length=int(name[2:]))
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a string like '|S1', '|S2', etc"
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this class from Zarr V3-flavored JSON.
+
+        This method checks if the input data is a valid representation of
+        this class in Zarr V3. If so, it returns a new instance of
+        this class with a ``length`` as specified in the input data.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to parse.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data is not a valid representation of this class.
+        """
+        if cls._check_json_v3(data):
+            return cls(length=data["configuration"]["length_bytes"])
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> NullterminatedBytesJSON_V2: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> NullTerminatedBytesJSON_V3: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[str, None] | NullTerminatedBytesJSON_V3:
+        """
+        Generate a JSON representation of this data type.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        NullterminatedBytesJSON_V2 | NullTerminatedBytesJSON_V3
+            The JSON-serializable representation of the data type
+        """
+        if zarr_format == 2:
+            return {"name": self.to_native_dtype().str, "object_codec_id": None}
+        elif zarr_format == 3:
+            v3_unstable_dtype_warning(self)
+            return {
+                "name": self._zarr_v3_name,
+                "configuration": {"length_bytes": self.length},
+            }
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def _check_scalar(self, data: object) -> TypeGuard[BytesLike]:
+        """
+        Check if the provided data is of type BytesLike.
+
+        This method is used to verify if the input data can be considered as a
+        scalar of bytes-like type, which includes NumPy bytes, strings, bytes,
+        and integers.
+
+        Parameters
+        ----------
+        data : object
+            The data to check.
+
+        Returns
+        -------
+        TypeGuard[BytesLike]
+            True if the data is bytes-like, False otherwise.
+        """
+
+        return isinstance(data, BytesLike)
+
+    def _cast_scalar_unchecked(self, data: BytesLike) -> np.bytes_:
+        """
+        Cast the provided scalar data to [`np.bytes_`][numpy.bytes_], truncating if necessary.
+
+        Parameters
+        ----------
+        data : BytesLike
+            The data to cast.
+
+        Returns
+        -------
+        bytes : [`np.bytes_`][numpy.bytes_]
+            The casted data as a NumPy bytes scalar.
+
+        Notes
+        -----
+        This method does not perform any type checking.
+        The input data must be bytes-like.
+        """
+        if isinstance(data, int):
+            return self.to_native_dtype().type(str(data)[: self.length])
+        else:
+            return self.to_native_dtype().type(data[: self.length])
+
+    def cast_scalar(self, data: object) -> np.bytes_:
+        """
+        Attempt to cast a given object to a NumPy bytes scalar.
+
+        This method first checks if the provided data is a valid scalar that can be
+        converted to a NumPy bytes scalar. If the check succeeds, the unchecked casting
+        operation is performed. If the data is not valid, a TypeError is raised.
+
+        Parameters
+        ----------
+        data : object
+            The data to be cast to a NumPy bytes scalar.
+
+        Returns
+        -------
+        bytes : [`np.bytes_`][numpy.bytes_]
+            The data cast as a NumPy bytes scalar.
+
+        Raises
+        ------
+        TypeError
+            If the data cannot be converted to a NumPy bytes scalar.
+        """
+
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        msg = (
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)
+
+    def default_scalar(self) -> np.bytes_:
+        """
+        Return a default scalar value, which for this data type is an empty byte string.
+
+        Returns
+        -------
+        bytes : [`np.bytes_`][numpy.bytes_]
+            The default scalar value.
+        """
+        return np.bytes_(b"")
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
+        """
+        Convert a scalar to a JSON-serializable string representation.
+
+        This method encodes the given scalar as a NumPy bytes scalar and then
+        encodes the bytes as a base64-encoded string.
+
+        Parameters
+        ----------
+        data : object
+            The scalar to convert.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        str
+            A string representation of the scalar.
+        """
+        as_bytes = self.cast_scalar(data)
+        return base64.standard_b64encode(as_bytes).decode("ascii")
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.bytes_:
+        """
+        Read a JSON-serializable value as [`np.bytes_`][numpy.bytes_].
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON-serializable base64-encoded string.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        bytes : [`np.bytes_`][numpy.bytes_]
+            The NumPy bytes scalar obtained from decoding the base64 string.
+
+        Raises
+        ------
+        TypeError
+            If the input data is not a base64-encoded string.
+        """
+
+        if check_json_str(data):
+            return self.to_native_dtype().type(base64.standard_b64decode(data.encode("ascii")))
+        raise TypeError(
+            f"Invalid type: {data}. Expected a base64-encoded string."
+        )  # pragma: no cover
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return self.length
+
+
+@dataclass(frozen=True, kw_only=True)
+class RawBytes(ZDType[np.dtypes.VoidDType[int], np.void], HasLength, HasItemSize):
+    """
+    A Zarr data type for arrays containing fixed-length sequences of raw bytes.
+
+    Wraps the NumPy ``void`` data type. Scalars for this data type are instances of [`np.void`][numpy.void].
+
+    This data type is parametrized by an integral length which specifies size in bytes of each
+    scalar belonging to this data type.
+
+    Attributes
+    ----------
+    dtype_cls: ClassVar[type[np.dtypes.VoidDType[int]]] = np.dtypes.VoidDtype
+        The NumPy data type wrapped by this ZDType.
+    _zarr_v3_name : ClassVar[Literal["raw_bytes"]]
+    length : int
+        The length of the bytes.
+
+    Notes
+    -----
+    Although the NumPy "Void" data type is used to create "structured" data types in NumPy, this
+    class does not support structured data types.
+
+    See the ``Structured`` data type for this functionality.
+
+    """
+
+    # np.dtypes.VoidDType is specified in an odd way in NumPy
+    # it cannot be used to create instances of the dtype
+    # so we have to tell mypy to ignore this here
+    dtype_cls = np.dtypes.VoidDType  # type: ignore[assignment]
+    _zarr_v3_name: ClassVar[Literal["raw_bytes"]] = "raw_bytes"
+
+    def __post_init__(self) -> None:
+        """
+        We don't allow instances of this class with length less than 1 because there is no way such
+        a data type can contain actual data.
+        """
+        if self.length < 1:
+            raise ValueError(f"length must be >= 1, got {self.length}.")
+
+    @classmethod
+    def _check_native_dtype(
+        cls: type[Self], dtype: TBaseDType
+    ) -> TypeGuard[np.dtypes.VoidDType[int]]:
+        """
+        Check that the input is a NumPy void dtype with no fields.
+
+
+        Numpy void dtype comes in two forms:
+        * If the ``fields`` attribute is ``None``, then the dtype represents N raw bytes.
+        * If the ``fields`` attribute is not ``None``, then the dtype represents a structured dtype,
+
+        In this check we ensure that ``fields`` is ``None``.
+
+        Parameters
+        ----------
+        dtype : TDBaseDType
+            The dtype to check.
+
+        Returns
+        -------
+        Bool
+            True if the dtype is an instance of np.dtypes.VoidDType with no fields, False otherwise.
+        """
+        return cls.dtype_cls is type(dtype) and dtype.fields is None
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of RawBytes from an instance of np.dtypes.VoidDType.
+
+        This method checks if the provided data type is compatible with RawBytes. The input
+        must be an instance of np.dtypes.VoidDType, and have no fields. If the input is compatible,
+        this method returns an instance of RawBytes with the specified length.
+
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The native dtype to convert.
+
+        Returns
+        -------
+        RawBytes
+            An instance of RawBytes with the specified length.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the dtype is not compatible with RawBytes.
+        """
+
+        if cls._check_native_dtype(dtype):
+            return cls(length=dtype.itemsize)
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> np.dtypes.VoidDType[int]:
+        """
+        Create a NumPy void dtype from this RawBytes ZDType.
+
+        Returns
+        -------
+        np.dtypes.VoidDType[int]
+            A NumPy data type object representing raw bytes with a specified length.
+        """
+        # Numpy does not allow creating a void type
+        # by invoking np.dtypes.VoidDType directly
+        return cast("np.dtypes.VoidDType[int]", np.dtype(f"V{self.length}"))
+
+    @classmethod
+    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[RawBytesJSON_V2]:
+        """
+        Check that the input is a valid representation of this class in Zarr V2.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        True if the input is a valid representation of this class in Zarr V3, False otherwise.
+
+        """
+        return (
+            check_dtype_spec_v2(data)
+            and isinstance(data["name"], str)
+            and re.match(r"^\|V\d+$", data["name"]) is not None
+            and data["object_codec_id"] is None
+        )
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[RawBytesJSON_V3]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[RawBytesJSON_V3]
+            True if the input is a valid representation of this class in Zarr V3, False
+            otherwise.
+        """
+        return (
+            isinstance(data, dict)
+            and set(data.keys()) == {"name", "configuration"}
+            and data["name"] == cls._zarr_v3_name
+            and isinstance(data["configuration"], dict)
+            and set(data["configuration"].keys()) == {"length_bytes"}
+            and isinstance(data["configuration"]["length_bytes"], int)
+        )
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of RawBytes from Zarr V2-flavored JSON.
+
+        This method checks if the input data is a valid representation of
+        RawBytes in Zarr V2. If so, it returns a new instance of
+        RawBytes with a ``length`` as specified in the input data.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to parse.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data is not a valid representation of this class.
+        """
+        if cls._check_json_v2(data):
+            name = data["name"]
+            return cls(length=int(name[2:]))
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a string like '|V1', '|V2', etc"
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of RawBytes from Zarr V3-flavored JSON.
+
+        This method checks if the input data is a valid representation of
+        RawBytes in Zarr V3. If so, it returns a new instance of
+        RawBytes with a ``length`` as specified in the input data.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to parse.
+
+        Returns
+        -------
+        RawBytes
+            An instance of RawBytes.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data is not a valid representation of this class.
+        """
+        if cls._check_json_v3(data):
+            return cls(length=data["configuration"]["length_bytes"])
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> RawBytesJSON_V2: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> RawBytesJSON_V3: ...
+
+    def to_json(self, zarr_format: ZarrFormat) -> RawBytesJSON_V2 | RawBytesJSON_V3:
+        """
+        Generate a JSON representation of this data type.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        RawBytesJSON_V2 | RawBytesJSON_V3
+            The JSON-serializable representation of the data type.
+        """
+        if zarr_format == 2:
+            return {"name": self.to_native_dtype().str, "object_codec_id": None}
+        elif zarr_format == 3:
+            v3_unstable_dtype_warning(self)
+            return {"name": self._zarr_v3_name, "configuration": {"length_bytes": self.length}}
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def _check_scalar(self, data: object) -> TypeGuard[np.bytes_ | str | bytes | np.void]:
+        """
+        Check if the provided data can be cast to np.void.
+
+        This method is used to verify if the input data can be considered as a
+        scalar of bytes-like type, which includes np.bytes_, np.void, strings, and bytes objects.
+
+        Parameters
+        ----------
+        data : object
+            The data to check.
+
+        Returns
+        -------
+        TypeGuard[np.bytes_ | str | bytes | np.void]
+            True if the data is void-scalar-like, False otherwise.
+        """
+        return isinstance(data, np.bytes_ | str | bytes | np.void)
+
+    def _cast_scalar_unchecked(self, data: object) -> np.void:
+        """
+        Cast the provided scalar data to np.void.
+
+        Parameters
+        ----------
+        data : BytesLike
+            The data to cast.
+
+        Returns
+        -------
+        np.void
+            The casted data as a NumPy void scalar.
+
+        Notes
+        -----
+        This method does not perform any type checking.
+        The input data must be castable to np.void.
+        """
+        native_dtype = self.to_native_dtype()
+        # Without the second argument, NumPy will return a void scalar for dtype V1.
+        # The second argument ensures that, if native_dtype is something like V10,
+        # the result will actually be a V10 scalar.
+        return native_dtype.type(data, native_dtype)
+
+    def cast_scalar(self, data: object) -> np.void:
+        """
+        Attempt to cast a given object to a NumPy void scalar.
+
+        This method first checks if the provided data is a valid scalar that can be
+        converted to a NumPy void scalar. If the check succeeds, the unchecked casting
+        operation is performed. If the data is not valid, a TypeError is raised.
+
+        Parameters
+        ----------
+        data : object
+            The data to be cast to a NumPy void scalar.
+
+        Returns
+        -------
+        np.void
+            The data cast as a NumPy void scalar.
+
+        Raises
+        ------
+        TypeError
+            If the data cannot be converted to a NumPy void scalar.
+        """
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        msg = (
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)
+
+    def default_scalar(self) -> np.void:
+        """
+        Return the default scalar value for this data type.
+
+        The default scalar is a NumPy void scalar of the same length as the data type,
+        filled with zero bytes.
+
+        Returns
+        -------
+        np.void
+            The default scalar value.
+        """
+        return self.to_native_dtype().type(("\x00" * self.length).encode("ascii"))
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
+        """
+        Convert a scalar to a JSON-serializable string representation.
+
+        This method converts the given scalar to bytes and then
+        encodes the bytes as a base64-encoded string.
+
+        Parameters
+        ----------
+        data : object
+            The scalar to convert.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        str
+            A string representation of the scalar.
+        """
+        as_bytes = self.cast_scalar(data)
+        return base64.standard_b64encode(as_bytes.tobytes()).decode("ascii")
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.void:
+        """
+        Read a JSON-serializable value as an np.void.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON-serializable value.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        np.void
+            The NumPy void scalar.
+
+        Raises
+        ------
+        TypeError
+            If the data is not a string, or if the string is not a valid base64 encoding.
+        """
+        if check_json_str(data):
+            return self.to_native_dtype().type(base64.standard_b64decode(data))
+        raise TypeError(f"Invalid type: {data}. Expected a string.")  # pragma: no cover
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return self.length
+
+
+@dataclass(frozen=True, kw_only=True)
+class VariableLengthBytes(ZDType[np.dtypes.ObjectDType, bytes], HasObjectCodec):
+    """
+    A Zarr data type for arrays containing variable-length sequences of bytes.
+
+    Wraps the NumPy "object" data type. Scalars for this data type are instances of ``bytes``.
+
+    Attributes
+    ----------
+    dtype_cls: ClassVar[type[np.dtypes.ObjectDType]] = np.dtypes.ObjectDType
+        The NumPy data type wrapped by this ZDType.
+    _zarr_v3_name: ClassVar[Literal["variable_length_bytes"]] = "variable_length_bytes"
+        The name of this data type in Zarr V3.
+    object_codec_id: ClassVar[Literal["vlen-bytes"]] = "vlen-bytes"
+        The object codec ID for this data type.
+
+    Notes
+    -----
+    Because this data type uses the NumPy "object" data type, it does not guarantee a compact memory
+    representation of array data. Therefore a "vlen-bytes" codec is needed to ensure that the array
+    data can be persisted to storage.
+    """
+
+    dtype_cls = np.dtypes.ObjectDType
+    _zarr_v3_name: ClassVar[Literal["variable_length_bytes"]] = "variable_length_bytes"
+    object_codec_id: ClassVar[Literal["vlen-bytes"]] = "vlen-bytes"
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of VariableLengthBytes from an instance of np.dtypes.ObjectDType.
+
+        This method checks if the provided data type is an instance of np.dtypes.ObjectDType.
+        If so, it returns an instance of VariableLengthBytes.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The native dtype to convert.
+
+        Returns
+        -------
+        VariableLengthBytes
+            An instance of VariableLengthBytes.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the dtype is not compatible with VariableLengthBytes.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls()
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> np.dtypes.ObjectDType:
+        """
+        Create a NumPy object dtype from this VariableLengthBytes ZDType.
+
+        Returns
+        -------
+        np.dtypes.ObjectDType
+            A NumPy data type object representing variable-length bytes.
+        """
+        return self.dtype_cls()
+
+    @classmethod
+    def _check_json_v2(
+        cls,
+        data: DTypeJSON,
+    ) -> TypeGuard[VariableLengthBytesJSON_V2]:
+        """
+        Check that the input is a valid JSON representation of a NumPy O dtype, and that the
+        object codec id is appropriate for variable-length bytes strings.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        True if the input is a valid representation of this class in Zarr V2, False
+        otherwise.
+        """
+        # Check that the input is a valid JSON representation of a Zarr v2 data type spec.
+        if not check_dtype_spec_v2(data):
+            return False
+
+        # Check that the object codec id is appropriate for variable-length bytes strings.
+        if data["name"] != "|O":
+            return False
+        return data["object_codec_id"] == cls.object_codec_id
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[Literal["variable_length_bytes"]]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[Literal["variable_length_bytes"]]
+            True if the input is a valid representation of this class in Zarr V3, False otherwise.
+        """
+
+        return data in (cls._zarr_v3_name, "bytes")
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this VariableLengthBytes from Zarr V2-flavored JSON.
+
+        This method checks if the input data is a valid representation of this class
+        in Zarr V2. If so, it returns a new instance this class.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to parse.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data is not a valid representation of this class class.
+        """
+
+        if cls._check_json_v2(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string '|O' and an object_codec_id of {cls.object_codec_id}"
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of VariableLengthBytes from Zarr V3-flavored JSON.
+
+        This method checks if the input data is a valid representation of
+        VariableLengthBytes in Zarr V3. If so, it returns a new instance of
+        VariableLengthBytes.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to parse.
+
+        Returns
+        -------
+        VariableLengthBytes
+            An instance of VariableLengthBytes.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data is not a valid representation of this class.
+        """
+
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> VariableLengthBytesJSON_V2: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["variable_length_bytes"]: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> VariableLengthBytesJSON_V2 | Literal["variable_length_bytes"]:
+        """
+        Convert the variable-length bytes data type to a JSON-serializable form.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The zarr format version. Accepted values are 2 and 3.
+
+        Returns
+        -------
+        ``DTypeConfig_V2[Literal["|O"], Literal["vlen-bytes"]] | Literal["variable_length_bytes"]``
+            The JSON-serializable representation of the variable-length bytes data type.
+            For zarr_format 2, returns a dictionary with "name" and "object_codec_id".
+            For zarr_format 3, returns a string identifier "variable_length_bytes".
+
+        Raises
+        ------
+        ValueError
+            If zarr_format is not 2 or 3.
+        """
+
+        if zarr_format == 2:
+            return {"name": "|O", "object_codec_id": self.object_codec_id}
+        elif zarr_format == 3:
+            v3_unstable_dtype_warning(self)
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def default_scalar(self) -> bytes:
+        """
+        Return the default scalar value for the variable-length bytes data type.
+
+        Returns
+        -------
+        bytes
+            The default scalar value, which is an empty byte string.
+        """
+
+        return b""
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
+        """
+        Convert a scalar to a JSON-serializable string representation.
+
+        This method encodes the given scalar as bytes and then
+        encodes the bytes as a base64-encoded string.
+
+        Parameters
+        ----------
+        data : object
+            The scalar to convert.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        str
+            A string representation of the scalar.
+        """
+        return base64.standard_b64encode(data).decode("ascii")  # type: ignore[arg-type]
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> bytes:
+        """
+        Decode a base64-encoded JSON string to bytes.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON-serializable base64-encoded string.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        bytes
+            The decoded bytes from the base64 string.
+
+        Raises
+        ------
+        TypeError
+            If the input data is not a base64-encoded string.
+        """
+
+        if check_json_str(data):
+            return base64.standard_b64decode(data.encode("ascii"))
+        raise TypeError(f"Invalid type: {data}. Expected a string.")  # pragma: no cover
+
+    def _check_scalar(self, data: object) -> TypeGuard[BytesLike]:
+        """
+        Check if the provided data is of type BytesLike.
+
+        This method is used to verify if the input data can be considered as a
+        scalar of bytes-like type, which includes NumPy bytes, strings, bytes,
+        and integers.
+
+        Parameters
+        ----------
+        data : object
+            The data to check.
+
+        Returns
+        -------
+        TypeGuard[BytesLike]
+            True if the data is bytes-like, False otherwise.
+        """
+        return isinstance(data, BytesLike)
+
+    def _cast_scalar_unchecked(self, data: BytesLike) -> bytes:
+        """
+        Cast the provided scalar data to bytes.
+
+        Parameters
+        ----------
+        data : BytesLike
+            The data to cast.
+
+        Returns
+        -------
+        bytes
+            The casted data as bytes.
+
+        Notes
+        -----
+        This method does not perform any type checking.
+        The input data must be bytes-like.
+        """
+        if isinstance(data, str):
+            return bytes(data, encoding="utf-8")
+        return bytes(data)
+
+    def cast_scalar(self, data: object) -> bytes:
+        """
+        Attempt to cast a given object to a bytes scalar.
+
+        This method first checks if the provided data is a valid scalar that can be
+        converted to a bytes scalar. If the check succeeds, the unchecked casting
+        operation is performed. If the data is not valid, a TypeError is raised.
+
+        Parameters
+        ----------
+        data : object
+            The data to be cast to a bytes scalar.
+
+        Returns
+        -------
+        bytes
+            The data cast as a bytes scalar.
+
+        Raises
+        ------
+        TypeError
+            If the data cannot be converted to a bytes scalar.
+        """
+
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        msg = (
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)

.venv/lib/python3.11/site-packages/zarr/core/dtype/npy/common.py

@@ -0,0 +1,581 @@
+from __future__ import annotations
+
+import base64
+import struct
+import sys
+from collections.abc import Sequence
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Final,
+    Literal,
+    NewType,
+    SupportsComplex,
+    SupportsFloat,
+    SupportsIndex,
+    SupportsInt,
+    TypeGuard,
+    TypeVar,
+)
+
+import numpy as np
+
+from zarr.core.dtype.common import (
+    ENDIANNESS_STR,
+    SPECIAL_FLOAT_STRINGS,
+    EndiannessStr,
+    JSONFloatV2,
+    JSONFloatV3,
+)
+
+if TYPE_CHECKING:
+    from zarr.core.common import JSON, ZarrFormat
+
+IntLike = SupportsInt | SupportsIndex | bytes | str
+FloatLike = SupportsIndex | SupportsFloat | bytes | str
+ComplexLike = SupportsFloat | SupportsIndex | SupportsComplex | bytes | str | None
+DateTimeUnit = Literal[
+    "Y", "M", "W", "D", "h", "m", "s", "ms", "us", "μs", "ns", "ps", "fs", "as", "generic"
+]
+DATETIME_UNIT: Final = (
+    "Y",
+    "M",
+    "W",
+    "D",
+    "h",
+    "m",
+    "s",
+    "ms",
+    "us",
+    "μs",
+    "ns",
+    "ps",
+    "fs",
+    "as",
+    "generic",
+)
+
+IntishFloat = NewType("IntishFloat", float)
+"""A type for floats that represent integers, like 1.0 (but not 1.1)."""
+
+IntishStr = NewType("IntishStr", str)
+"""A type for strings that represent integers, like "0" or "42"."""
+
+FloatishStr = NewType("FloatishStr", str)
+"""A type for strings that represent floats, like "3.14" or "-2.5"."""
+
+NumpyEndiannessStr = Literal[">", "<", "="]
+NUMPY_ENDIANNESS_STR: Final = ">", "<", "="
+
+TFloatDType_co = TypeVar(
+    "TFloatDType_co",
+    bound=np.dtypes.Float16DType | np.dtypes.Float32DType | np.dtypes.Float64DType,
+    covariant=True,
+)
+TFloatScalar_co = TypeVar(
+    "TFloatScalar_co", bound=np.float16 | np.float32 | np.float64, covariant=True
+)
+
+TComplexDType_co = TypeVar(
+    "TComplexDType_co", bound=np.dtypes.Complex64DType | np.dtypes.Complex128DType, covariant=True
+)
+TComplexScalar_co = TypeVar("TComplexScalar_co", bound=np.complex64 | np.complex128, covariant=True)
+
+
+def endianness_from_numpy_str(endianness: NumpyEndiannessStr) -> EndiannessStr:
+    """
+    Convert a numpy endianness string literal to a human-readable literal value.
+
+    Parameters
+    ----------
+    endianness : Literal[">", "<", "="]
+        The numpy string representation of the endianness.
+
+    Returns
+    -------
+    Endianness
+        The human-readable representation of the endianness.
+
+    Raises
+    ------
+    ValueError
+        If the endianness is invalid.
+    """
+    match endianness:
+        case "=":
+            # Use the local system endianness
+            return sys.byteorder
+        case "<":
+            return "little"
+        case ">":
+            return "big"
+    raise ValueError(f"Invalid endianness: {endianness!r}. Expected one of {NUMPY_ENDIANNESS_STR}")
+
+
+def endianness_to_numpy_str(endianness: EndiannessStr) -> NumpyEndiannessStr:
+    """
+    Convert an endianness literal to its numpy string representation.
+
+    Parameters
+    ----------
+    endianness : Endianness
+        The endianness to convert.
+
+    Returns
+    -------
+    Literal[">", "<"]
+        The numpy string representation of the endianness.
+
+    Raises
+    ------
+    ValueError
+        If the endianness is invalid.
+    """
+    match endianness:
+        case "little":
+            return "<"
+        case "big":
+            return ">"
+    raise ValueError(
+        f"Invalid endianness: {endianness!r}. Expected one of {ENDIANNESS_STR} or None"
+    )
+
+
+def get_endianness_from_numpy_dtype(dtype: np.dtype[np.generic]) -> EndiannessStr:
+    """
+    Gets the endianness from a numpy dtype that has an endianness. This function will
+    raise a ValueError if the numpy data type does not have a concrete endianness.
+    """
+    endianness = dtype.byteorder
+    if dtype.byteorder in NUMPY_ENDIANNESS_STR:
+        return endianness_from_numpy_str(endianness)  # type: ignore [arg-type]
+    raise ValueError(f"The dtype {dtype} has an unsupported endianness: {endianness}")
+
+
+def float_from_json_v2(data: JSONFloatV2) -> float:
+    """
+    Convert a JSON float to a float (Zarr v2).
+
+    Parameters
+    ----------
+    data : JSONFloat
+        The JSON float to convert.
+
+    Returns
+    -------
+    float
+        The float value.
+    """
+    match data:
+        case "NaN":
+            return float("nan")
+        case "Infinity":
+            return float("inf")
+        case "-Infinity":
+            return float("-inf")
+        case _:
+            return float(data)
+
+
+def float_from_json_v3(data: JSONFloatV3) -> float:
+    """
+    Convert a JSON float to a float (v3).
+
+    Parameters
+    ----------
+    data : JSONFloat
+        The JSON float to convert.
+
+    Returns
+    -------
+    float
+        The float value.
+
+    Notes
+    -----
+    Zarr V3 allows floats to be stored as hex strings. To quote the spec:
+       "...for float32, "NaN" is equivalent to "0x7fc00000".
+       This representation is the only way to specify a NaN value other than the specific NaN value
+       denoted by "NaN"."
+    """
+
+    if isinstance(data, str):
+        if data in SPECIAL_FLOAT_STRINGS:
+            return float_from_json_v2(data)  # type: ignore[arg-type]
+        if not data.startswith("0x"):
+            msg = (
+                f"Invalid float value: {data!r}. Expected a string starting with the hex prefix"
+                " '0x', or one of 'NaN', 'Infinity', or '-Infinity'."
+            )
+            raise ValueError(msg)
+        if len(data[2:]) == 4:
+            dtype_code = ">e"
+        elif len(data[2:]) == 8:
+            dtype_code = ">f"
+        elif len(data[2:]) == 16:
+            dtype_code = ">d"
+        else:
+            msg = (
+                f"Invalid hexadecimal float value: {data!r}. "
+                "Expected the '0x' prefix to be followed by 4, 8, or 16 numeral characters"
+            )
+            raise ValueError(msg)
+        return float(struct.unpack(dtype_code, bytes.fromhex(data[2:]))[0])
+    return float_from_json_v2(data)
+
+
+def bytes_from_json(data: str, *, zarr_format: ZarrFormat) -> bytes:
+    """
+    Convert a JSON string to bytes
+
+    Parameters
+    ----------
+    data : str
+        The JSON string to convert.
+    zarr_format : ZarrFormat
+        The zarr format version.
+
+    Returns
+    -------
+    bytes
+        The bytes.
+    """
+    if zarr_format == 2:
+        return base64.b64decode(data.encode("ascii"))
+    # TODO: differentiate these as needed. This is a spec question.
+    if zarr_format == 3:
+        return base64.b64decode(data.encode("ascii"))
+    raise ValueError(f"Invalid zarr format: {zarr_format}. Expected 2 or 3.")  # pragma: no cover
+
+
+def bytes_to_json(data: bytes, zarr_format: ZarrFormat) -> str:
+    """
+    Convert bytes to JSON.
+
+    Parameters
+    ----------
+    data : bytes
+        The bytes to store.
+    zarr_format : ZarrFormat
+        The zarr format version.
+
+    Returns
+    -------
+    str
+        The bytes encoded as ascii using the base64 alphabet.
+    """
+    # TODO: decide if we are going to make this implementation zarr format-specific
+    return base64.b64encode(data).decode("ascii")
+
+
+def float_to_json_v2(data: float | np.floating[Any]) -> JSONFloatV2:
+    """
+    Convert a float to JSON (v2).
+
+    Parameters
+    ----------
+    data : float or np.floating
+        The float value to convert.
+
+    Returns
+    -------
+    JSONFloat
+        The JSON representation of the float.
+    """
+    if np.isnan(data):
+        return "NaN"
+    elif np.isinf(data):
+        return "Infinity" if data > 0 else "-Infinity"
+    return float(data)
+
+
+def float_to_json_v3(data: float | np.floating[Any]) -> JSONFloatV3:
+    """
+    Convert a float to JSON (v3).
+
+    Parameters
+    ----------
+    data : float or np.floating
+        The float value to convert.
+
+    Returns
+    -------
+    JSONFloat
+        The JSON representation of the float.
+    """
+    # v3 can in principle handle distinct NaN values, but numpy does not represent these explicitly
+    # so we just reuse the v2 routine here
+    return float_to_json_v2(data)
+
+
+def complex_float_to_json_v3(
+    data: complex | np.complexfloating[Any, Any],
+) -> tuple[JSONFloatV3, JSONFloatV3]:
+    """
+    Convert a complex number to JSON as defined by the Zarr V3 spec.
+
+    Parameters
+    ----------
+    data : complex or np.complexfloating
+        The complex value to convert.
+
+    Returns
+    -------
+    tuple[JSONFloat, JSONFloat]
+        The JSON representation of the complex number.
+    """
+    return float_to_json_v3(data.real), float_to_json_v3(data.imag)
+
+
+def complex_float_to_json_v2(
+    data: complex | np.complexfloating[Any, Any],
+) -> tuple[JSONFloatV2, JSONFloatV2]:
+    """
+    Convert a complex number to JSON as defined by the Zarr V2 spec.
+
+    Parameters
+    ----------
+    data : complex | np.complexfloating
+        The complex value to convert.
+
+    Returns
+    -------
+    tuple[JSONFloat, JSONFloat]
+        The JSON representation of the complex number.
+    """
+    return float_to_json_v2(data.real), float_to_json_v2(data.imag)
+
+
+def complex_float_from_json_v2(data: tuple[JSONFloatV2, JSONFloatV2]) -> complex:
+    """
+    Convert a JSON complex float to a complex number (v2).
+
+    Parameters
+    ----------
+    data : tuple[JSONFloat, JSONFloat]
+        The JSON complex float to convert.
+
+    Returns
+    -------
+    np.complexfloating
+        The complex number.
+    """
+    return complex(float_from_json_v2(data[0]), float_from_json_v2(data[1]))
+
+
+def complex_float_from_json_v3(data: tuple[JSONFloatV3, JSONFloatV3]) -> complex:
+    """
+    Convert a JSON complex float to a complex number (v3).
+
+    Parameters
+    ----------
+    data : tuple[JSONFloat, JSONFloat]
+        The JSON complex float to convert.
+
+    Returns
+    -------
+    np.complexfloating
+        The complex number.
+    """
+    return complex(float_from_json_v3(data[0]), float_from_json_v3(data[1]))
+
+
+def check_json_float_v2(data: JSON) -> TypeGuard[JSONFloatV2]:
+    """
+    Check if a JSON value represents a float (v2).
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    Bool
+        True if the data is a float, False otherwise.
+    """
+    return data in ("NaN", "Infinity", "-Infinity") or isinstance(data, float | int)
+
+
+def check_json_float_v3(data: JSON) -> TypeGuard[JSONFloatV3]:
+    """
+    Check if a JSON value represents a float (v3).
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    Bool
+        True if the data is a float, False otherwise.
+    """
+    return check_json_float_v2(data) or (isinstance(data, str) and data.startswith("0x"))
+
+
+def check_json_complex_float_v2(data: JSON) -> TypeGuard[tuple[JSONFloatV2, JSONFloatV2]]:
+    """
+    Check if a JSON value represents a complex float, as per the behavior of zarr-python 2.x
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    Bool
+        True if the data is a complex float, False otherwise.
+    """
+    return (
+        not isinstance(data, str)
+        and isinstance(data, Sequence)
+        and len(data) == 2
+        and check_json_float_v2(data[0])
+        and check_json_float_v2(data[1])
+    )
+
+
+def check_json_complex_float_v3(data: JSON) -> TypeGuard[tuple[JSONFloatV3, JSONFloatV3]]:
+    """
+    Check if a JSON value represents a complex float, as per the zarr v3 spec
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    Bool
+        True if the data is a complex float, False otherwise.
+    """
+    return (
+        not isinstance(data, str)
+        and isinstance(data, Sequence)
+        and len(data) == 2
+        and check_json_float_v3(data[0])
+        and check_json_float_v3(data[1])
+    )
+
+
+def check_json_int(data: JSON) -> TypeGuard[int]:
+    """
+    Check if a JSON value is an integer.
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    Bool
+        True if the data is an integer, False otherwise.
+    """
+    return bool(isinstance(data, int))
+
+
+def check_json_intish_float(data: JSON) -> TypeGuard[IntishFloat]:
+    """
+    Check if a JSON value is an "intish float", i.e. a float that represents an integer, like 0.0.
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    Bool
+        True if the data is an intish float, False otherwise.
+    """
+    return isinstance(data, float) and data.is_integer()
+
+
+def check_json_intish_str(data: JSON) -> TypeGuard[IntishStr]:
+    """
+    Check if a JSON value is a string that represents an integer, like "0", "42", or "-5".
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    bool
+        True if the data is a string representing an integer, False otherwise.
+    """
+    if not isinstance(data, str):
+        return False
+
+    try:
+        int(data)
+    except ValueError:
+        return False
+    else:
+        return True
+
+
+def check_json_floatish_str(data: JSON) -> TypeGuard[FloatishStr]:
+    """
+    Check if a JSON value is a string that represents a float, like "3.14", "-2.5", or "0.0".
+
+    Note: This function is intended to be used AFTER check_json_float_v2/v3, so it only
+    handles regular string representations that those functions don't cover.
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    bool
+        True if the data is a string representing a regular float, False otherwise.
+    """
+    if not isinstance(data, str):
+        return False
+
+    try:
+        float(data)
+    except ValueError:
+        return False
+    else:
+        return True
+
+
+def check_json_str(data: JSON) -> TypeGuard[str]:
+    """
+    Check if a JSON value is a string.
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    Bool
+        True if the data is a string, False otherwise.
+    """
+    return bool(isinstance(data, str))
+
+
+def check_json_bool(data: JSON) -> TypeGuard[bool]:
+    """
+    Check if a JSON value is a boolean.
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    Bool
+        True if the data is a boolean, False otherwise.
+    """
+    return isinstance(data, bool)

.venv/lib/python3.11/site-packages/zarr/core/dtype/npy/complex.py

@@ -0,0 +1,418 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Literal,
+    Self,
+    TypeGuard,
+    overload,
+)
+
+import numpy as np
+
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    DTypeConfig_V2,
+    DTypeJSON,
+    HasEndianness,
+    HasItemSize,
+    check_dtype_spec_v2,
+)
+from zarr.core.dtype.npy.common import (
+    ComplexLike,
+    TComplexDType_co,
+    TComplexScalar_co,
+    check_json_complex_float_v2,
+    check_json_complex_float_v3,
+    complex_float_from_json_v2,
+    complex_float_from_json_v3,
+    complex_float_to_json_v2,
+    complex_float_to_json_v3,
+    endianness_to_numpy_str,
+    get_endianness_from_numpy_dtype,
+)
+from zarr.core.dtype.wrapper import TBaseDType, ZDType
+
+if TYPE_CHECKING:
+    from zarr.core.common import JSON, ZarrFormat
+
+
+@dataclass(frozen=True)
+class BaseComplex(ZDType[TComplexDType_co, TComplexScalar_co], HasEndianness, HasItemSize):
+    """
+    A base class for Zarr data types that wrap NumPy complex float data types.
+    """
+
+    # This attribute holds the possible zarr v2 JSON names for the data type
+    _zarr_v2_names: ClassVar[tuple[str, ...]]
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of this data type from a NumPy complex dtype.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The native dtype to convert.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the dtype is not compatible with this data type.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> TComplexDType_co:
+        """
+        Convert this class to a NumPy complex dtype with the appropriate byte order.
+
+        Returns
+        -------
+        TComplexDType_co
+            A NumPy data type object representing the complex data type with the specified byte order.
+        """
+
+        byte_order = endianness_to_numpy_str(self.endianness)
+        return self.dtype_cls().newbyteorder(byte_order)  # type: ignore[return-value]
+
+    @classmethod
+    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[DTypeConfig_V2[str, None]]:
+        """
+        Check that the input is a valid JSON representation of this data type.
+
+        The input data must be a mapping that contains a "name" key that is one of
+        the strings from cls._zarr_v2_names and an "object_codec_id" key that is None.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        bool
+            True if the input is a valid JSON representation, False otherwise.
+        """
+        return (
+            check_dtype_spec_v2(data)
+            and data["name"] in cls._zarr_v2_names
+            and data["object_codec_id"] is None
+        )
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[str]:
+        """
+        Check that the input is a valid JSON representation of this data type in Zarr V3.
+
+        This method verifies that the provided data matches the expected Zarr V3
+        representation, which is the string specified by the class-level attribute _zarr_v3_name.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[str]
+            True if the input is a valid representation of this class in Zarr V3, False otherwise.
+        """
+
+        return data == cls._zarr_v3_name
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this class from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this class.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v2(data):
+            # Going via numpy ensures that we get the endianness correct without
+            # annoying string parsing.
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names}."
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this class from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected {cls._zarr_v3_name}."
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[str, None]: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> str: ...
+
+    def to_json(self, zarr_format: ZarrFormat) -> DTypeConfig_V2[str, None] | str:
+        """
+        Serialize this object to a JSON-serializable representation.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version. Supported values are 2 and 3.
+
+        Returns
+        -------
+        DTypeConfig_V2[str, None] | str
+            If ``zarr_format`` is 2, a dictionary with ``"name"`` and ``"object_codec_id"`` keys is
+            returned.
+            If ``zarr_format`` is 3, a string representation of the complex data type is returned.
+
+        Raises
+        ------
+        ValueError
+            If `zarr_format` is not 2 or 3.
+        """
+
+        if zarr_format == 2:
+            return {"name": self.to_native_dtype().str, "object_codec_id": None}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def _check_scalar(self, data: object) -> TypeGuard[ComplexLike]:
+        """
+        Check that the input is a scalar complex value.
+
+        Parameters
+        ----------
+        data : object
+            The value to check.
+
+        Returns
+        -------
+        TypeGuard[ComplexLike]
+            True if the input is a scalar complex value, False otherwise.
+        """
+        return isinstance(data, ComplexLike)
+
+    def _cast_scalar_unchecked(self, data: ComplexLike) -> TComplexScalar_co:
+        """
+        Cast the provided scalar data to the native scalar type of this class.
+
+        Parameters
+        ----------
+        data : ComplexLike
+            The data to cast.
+
+        Returns
+        -------
+        TComplexScalar_co
+            The casted data as a numpy complex scalar.
+
+        Notes
+        -----
+        This method does not perform any type checking.
+        The input data must be a scalar complex value.
+        """
+        return self.to_native_dtype().type(data)  # type: ignore[return-value]
+
+    def cast_scalar(self, data: object) -> TComplexScalar_co:
+        """
+        Attempt to cast a given object to a numpy complex scalar.
+
+        Parameters
+        ----------
+        data : object
+            The data to be cast to a numpy complex scalar.
+
+        Returns
+        -------
+        TComplexScalar_co
+            The data cast as a numpy complex scalar.
+
+        Raises
+        ------
+        TypeError
+            If the data cannot be converted to a numpy complex scalar.
+        """
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        msg = (
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)
+
+    def default_scalar(self) -> TComplexScalar_co:
+        """
+        Get the default value, which is 0 cast to this dtype
+
+        Returns
+        -------
+        Int scalar
+            The default value.
+        """
+        return self._cast_scalar_unchecked(0)
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TComplexScalar_co:
+        """
+        Read a JSON-serializable value as a numpy float.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON-serializable value.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        TScalar_co
+            The numpy float.
+        """
+        if zarr_format == 2:
+            if check_json_complex_float_v2(data):
+                return self._cast_scalar_unchecked(complex_float_from_json_v2(data))
+            raise TypeError(
+                f"Invalid type: {data}. Expected a float or a special string encoding of a float."
+            )
+        elif zarr_format == 3:
+            if check_json_complex_float_v3(data):
+                return self._cast_scalar_unchecked(complex_float_from_json_v3(data))
+            raise TypeError(
+                f"Invalid type: {data}. Expected a float or a special string encoding of a float."
+            )
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> JSON:
+        """
+        Convert an object to a JSON-serializable float.
+
+        Parameters
+        ----------
+        data : _BaseScalar
+            The value to convert.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        JSON
+            The JSON-serializable form of the complex number, which is a list of two floats,
+            each of which is encoding according to a zarr-format-specific encoding.
+        """
+        if zarr_format == 2:
+            return complex_float_to_json_v2(self.cast_scalar(data))
+        elif zarr_format == 3:
+            return complex_float_to_json_v3(self.cast_scalar(data))
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+
+@dataclass(frozen=True, kw_only=True)
+class Complex64(BaseComplex[np.dtypes.Complex64DType, np.complex64]):
+    """
+    A Zarr data type for arrays containing 64 bit complex floats.
+
+    Wraps the [`np.dtypes.Complex64DType`][numpy.dtypes.Complex64DType] data type. Scalars for this data type
+    are instances of [`np.complex64`][numpy.complex64].
+
+    Attributes
+    ----------
+    dtype_cls : Type[np.dtypes.Complex64DType]
+        The numpy dtype class for this data type.
+    _zarr_v3_name : ClassVar[Literal["complex64"]]
+        The name of this data type in Zarr V3.
+    _zarr_v2_names : ClassVar[tuple[Literal[">c8"], Literal["<c8"]]]
+        The names of this data type in Zarr V2.
+    """
+
+    dtype_cls = np.dtypes.Complex64DType
+    _zarr_v3_name: ClassVar[Literal["complex64"]] = "complex64"
+    _zarr_v2_names: ClassVar[tuple[Literal[">c8"], Literal["<c8"]]] = (">c8", "<c8")
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 8
+
+
+@dataclass(frozen=True, kw_only=True)
+class Complex128(BaseComplex[np.dtypes.Complex128DType, np.complex128], HasEndianness):
+    """
+    A Zarr data type for arrays containing 64 bit complex floats.
+
+    Wraps the [`np.dtypes.Complex128DType`][numpy.dtypes.Complex128DType] data type. Scalars for this data type
+    are instances of [`np.complex128`][numpy.complex128].
+
+    Attributes
+    ----------
+    dtype_cls : Type[np.dtypes.Complex128DType]
+        The numpy dtype class for this data type.
+    _zarr_v3_name : ClassVar[Literal["complex128"]]
+        The name of this data type in Zarr V3.
+    _zarr_v2_names : ClassVar[tuple[Literal[">c16"], Literal["<c16"]]]
+        The names of this data type in Zarr V2.
+    """
+
+    dtype_cls = np.dtypes.Complex128DType
+    _zarr_v3_name: ClassVar[Literal["complex128"]] = "complex128"
+    _zarr_v2_names: ClassVar[tuple[Literal[">c16"], Literal["<c16"]]] = (">c16", "<c16")
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 16

.venv/lib/python3.11/site-packages/zarr/core/dtype/npy/float.py

@@ -0,0 +1,435 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar, Literal, Self, TypeGuard, overload
+
+import numpy as np
+
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    DTypeConfig_V2,
+    DTypeJSON,
+    HasEndianness,
+    HasItemSize,
+    check_dtype_spec_v2,
+)
+from zarr.core.dtype.npy.common import (
+    FloatLike,
+    TFloatDType_co,
+    TFloatScalar_co,
+    check_json_float_v2,
+    check_json_float_v3,
+    check_json_floatish_str,
+    endianness_to_numpy_str,
+    float_from_json_v2,
+    float_from_json_v3,
+    float_to_json_v2,
+    float_to_json_v3,
+    get_endianness_from_numpy_dtype,
+)
+from zarr.core.dtype.wrapper import TBaseDType, ZDType
+
+if TYPE_CHECKING:
+    from zarr.core.common import JSON, ZarrFormat
+
+
+@dataclass(frozen=True)
+class BaseFloat(ZDType[TFloatDType_co, TFloatScalar_co], HasEndianness, HasItemSize):
+    """
+    A base class for Zarr data types that wrap NumPy float data types.
+    """
+
+    # This attribute holds the possible zarr v2 JSON names for the data type
+    _zarr_v2_names: ClassVar[tuple[str, ...]]
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of this ZDType from a NumPy data type.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The NumPy data type.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> TFloatDType_co:
+        """
+        Convert the wrapped data type to a NumPy data type.
+
+        Returns
+        -------
+        TFloatDType_co
+            The NumPy data type.
+        """
+        byte_order = endianness_to_numpy_str(self.endianness)
+        return self.dtype_cls().newbyteorder(byte_order)  # type: ignore[return-value]
+
+    @classmethod
+    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[DTypeConfig_V2[str, None]]:
+        """
+        Check that the input is a valid JSON representation of this data type.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        TypeGuard[DTypeConfig_V2[str, None]]
+            True if the input is a valid JSON representation of this data type, False otherwise.
+        """
+        return (
+            check_dtype_spec_v2(data)
+            and data["name"] in cls._zarr_v2_names
+            and data["object_codec_id"] is None
+        )
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[str]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        TypeGuard[str]
+            True if the input is a valid JSON representation of this class, False otherwise.
+        """
+        return data == cls._zarr_v3_name
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this ZDType from Zarr v2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+        """
+        if cls._check_json_v2(data):
+            # Going via NumPy ensures that we get the endianness correct without
+            # annoying string parsing.
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names}."
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this ZDType from Zarr v3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected {cls._zarr_v3_name}."
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[str, None]: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> str: ...
+
+    def to_json(self, zarr_format: ZarrFormat) -> DTypeConfig_V2[str, None] | str:
+        """
+        Convert the wrapped data type to a JSON-serializable form.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        DTypeConfig_V2[str, None] or str
+            The JSON-serializable representation of the wrapped data type.
+
+        Raises
+        ------
+        ValueError
+            If zarr_format is not 2 or 3.
+        """
+        if zarr_format == 2:
+            return {"name": self.to_native_dtype().str, "object_codec_id": None}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def _check_scalar(self, data: object) -> TypeGuard[FloatLike]:
+        """
+        Check that the input is a valid scalar value.
+
+        Parameters
+        ----------
+        data : object
+            The input to check.
+
+        Returns
+        -------
+        TypeGuard[FloatLike]
+            True if the input is a valid scalar value, False otherwise.
+        """
+        if isinstance(data, str):
+            # Only accept strings that are valid float representations (e.g. "NaN", "inf").
+            # Plain strings that cannot be converted should return False so that cast_scalar
+            # raises TypeError rather than a confusing ValueError.
+            try:
+                self.to_native_dtype().type(data)
+            except (ValueError, OverflowError):
+                return False
+            else:
+                return True
+        return isinstance(data, FloatLike)
+
+    def _cast_scalar_unchecked(self, data: FloatLike) -> TFloatScalar_co:
+        """
+        Cast a scalar value to a NumPy float scalar.
+
+        Parameters
+        ----------
+        data : FloatLike
+            The scalar value to cast.
+
+        Returns
+        -------
+        TFloatScalar_co
+            The NumPy float scalar.
+        """
+        return self.to_native_dtype().type(data)  # type: ignore[return-value]
+
+    def cast_scalar(self, data: object) -> TFloatScalar_co:
+        """
+        Cast a scalar value to a NumPy float scalar.
+
+        Parameters
+        ----------
+        data : object
+            The scalar value to cast.
+
+        Returns
+        -------
+        TFloatScalar_co
+            The NumPy float scalar.
+        """
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        msg = (
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)
+
+    def default_scalar(self) -> TFloatScalar_co:
+        """
+        Get the default value, which is 0 cast to this zdtype.
+
+        Returns
+        -------
+        TFloatScalar_co
+            The default value.
+        """
+        return self._cast_scalar_unchecked(0)
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TFloatScalar_co:
+        """
+        Read a JSON-serializable value as a NumPy float scalar.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON-serializable value.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        TFloatScalar_co
+            The NumPy float scalar.
+        """
+        if zarr_format == 2:
+            if check_json_float_v2(data):
+                return self._cast_scalar_unchecked(float_from_json_v2(data))
+            elif check_json_floatish_str(data):
+                return self._cast_scalar_unchecked(float(data))
+            else:
+                raise TypeError(
+                    f"Invalid type: {data}. Expected a float or a special string encoding of a float."
+                )
+        elif zarr_format == 3:
+            if check_json_float_v3(data):
+                return self._cast_scalar_unchecked(float_from_json_v3(data))
+            elif check_json_floatish_str(data):
+                return self._cast_scalar_unchecked(float(data))
+            else:
+                raise TypeError(
+                    f"Invalid type: {data}. Expected a float or a special string encoding of a float."
+                )
+        else:
+            raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> float | str:
+        """
+        Convert an object to a JSON-serializable float.
+
+        Parameters
+        ----------
+        data : _BaseScalar
+            The value to convert.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        JSON
+            The JSON-serializable form of the float, which is potentially a number or a string.
+            See the zarr specifications for details on the JSON encoding for floats.
+        """
+        if zarr_format == 2:
+            return float_to_json_v2(self.cast_scalar(data))
+        elif zarr_format == 3:
+            return float_to_json_v3(self.cast_scalar(data))
+        else:
+            raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+
+@dataclass(frozen=True, kw_only=True)
+class Float16(BaseFloat[np.dtypes.Float16DType, np.float16]):
+    """
+    A Zarr data type for arrays containing 16-bit floating point numbers.
+
+    Wraps the [`np.dtypes.Float16DType`][numpy.dtypes.Float16DType] data type. Scalars for this data type are instances
+    of [`np.float16`][numpy.float16].
+
+    Attributes
+    ----------
+    dtype_cls : Type[np.dtypes.Float16DType]
+        The NumPy dtype class for this data type.
+
+    References
+    ----------
+    This class implements the float16 data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.Float16DType
+    _zarr_v3_name = "float16"
+    _zarr_v2_names: ClassVar[tuple[Literal[">f2"], Literal["<f2"]]] = (">f2", "<f2")
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 2
+
+
+@dataclass(frozen=True, kw_only=True)
+class Float32(BaseFloat[np.dtypes.Float32DType, np.float32]):
+    """
+    A Zarr data type for arrays containing 32-bit floating point numbers.
+
+    Wraps the [`np.dtypes.Float32DType`][numpy.dtypes.Float32DType] data type. Scalars for this data type are instances
+    of [`np.float32`][numpy.float32].
+
+    Attributes
+    ----------
+    dtype_cls : Type[np.dtypes.Float32DType]
+        The NumPy dtype class for this data type.
+
+    References
+    ----------
+    This class implements the float32 data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.Float32DType
+    _zarr_v3_name = "float32"
+    _zarr_v2_names: ClassVar[tuple[Literal[">f4"], Literal["<f4"]]] = (">f4", "<f4")
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 4
+
+
+@dataclass(frozen=True, kw_only=True)
+class Float64(BaseFloat[np.dtypes.Float64DType, np.float64]):
+    """
+    A Zarr data type for arrays containing 64-bit floating point numbers.
+
+    Wraps the [`np.dtypes.Float64DType`][numpy.dtypes.Float64DType] data type. Scalars for this data type are instances
+    of [`np.float64`][numpy.float64].
+
+    Attributes
+    ----------
+    dtype_cls : Type[np.dtypes.Float64DType]
+        The NumPy dtype class for this data type.
+
+    References
+    ----------
+    This class implements the float64 data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.Float64DType
+    _zarr_v3_name = "float64"
+    _zarr_v2_names: ClassVar[tuple[Literal[">f8"], Literal["<f8"]]] = (">f8", "<f8")
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 8

.venv/lib/python3.11/site-packages/zarr/core/dtype/npy/int.py

@@ -0,0 +1,1521 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Literal,
+    Self,
+    SupportsIndex,
+    SupportsInt,
+    TypeGuard,
+    TypeVar,
+    overload,
+)
+
+import numpy as np
+
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    DTypeConfig_V2,
+    DTypeJSON,
+    HasEndianness,
+    HasItemSize,
+    check_dtype_spec_v2,
+)
+from zarr.core.dtype.npy.common import (
+    check_json_int,
+    check_json_intish_float,
+    check_json_intish_str,
+    endianness_to_numpy_str,
+    get_endianness_from_numpy_dtype,
+)
+from zarr.core.dtype.wrapper import TBaseDType, ZDType
+
+if TYPE_CHECKING:
+    from zarr.core.common import JSON, ZarrFormat
+
+_NumpyIntDType = (
+    np.dtypes.Int8DType
+    | np.dtypes.Int16DType
+    | np.dtypes.Int32DType
+    | np.dtypes.Int64DType
+    | np.dtypes.UInt8DType
+    | np.dtypes.UInt16DType
+    | np.dtypes.UInt32DType
+    | np.dtypes.UInt64DType
+)
+_NumpyIntScalar = (
+    np.int8 | np.int16 | np.int32 | np.int64 | np.uint8 | np.uint16 | np.uint32 | np.uint64
+)
+TIntDType_co = TypeVar("TIntDType_co", bound=_NumpyIntDType, covariant=True)
+TIntScalar_co = TypeVar("TIntScalar_co", bound=_NumpyIntScalar, covariant=True)
+IntLike = SupportsInt | SupportsIndex | bytes | str
+
+
+@dataclass(frozen=True)
+class BaseInt(ZDType[TIntDType_co, TIntScalar_co], HasItemSize):
+    """
+    A base class for integer data types in Zarr.
+
+    This class provides methods for serialization and deserialization of integer types
+    in both Zarr v2 and v3 formats, as well as methods for checking and casting scalars.
+    """
+
+    _zarr_v2_names: ClassVar[tuple[str, ...]]
+
+    @classmethod
+    def _check_json_v2(cls, data: object) -> TypeGuard[DTypeConfig_V2[str, None]]:
+        """
+        Check that the input is a valid JSON representation of this integer data type in Zarr V2.
+
+        This method verifies that the provided data matches the expected Zarr V2 representation
+        for this data type. The input data must be a mapping that contains a "name" key that is
+        one of the strings from cls._zarr_v2_names and an "object_codec_id" key that is None.
+
+        Parameters
+        ----------
+        data : object
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[DTypeConfig_V2[str, None]]
+            True if the input is a valid representation of this class in Zarr V2,
+            False otherwise.
+        """
+
+        return (
+            check_dtype_spec_v2(data)
+            and data["name"] in cls._zarr_v2_names
+            and data["object_codec_id"] is None
+        )
+
+    @classmethod
+    def _check_json_v3(cls, data: object) -> TypeGuard[str]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Parameters
+        ----------
+        data : object
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[str]
+            True if the input is a valid representation of this class in Zarr v3,
+            False otherwise.
+        """
+        return data == cls._zarr_v3_name
+
+    def _check_scalar(self, data: object) -> TypeGuard[IntLike]:
+        """
+        Check if the input object is of an IntLike type.
+
+        This method verifies whether the provided data can be considered as an integer-like
+        value, which includes objects supporting integer conversion.
+
+        Parameters
+        ----------
+        data : object
+            The data to check.
+
+        Returns
+        -------
+        TypeGuard[IntLike]
+            True if the data is IntLike, False otherwise.
+        """
+
+        return isinstance(data, IntLike)
+
+    def _cast_scalar_unchecked(self, data: IntLike) -> TIntScalar_co:
+        """
+        Casts a given scalar value to the native integer scalar type without type checking.
+
+        Parameters
+        ----------
+        data : IntLike
+            The scalar value to cast.
+
+        Returns
+        -------
+        TIntScalar_co
+            The casted integer scalar of the native dtype.
+        """
+
+        return self.to_native_dtype().type(data)  # type: ignore[return-value]
+
+    def cast_scalar(self, data: object) -> TIntScalar_co:
+        """
+        Attempt to cast a given object to a NumPy integer scalar.
+
+        Parameters
+        ----------
+        data : object
+            The data to be cast to a NumPy integer scalar.
+
+        Returns
+        -------
+        TIntScalar_co
+            The data cast as a NumPy integer scalar.
+
+        Raises
+        ------
+        TypeError
+            If the data cannot be converted to a NumPy integer scalar.
+        """
+
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        msg = (
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)
+
+    def default_scalar(self) -> TIntScalar_co:
+        """
+        Get the default value, which is 0 cast to this dtype.
+
+        Returns
+        -------
+        TIntScalar_co
+            The default value.
+        """
+        return self._cast_scalar_unchecked(0)
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TIntScalar_co:
+        """
+        Read a JSON-serializable value as a NumPy int scalar.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON-serializable value.
+        zarr_format : ZarrFormat
+            The Zarr format version.
+
+        Returns
+        -------
+        TIntScalar_co
+            The NumPy int scalar.
+
+        Raises
+        ------
+        TypeError
+            If the input is not a valid integer type.
+        """
+        if check_json_int(data):
+            return self._cast_scalar_unchecked(data)
+        if check_json_intish_float(data):
+            return self._cast_scalar_unchecked(int(data))
+
+        if check_json_intish_str(data):
+            return self._cast_scalar_unchecked(int(data))
+
+        raise TypeError(f"Invalid type: {data}. Expected an integer.")
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
+        """
+        Convert an object to a JSON serializable scalar. For the integer data types,
+        the JSON form is a plain integer.
+
+        Parameters
+        ----------
+        data : object
+            The value to convert.
+        zarr_format : ZarrFormat
+            The Zarr format version.
+
+        Returns
+        -------
+        int
+            The JSON-serializable form of the scalar.
+        """
+        return int(self.cast_scalar(data))
+
+
+@dataclass(frozen=True, kw_only=True)
+class Int8(BaseInt[np.dtypes.Int8DType, np.int8]):
+    """
+    A Zarr data type for arrays containing 8-bit signed integers.
+
+    Wraps the [`np.dtypes.Int8DType`][numpy.dtypes.Int8DType] data type. Scalars for this data type are
+    instances of [`np.int8`][numpy.int8].
+
+    Attributes
+    ----------
+    dtype_cls : np.dtypes.Int8DType
+        The class of the underlying NumPy dtype.
+
+    References
+    ----------
+    This class implements the 8-bit signed integer data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.Int8DType
+    _zarr_v3_name: ClassVar[Literal["int8"]] = "int8"
+    _zarr_v2_names: ClassVar[tuple[Literal["|i1"]]] = ("|i1",)
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an Int8 from an np.dtype('int8') instance.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The np.dtype('int8') instance.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data type is not a valid representation of this class Int8.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls()
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self: Self) -> np.dtypes.Int8DType:
+        """
+        Convert the Int8 instance to an np.dtype('int8') instance.
+
+        Returns
+        -------
+        np.dtypes.Int8DType
+            The np.dtype('int8') instance.
+        """
+        return self.dtype_cls()
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an Int8 from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class Int8.
+        """
+        if cls._check_json_v2(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v2_names[0]!r}"
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an Int8 from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class Int8.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal["|i1"], None]: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["int8"]: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[Literal["|i1"], None] | Literal["int8"]:
+        """
+        Convert the data type to a JSON-serializable form.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version.
+
+        Returns
+        -------
+        ``DTypeConfig_V2[Literal["|i1"], None] | Literal["int8"]``
+            The JSON-serializable representation of the data type.
+
+        Raises
+        ------
+        ValueError
+            If the zarr_format is not 2 or 3.
+        """
+        if zarr_format == 2:
+            return {"name": self._zarr_v2_names[0], "object_codec_id": None}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 1
+
+
+@dataclass(frozen=True, kw_only=True)
+class UInt8(BaseInt[np.dtypes.UInt8DType, np.uint8]):
+    """
+    A Zarr data type for arrays containing 8-bit unsigned integers.
+
+    Wraps the [`np.dtypes.UInt8DType`][numpy.dtypes.UInt8DType] data type. Scalars for this data type are instances of [`np.uint8`][numpy.uint8].
+
+    Attributes
+    ----------
+    dtype_cls : np.dtypes.UInt8DType
+        The class of the underlying NumPy dtype.
+
+    References
+    ----------
+    This class implements the 8-bit unsigned integer data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.UInt8DType
+    _zarr_v3_name: ClassVar[Literal["uint8"]] = "uint8"
+    _zarr_v2_names: ClassVar[tuple[Literal["|u1"]]] = ("|u1",)
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create a UInt8 from an np.dtype('uint8') instance.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls()
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self: Self) -> np.dtypes.UInt8DType:
+        """
+        Create a NumPy unsigned 8-bit integer dtype instance from this UInt8 ZDType.
+
+        Returns
+        -------
+        np.dtypes.UInt8DType
+            The NumPy unsigned 8-bit integer dtype.
+        """
+
+        return self.dtype_cls()
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+
+        if cls._check_json_v2(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v2_names[0]!r}"
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal["|u1"], None]: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["uint8"]: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[Literal["|u1"], None] | Literal["uint8"]:
+        """
+        Convert the data type to a JSON-serializable form.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version. Supported values are 2 and 3.
+
+        Returns
+        -------
+        ``DTypeConfig_V2[Literal["|u1"], None] | Literal["uint8"]``
+            The JSON-serializable representation of the data type.
+
+        Raises
+        ------
+        ValueError
+            If `zarr_format` is not 2 or 3.
+        """
+        if zarr_format == 2:
+            # For Zarr format version 2, return a dictionary with the name and object codec ID.
+            return {"name": self._zarr_v2_names[0], "object_codec_id": None}
+        elif zarr_format == 3:
+            # For Zarr format version 3, return the v3 name as a string.
+            return self._zarr_v3_name
+        # Raise an error if the zarr_format is neither 2 nor 3.
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 1
+
+
+@dataclass(frozen=True, kw_only=True)
+class Int16(BaseInt[np.dtypes.Int16DType, np.int16], HasEndianness):
+    """
+    A Zarr data type for arrays containing 16-bit signed integers.
+
+    Wraps the [`np.dtypes.Int16DType`][numpy.dtypes.Int16DType] data type. Scalars for this data type are instances of
+    [`np.int16`][numpy.int16].
+
+    Attributes
+    ----------
+    dtype_cls : np.dtypes.Int16DType
+        The class of the underlying NumPy dtype.
+
+    References
+    ----------
+    This class implements the 16-bit signed integer data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.Int16DType
+    _zarr_v3_name: ClassVar[Literal["int16"]] = "int16"
+    _zarr_v2_names: ClassVar[tuple[Literal[">i2"], Literal["<i2"]]] = (">i2", "<i2")
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of this data type from an np.dtype('int16') instance.
+
+        Parameters
+        ----------
+        dtype : np.dtype
+            The instance of np.dtype('int16') to create from.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data type is not an instance of np.dtype('int16').
+        """
+        if cls._check_native_dtype(dtype):
+            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> np.dtypes.Int16DType:
+        """
+        Convert the data type to an np.dtype('int16') instance.
+
+        Returns
+        -------
+        np.dtype
+            The np.dtype('int16') instance.
+        """
+        byte_order = endianness_to_numpy_str(self.endianness)
+        return self.dtype_cls().newbyteorder(byte_order)
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v2(data):
+            # Going via NumPy ensures that we get the endianness correct without
+            # annoying string parsing.
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names!r}."
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">i2", "<i2"], None]: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["int16"]: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[Literal[">i2", "<i2"], None] | Literal["int16"]:
+        """
+        Serialize this ZDType to v2- or v3-flavored JSON
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version (2 or 3).
+
+        Returns
+        -------
+        DTypeConfig_V2[Literal[">i2", "<i2"], None] or Literal["int16"]
+            The JSON representation of the Int16 instance.
+
+        Raises
+        ------
+        ValueError
+            If the zarr_format is not 2 or 3.
+        """
+        if zarr_format == 2:
+            name = self.to_native_dtype().str
+            return {"name": name, "object_codec_id": None}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 2
+
+
+@dataclass(frozen=True, kw_only=True)
+class UInt16(BaseInt[np.dtypes.UInt16DType, np.uint16], HasEndianness):
+    """
+    A Zarr data type for arrays containing 16-bit unsigned integers.
+
+    Wraps the [`np.dtypes.UInt16DType`][numpy.dtypes.UInt16DType] data type. Scalars for this data type are instances of
+    [`np.uint16`][numpy.uint16].
+
+    Attributes
+    ----------
+    dtype_cls : np.dtypes.UInt16DType
+        The class of the underlying NumPy dtype.
+
+    References
+    ----------
+    This class implements the unsigned 16-bit unsigned integer data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.UInt16DType
+    _zarr_v3_name: ClassVar[Literal["uint16"]] = "uint16"
+    _zarr_v2_names: ClassVar[tuple[Literal[">u2"], Literal["<u2"]]] = (">u2", "<u2")
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of this data type from an np.dtype('uint16') instance.
+
+        Parameters
+        ----------
+        dtype : np.dtype
+            The NumPy data type.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data type is not an instance of np.dtype('uint16').
+        """
+        if cls._check_native_dtype(dtype):
+            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> np.dtypes.UInt16DType:
+        """
+        Convert the data type to an np.dtype('uint16') instance.
+
+        Returns
+        -------
+        np.dtype
+            The np.dtype('uint16') instance.
+        """
+        byte_order = endianness_to_numpy_str(self.endianness)
+        return self.dtype_cls().newbyteorder(byte_order)
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v2(data):
+            # Going via NumPy ensures that we get the endianness correct without
+            # annoying string parsing.
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        msg = f"Invalid JSON representation of UInt16. Got {data!r}, expected one of the strings {cls._zarr_v2_names}."
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of UInt16. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">u2", "<u2"], None]: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["uint16"]: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[Literal[">u2", "<u2"], None] | Literal["uint16"]:
+        """
+        Serialize this ZDType to v2- or v3-flavored JSON
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version (2 or 3).
+
+        Returns
+        -------
+        DTypeConfig_V2[Literal[">u2", "<u2"], None] or Literal["uint16"]
+            The JSON representation of the UInt16 instance.
+
+        Raises
+        ------
+        ValueError
+            If the zarr_format is not 2 or 3.
+        """
+        if zarr_format == 2:
+            name = self.to_native_dtype().str
+            return {"name": name, "object_codec_id": None}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 2
+
+
+@dataclass(frozen=True, kw_only=True)
+class Int32(BaseInt[np.dtypes.Int32DType, np.int32], HasEndianness):
+    """
+    A Zarr data type for arrays containing 32-bit signed integers.
+
+    Wraps the [`np.dtypes.Int32DType`][numpy.dtypes.Int32DType] data type. Scalars for this data type are instances of
+    [`np.int32`][numpy.int32].
+
+    Attributes
+    ----------
+    dtype_cls : np.dtypes.Int32DType
+        The class of the underlying NumPy dtype.
+
+    References
+    ----------
+    This class implements the 32-bit signed integer data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.Int32DType
+    _zarr_v3_name: ClassVar[Literal["int32"]] = "int32"
+    _zarr_v2_names: ClassVar[tuple[Literal[">i4"], Literal["<i4"]]] = (">i4", "<i4")
+
+    @classmethod
+    def _check_native_dtype(cls: type[Self], dtype: TBaseDType) -> TypeGuard[np.dtypes.Int32DType]:
+        """
+        A type guard that checks if the input is assignable to the type of ``cls.dtype_class``
+
+        This method is overridden for this particular data type because of a Windows-specific issue
+        where np.dtype('i') creates an instance of ``np.dtypes.IntDType``, rather than an
+        instance of ``np.dtypes.Int32DType``, even though both represent 32-bit signed integers.
+
+        Parameters
+        ----------
+        dtype : TDType
+            The dtype to check.
+
+        Returns
+        -------
+        Bool
+            True if the dtype matches, False otherwise.
+        """
+        return super()._check_native_dtype(dtype) or dtype == np.dtypes.Int32DType()
+
+    @classmethod
+    def from_native_dtype(cls: type[Self], dtype: TBaseDType) -> Self:
+        """
+        Create an Int32 from an np.dtype('int32') instance.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The np.dtype('int32') instance.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class Int32.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self: Self) -> np.dtypes.Int32DType:
+        """
+        Convert the Int32 instance to an np.dtype('int32') instance.
+
+        Returns
+        -------
+        np.dtypes.Int32DType
+            The np.dtype('int32') instance.
+        """
+        byte_order = endianness_to_numpy_str(self.endianness)
+        return self.dtype_cls().newbyteorder(byte_order)
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an Int32 from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class Int32.
+        """
+        if cls._check_json_v2(data):
+            # Going via NumPy ensures that we get the endianness correct without
+            # annoying string parsing.
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names!r}."
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an Int32 from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class Int32.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">i4", "<i4"], None]: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["int32"]: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[Literal[">i4", "<i4"], None] | Literal["int32"]:
+        """
+        Serialize this ZDType to v2- or v3-flavored JSON
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version (2 or 3).
+
+        Returns
+        -------
+        DTypeConfig_V2[Literal[">i4", "<i4"], None] or Literal["int32"]
+            The JSON representation of the Int32 instance.
+
+        Raises
+        ------
+        ValueError
+            If the zarr_format is not 2 or 3.
+        """
+        if zarr_format == 2:
+            name = self.to_native_dtype().str
+            return {"name": name, "object_codec_id": None}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 4
+
+
+@dataclass(frozen=True, kw_only=True)
+class UInt32(BaseInt[np.dtypes.UInt32DType, np.uint32], HasEndianness):
+    """
+    A Zarr data type for arrays containing 32-bit unsigned integers.
+
+    Wraps the [`np.dtypes.UInt32DType`][numpy.dtypes.UInt32DType] data type. Scalars for this data type are instances of
+    [`np.uint32`][numpy.uint32].
+
+    Attributes
+    ----------
+    dtype_cls : np.dtypes.UInt32DType
+        The class of the underlying NumPy dtype.
+
+    References
+    ----------
+    This class implements the 32-bit unsigned integer data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.UInt32DType
+    _zarr_v3_name: ClassVar[Literal["uint32"]] = "uint32"
+    _zarr_v2_names: ClassVar[tuple[Literal[">u4"], Literal["<u4"]]] = (">u4", "<u4")
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create a UInt32 from an np.dtype('uint32') instance.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The NumPy data type.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data type is not a valid representation of this class 32-bit unsigned
+            integer.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> np.dtypes.UInt32DType:
+        """
+        Create a NumPy unsigned 32-bit integer dtype instance from this UInt32 ZDType.
+
+        Returns
+        -------
+        np.dtypes.UInt32DType
+            The NumPy unsigned 32-bit integer dtype.
+        """
+        byte_order = endianness_to_numpy_str(self.endianness)
+        return self.dtype_cls().newbyteorder(byte_order)
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class 32-bit unsigned
+            integer.
+        """
+        if cls._check_json_v2(data):
+            # Going via NumPy ensures that we get the endianness correct without
+            # annoying string parsing.
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names}."
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class 32-bit unsigned
+            integer.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">u4", "<u4"], None]: ...
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["uint32"]: ...
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[Literal[">u4", "<u4"], None] | Literal["uint32"]:
+        """
+        Convert the data type to a JSON-serializable form.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version.
+
+        Returns
+        -------
+        DTypeConfig_V2[Literal[">u4", "<u4"], None] | Literal["uint32"]
+            The JSON-serializable representation of the data type
+        """
+        if zarr_format == 2:
+            name = self.to_native_dtype().str
+            return {"name": name, "object_codec_id": None}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 4
+
+
+@dataclass(frozen=True, kw_only=True)
+class Int64(BaseInt[np.dtypes.Int64DType, np.int64], HasEndianness):
+    """
+    A Zarr data type for arrays containing 64-bit signed integers.
+
+    Wraps the [`np.dtypes.Int64DType`][numpy.dtypes.Int64DType] data type. Scalars for this data type are instances of
+    [`np.int64`][numpy.int64].
+
+    Attributes
+    ----------
+    dtype_cls : np.dtypes.Int64DType
+        The class of the underlying NumPy dtype.
+
+    References
+    ----------
+    This class implements the 64-bit signed integer data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.Int64DType
+    _zarr_v3_name: ClassVar[Literal["int64"]] = "int64"
+    _zarr_v2_names: ClassVar[tuple[Literal[">i8"], Literal["<i8"]]] = (">i8", "<i8")
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an Int64 from an np.dtype('int64') instance.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The NumPy data type.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data type is not a valid representation of this class 64-bit signed
+            integer.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> np.dtypes.Int64DType:
+        """
+        Create a NumPy signed 64-bit integer dtype instance from this Int64 ZDType.
+
+        Returns
+        -------
+        np.dtypes.Int64DType
+            The NumPy signed 64-bit integer dtype.
+        """
+        byte_order = endianness_to_numpy_str(self.endianness)
+        return self.dtype_cls().newbyteorder(byte_order)
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class 64-bit signed
+            integer.
+        """
+        if cls._check_json_v2(data):
+            # Going via NumPy ensures that we get the endianness correct without
+            # annoying string parsing.
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names}."
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class 64-bit signed
+            integer.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">i8", "<i8"], None]: ...
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["int64"]: ...
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[Literal[">i8", "<i8"], None] | Literal["int64"]:
+        """
+        Convert the data type to a JSON-serializable form.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version.
+
+        Returns
+        -------
+        DTypeConfig_V2[Literal[">i8", "<i8"], None] | Literal["int64"]
+            The JSON-serializable representation of the data type.
+        """
+        if zarr_format == 2:
+            name = self.to_native_dtype().str
+            return {"name": name, "object_codec_id": None}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 8
+
+
+@dataclass(frozen=True, kw_only=True)
+class UInt64(BaseInt[np.dtypes.UInt64DType, np.uint64], HasEndianness):
+    """
+    A Zarr data type for arrays containing 64-bit unsigned integers.
+
+    Wraps the [`np.dtypes.UInt64DType`][numpy.dtypes.UInt64DType] data type. Scalars for this data type
+    are instances of [`np.uint64`][numpy.uint64].
+
+    Attributes
+    ----------
+    dtype_cls: np.dtypes.UInt64DType
+        The class of the underlying NumPy dtype.
+
+    References
+    ----------
+    This class implements the unsigned 64-bit integer data type defined in Zarr V2 and V3.
+
+    See the [Zarr V2](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
+    """
+
+    dtype_cls = np.dtypes.UInt64DType
+    _zarr_v3_name: ClassVar[Literal["uint64"]] = "uint64"
+    _zarr_v2_names: ClassVar[tuple[Literal[">u8"], Literal["<u8"]]] = (">u8", "<u8")
+
+    def to_native_dtype(self) -> np.dtypes.UInt64DType:
+        """
+        Convert the data type to a native NumPy dtype.
+
+        Returns
+        -------
+        np.dtypes.UInt64DType
+            The native NumPy dtype.eeeeeeeeeeeeeeeee
+        """
+        byte_order = endianness_to_numpy_str(self.endianness)
+        return self.dtype_cls().newbyteorder(byte_order)
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class unsigned 64-bit
+            integer.
+        """
+        if cls._check_json_v2(data):
+            # Going via NumPy ensures that we get the endianness correct without
+            # annoying string parsing.
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names}."
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class unsigned 64-bit
+            integer.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">u8", "<u8"], None]: ...
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["uint64"]: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[Literal[">u8", "<u8"], None] | Literal["uint64"]:
+        """
+        Convert the data type to a JSON-serializable form.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version.
+
+        Returns
+        -------
+        DTypeConfig_V2[Literal[">u8", "<u8"], None] | Literal["uint64"]
+            The JSON-serializable representation of the data type.
+        """
+        if zarr_format == 2:
+            name = self.to_native_dtype().str
+            return {"name": name, "object_codec_id": None}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of this data type from a native NumPy dtype.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The native NumPy dtype.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input dtype is not a valid representation of this class unsigned 64-bit
+            integer.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 8

.venv/lib/python3.11/site-packages/zarr/core/dtype/npy/string.py

@@ -0,0 +1,825 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Literal,
+    Protocol,
+    Self,
+    TypedDict,
+    TypeGuard,
+    overload,
+    runtime_checkable,
+)
+
+import numpy as np
+
+from zarr.core.common import NamedConfig
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    DTypeConfig_V2,
+    DTypeJSON,
+    HasEndianness,
+    HasItemSize,
+    HasLength,
+    HasObjectCodec,
+    check_dtype_spec_v2,
+    v3_unstable_dtype_warning,
+)
+from zarr.core.dtype.npy.common import (
+    check_json_str,
+    endianness_to_numpy_str,
+    get_endianness_from_numpy_dtype,
+)
+from zarr.core.dtype.wrapper import TDType_co, ZDType
+
+if TYPE_CHECKING:
+    from zarr.core.common import JSON, ZarrFormat
+    from zarr.core.dtype.wrapper import TBaseDType
+
+_NUMPY_SUPPORTS_VLEN_STRING = hasattr(np.dtypes, "StringDType")
+
+
+@runtime_checkable
+class SupportsStr(Protocol):
+    def __str__(self) -> str: ...
+
+
+class LengthBytesConfig(TypedDict):
+    """
+    Configuration for a fixed-length string data type in Zarr V3.
+
+    Attributes
+    ----------
+    length_bytes : int
+        The length in bytes of the data associated with this configuration.
+    """
+
+    length_bytes: int
+
+
+class FixedLengthUTF32JSON_V2(DTypeConfig_V2[str, None]):
+    """
+    A wrapper around the JSON representation of the ``FixedLengthUTF32`` data type in Zarr V2.
+
+    The ``name`` field of this class contains the value that would appear under the
+    ``dtype`` field in Zarr V2 array metadata.
+
+    References
+    ----------
+    The structure of the ``name`` field is defined in the Zarr V2
+    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+
+    Examples
+    --------
+
+    ```python
+    {
+        "name": "<U12",
+        "object_codec_id": None
+    }
+    ```
+    """
+
+
+class FixedLengthUTF32JSON_V3(NamedConfig[Literal["fixed_length_utf32"], LengthBytesConfig]):
+    """
+    The JSON representation of the ``FixedLengthUTF32`` data type in Zarr V3.
+
+    References
+    ----------
+    This representation is not currently defined in an external specification.
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "fixed_length_utf32",
+        "configuration": {
+            "length_bytes": 12
+            }
+    }
+    ```
+    """
+
+
+@dataclass(frozen=True, kw_only=True)
+class FixedLengthUTF32(
+    ZDType[np.dtypes.StrDType[int], np.str_], HasEndianness, HasLength, HasItemSize
+):
+    """
+    A Zarr data type for arrays containing fixed-length UTF-32 strings.
+
+    Wraps the ``np.dtypes.StrDType`` data type. Scalars for this data type are instances of
+    ``np.str_``.
+
+    Attributes
+    ----------
+    dtype_cls : Type[np.dtypes.StrDType]
+        The NumPy dtype class for this data type.
+    _zarr_v3_name : ClassVar[Literal["fixed_length_utf32"]]
+        The name of this data type in Zarr V3.
+    code_point_bytes : ClassVar[int] = 4
+        The number of bytes per code point in UTF-32, which is 4.
+    """
+
+    dtype_cls = np.dtypes.StrDType
+    _zarr_v3_name: ClassVar[Literal["fixed_length_utf32"]] = "fixed_length_utf32"
+    code_point_bytes: ClassVar[int] = 4  # utf32 is 4 bytes per code point
+
+    def __post_init__(self) -> None:
+        """
+        We don't allow instances of this class with length less than 1 because there is no way such
+        a data type can contain actual data.
+        """
+        if self.length < 1:
+            raise ValueError(f"length must be >= 1, got {self.length}.")
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create a FixedLengthUTF32 from a NumPy data type.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The NumPy data type.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+        """
+        if cls._check_native_dtype(dtype):
+            endianness = get_endianness_from_numpy_dtype(dtype)
+            return cls(
+                length=dtype.itemsize // (cls.code_point_bytes),
+                endianness=endianness,
+            )
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> np.dtypes.StrDType[int]:
+        """
+        Convert the FixedLengthUTF32 instance to a NumPy data type.
+
+        Returns
+        -------
+        np.dtypes.StrDType[int]
+            The NumPy data type.
+        """
+        byte_order = endianness_to_numpy_str(self.endianness)
+        return self.dtype_cls(self.length).newbyteorder(byte_order)
+
+    @classmethod
+    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[FixedLengthUTF32JSON_V2]:
+        """
+        Check that the input is a valid JSON representation of a NumPy U dtype.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        TypeGuard[FixedLengthUTF32JSON_V2]
+            Whether the input is a valid JSON representation of a NumPy U dtype.
+        """
+        return (
+            check_dtype_spec_v2(data)
+            and isinstance(data["name"], str)
+            and re.match(r"^[><]U\d+$", data["name"]) is not None
+            and data["object_codec_id"] is None
+        )
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[FixedLengthUTF32JSON_V3]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        TypeGuard[FixedLengthUTF32JSONV3]
+            Whether the input is a valid JSON representation of a NumPy U dtype.
+        """
+        return (
+            isinstance(data, dict)
+            and set(data.keys()) == {"name", "configuration"}
+            and data["name"] == cls._zarr_v3_name
+            and "configuration" in data
+            and isinstance(data["configuration"], dict)
+            and set(data["configuration"].keys()) == {"length_bytes"}
+            and isinstance(data["configuration"]["length_bytes"], int)
+        )
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[str, None]: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> FixedLengthUTF32JSON_V3: ...
+
+    def to_json(
+        self, zarr_format: ZarrFormat
+    ) -> DTypeConfig_V2[str, None] | FixedLengthUTF32JSON_V3:
+        """
+        Convert the FixedLengthUTF32 instance to a JSON representation.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format to use.
+
+        Returns
+        -------
+        DTypeConfig_V2[str, None] | FixedLengthUTF32JSON_V3
+            The JSON representation of the data type.
+        """
+        if zarr_format == 2:
+            return {"name": self.to_native_dtype().str, "object_codec_id": None}
+        elif zarr_format == 3:
+            v3_unstable_dtype_warning(self)
+            return {
+                "name": self._zarr_v3_name,
+                "configuration": {"length_bytes": self.length * self.code_point_bytes},
+            }
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create a FixedLengthUTF32 from a JSON representation of a NumPy U dtype.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+        """
+        if cls._check_json_v2(data):
+            # Construct the NumPy dtype instead of string parsing.
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        raise DataTypeValidationError(
+            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a string representation of a NumPy U dtype."
+        )
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create a FixedLengthUTF32 from a JSON representation of a NumPy U dtype.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+        """
+        if cls._check_json_v3(data):
+            return cls(length=data["configuration"]["length_bytes"] // cls.code_point_bytes)
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected {cls._zarr_v3_name}."
+        raise DataTypeValidationError(msg)
+
+    def default_scalar(self) -> np.str_:
+        """
+        Return the default scalar value for this data type.
+
+        Returns
+        -------
+        ``np.str_``
+            The default scalar value.
+        """
+        return np.str_("")
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
+        """
+        Convert the scalar value to a JSON representation.
+
+        Parameters
+        ----------
+        data : object
+            The scalar value.
+        zarr_format : ZarrFormat
+            The Zarr format to use.
+
+        Returns
+        -------
+        str
+            The JSON representation of the scalar value.
+        """
+        return str(data)
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.str_:
+        """
+        Convert the JSON representation of a scalar value to the native scalar value.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON data.
+        zarr_format : ZarrFormat
+            The Zarr format to use.
+
+        Returns
+        -------
+        ``np.str_``
+            The native scalar value.
+        """
+        if check_json_str(data):
+            return self.to_native_dtype().type(data)
+        raise TypeError(f"Invalid type: {data}. Expected a string.")  # pragma: no cover
+
+    def _check_scalar(self, data: object) -> TypeGuard[SupportsStr]:
+        """
+        Check that the input is a valid scalar value for this data type.
+
+        Parameters
+        ----------
+        data : object
+            The scalar value.
+
+        Returns
+        -------
+        TypeGuard[SupportsStr]
+            Whether the input is a valid scalar value for this data type.
+        """
+        # this is generous for backwards compatibility
+        return isinstance(data, SupportsStr)
+
+    def cast_scalar(self, data: object) -> np.str_:
+        """
+        Cast the scalar value to the native scalar value.
+
+        Parameters
+        ----------
+        data : object
+            The scalar value.
+
+        Returns
+        -------
+        ``np.str_``
+            The native scalar value.
+        """
+        if self._check_scalar(data):
+            # We explicitly truncate before casting because of the following NumPy behavior:
+            # >>> x = np.dtype('U3').type('hello world')
+            # >>> x
+            # np.str_('hello world')
+            # >>> x.dtype
+            # dtype('U11')
+
+            return self.to_native_dtype().type(str(data)[: self.length])
+
+        msg = (  # pragma: no cover
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)  # pragma: no-cover
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return self.length * self.code_point_bytes
+
+
+def check_vlen_string_json_scalar(data: object) -> TypeGuard[int | str | float]:
+    """
+    Check if the input is a valid JSON scalar for a variable-length string.
+
+    This function is generous for backwards compatibility, as Zarr Python v2 would use ints for
+    variable-length string fill values.
+
+    Parameters
+    ----------
+    data : object
+        The JSON value to check.
+
+    Returns
+    -------
+    TypeGuard[int | str | float]
+        True if the input is a valid scalar for a variable-length string.
+    """
+    return isinstance(data, int | str | float)
+
+
+class VariableLengthUTF8JSON_V2(DTypeConfig_V2[Literal["|O"], Literal["vlen-utf8"]]):
+    """
+    A wrapper around the JSON representation of the ``VariableLengthUTF8`` data type in Zarr V2.
+
+    The ``name`` field of this class contains the value that would appear under the
+    ``dtype`` field in Zarr V2 array metadata. The ``object_codec_id`` field is always ``"vlen-utf8"``.
+
+    References
+    ----------
+    The structure of the ``name`` field is defined in the Zarr V2
+    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "|O",
+        "object_codec_id": "vlen-utf8"
+    }
+    ```
+    """
+
+
+# VariableLengthUTF8 is defined in two places, conditioned on the version of NumPy.
+# If NumPy 2 is installed, then VariableLengthUTF8 is defined with the NumPy variable length
+# string dtype as the native dtype. Otherwise, VariableLengthUTF8 is defined with the NumPy object
+# dtype as the native dtype.
+class UTF8Base(ZDType[TDType_co, str], HasObjectCodec):
+    """
+    A base class for variable-length UTF-8 string data types.
+
+    Not intended for direct use, but as a base for concrete implementations.
+
+    Attributes
+    ----------
+    object_codec_id : ClassVar[Literal["vlen-utf8"]]
+        The object codec ID for this data type.
+
+    References
+    ----------
+    This data type does not have a Zarr V3 specification.
+
+    The Zarr V2 data type specification can be found [here](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+    """
+
+    _zarr_v3_name: ClassVar[Literal["string"]] = "string"
+    object_codec_id: ClassVar[Literal["vlen-utf8"]] = "vlen-utf8"
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of this data type from a compatible NumPy data type.
+
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The native data type.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input is not compatible with this data type.
+        """
+        if cls._check_native_dtype(dtype):
+            return cls()
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    @classmethod
+    def _check_json_v2(
+        cls,
+        data: DTypeJSON,
+    ) -> TypeGuard[VariableLengthUTF8JSON_V2]:
+        """
+        "Check if the input is a valid JSON representation of a variable-length UTF-8 string dtype
+        for Zarr v2."
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        ``TypeGuard[VariableLengthUTF8JSON_V2]``
+            Whether the input is a valid JSON representation of a NumPy "object" data type, and that the
+            object codec id is appropriate for variable-length UTF-8 strings.
+        """
+        return (
+            check_dtype_spec_v2(data)
+            and data["name"] == "|O"
+            and data["object_codec_id"] == cls.object_codec_id
+        )
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[Literal["variable_length_utf8"]]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[Literal["variable_length_utf8"]]
+            Whether the input is a valid JSON representation of a variable length UTF-8 string
+            data type.
+        """
+        return data == cls._zarr_v3_name
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this class from a JSON representation of a NumPy "object" dtype.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to create an instance from.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+        """
+        if cls._check_json_v2(data):
+            return cls()
+        msg = (
+            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string '|O'"
+        )
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this class from a JSON representation of a variable length UTF-8
+        string data type.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to create an instance from.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+        """
+        if cls._check_json_v3(data):
+            return cls()
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected {cls._zarr_v3_name}."
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> VariableLengthUTF8JSON_V2: ...
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> Literal["string"]: ...
+
+    def to_json(self, zarr_format: ZarrFormat) -> VariableLengthUTF8JSON_V2 | Literal["string"]:
+        """
+        Convert this data type to a JSON representation.
+
+        Parameters
+        ----------
+        zarr_format : int
+            The zarr format to use for the JSON representation.
+
+        Returns
+        -------
+        ``VariableLengthUTF8JSON_V2 | Literal["string"]``
+            The JSON representation of this data type.
+        """
+        if zarr_format == 2:
+            return {"name": "|O", "object_codec_id": self.object_codec_id}
+        elif zarr_format == 3:
+            return self._zarr_v3_name
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def default_scalar(self) -> str:
+        """
+        Return the default scalar value for this data type.
+
+        Returns
+        -------
+        str
+            The default scalar value.
+        """
+        return ""
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
+        """
+        Convert a scalar value to a JSON representation.
+
+        Parameters
+        ----------
+        data : object
+            The scalar value to convert.
+        zarr_format : int
+            The zarr format to use for the JSON representation.
+
+        Returns
+        -------
+        str
+            The JSON representation of the scalar value.
+        """
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        raise TypeError(f"Invalid type: {data}. Expected a string.")
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> str:
+        """
+        Convert a JSON representation of a scalar value to the native scalar type.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON representation of the scalar value.
+        zarr_format : int
+            The zarr format to use for the JSON representation.
+
+        Returns
+        -------
+        str
+            The native scalar type of the scalar value.
+        """
+        if not check_vlen_string_json_scalar(data):
+            raise TypeError(f"Invalid type: {data}. Expected a string or number.")
+        return str(data)
+
+    def _check_scalar(self, data: object) -> TypeGuard[SupportsStr]:
+        """
+        Check that the input is a valid scalar value for this data type.
+
+        Parameters
+        ----------
+        data : object
+            The scalar value to check.
+
+        Returns
+        -------
+        TypeGuard[SupportsStr]
+            Whether the input is a valid scalar value for this data type.
+        """
+        return isinstance(data, SupportsStr)
+
+    def _cast_scalar_unchecked(self, data: SupportsStr) -> str:
+        """
+        Cast a scalar value to a string.
+
+        Parameters
+        ----------
+        data : object
+            The scalar value to cast.
+
+        Returns
+        -------
+        str
+            The string representation of the scalar value.
+        """
+        return str(data)
+
+    def cast_scalar(self, data: object) -> str:
+        """
+        Cast an object to a string.
+
+        Parameters
+        ----------
+        data : object
+            The value to cast.
+
+        Returns
+        -------
+        str
+            The input cast to str.
+        """
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        msg = (  # pragma: no cover
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)  # pragma: no cover
+
+
+if _NUMPY_SUPPORTS_VLEN_STRING:
+
+    @dataclass(frozen=True, kw_only=True)
+    class VariableLengthUTF8(UTF8Base[np.dtypes.StringDType]):  # type: ignore[type-var]
+        """
+        A Zarr data type for arrays containing variable-length UTF-8 strings.
+
+        Wraps the ``np.dtypes.StringDType`` data type. Scalars for this data type are instances
+        of ``str``.
+
+
+        Attributes
+        ----------
+        dtype_cls : Type[np.dtypes.StringDType]
+            The NumPy dtype class for this data type.
+        _zarr_v3_name : ClassVar[Literal["variable_length_utf8"]] = "variable_length_utf8"
+            The name of this data type in Zarr V3.
+        object_codec_id : ClassVar[Literal["vlen-utf8"]] = "vlen-utf8"
+            The object codec ID for this data type.
+        """
+
+        dtype_cls = np.dtypes.StringDType
+
+        @classmethod
+        def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+            """
+            Create an instance of this data type from a compatible NumPy data type.
+            We reject NumPy StringDType instances that have the `na_object` field set,
+            because this is not representable by the Zarr `string` data type.
+
+            Parameters
+            ----------
+            dtype : TBaseDType
+                The native data type.
+
+            Returns
+            -------
+            Self
+                An instance of this data type.
+
+            Raises
+            ------
+            DataTypeValidationError
+                If the input is not compatible with this data type.
+            ValueError
+                If the input is `numpy.dtypes.StringDType` and has `na_object` set.
+            """
+            if cls._check_native_dtype(dtype):
+                if hasattr(dtype, "na_object"):
+                    msg = (
+                        f"Zarr data type resolution from {dtype} failed. "
+                        "Attempted to resolve a zarr data type from a `numpy.dtypes.StringDType` "
+                        "with `na_object` set, which is not supported."
+                    )
+                    raise ValueError(msg)
+                return cls()
+            raise DataTypeValidationError(
+                f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+            )
+
+        def to_native_dtype(self) -> np.dtypes.StringDType:
+            """
+            Create a NumPy string dtype from this VariableLengthUTF8 ZDType.
+
+            Returns
+            -------
+            np.dtypes.StringDType
+                The NumPy string dtype.
+            """
+            return self.dtype_cls()
+
+else:
+    # Numpy pre-2 does not have a variable length string dtype, so we use the Object dtype instead.
+    @dataclass(frozen=True, kw_only=True)
+    class VariableLengthUTF8(UTF8Base[np.dtypes.ObjectDType]):  # type: ignore[no-redef]
+        """
+        A Zarr data type for arrays containing variable-length UTF-8 strings.
+
+        Wraps the ``np.dtypes.ObjectDType`` data type. Scalars for this data type are instances
+        of ``str``.
+
+
+        Attributes
+        ----------
+        dtype_cls : Type[np.dtypes.ObjectDType]
+            The NumPy dtype class for this data type.
+        _zarr_v3_name : ClassVar[Literal["variable_length_utf8"]] = "variable_length_utf8"
+            The name of this data type in Zarr V3.
+        object_codec_id : ClassVar[Literal["vlen-utf8"]] = "vlen-utf8"
+            The object codec ID for this data type.
+        """
+
+        dtype_cls = np.dtypes.ObjectDType
+
+        def to_native_dtype(self) -> np.dtypes.ObjectDType:
+            """
+            Create a NumPy object dtype from this VariableLengthUTF8 ZDType.
+
+            Returns
+            -------
+            np.dtypes.ObjectDType
+                The NumPy object dtype.
+            """
+            return self.dtype_cls()

.venv/lib/python3.11/site-packages/zarr/core/dtype/npy/structured.py

@@ -0,0 +1,477 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar, Literal, Self, TypeGuard, cast, overload
+
+import numpy as np
+
+from zarr.core.common import NamedConfig
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    DTypeConfig_V2,
+    DTypeJSON,
+    HasItemSize,
+    StructuredName_V2,
+    check_dtype_spec_v2,
+    check_structured_dtype_name_v2,
+    v3_unstable_dtype_warning,
+)
+from zarr.core.dtype.npy.common import (
+    bytes_from_json,
+    bytes_to_json,
+    check_json_str,
+)
+from zarr.core.dtype.wrapper import TBaseDType, TBaseScalar, ZDType
+
+if TYPE_CHECKING:
+    from zarr.core.common import JSON, ZarrFormat
+
+StructuredScalarLike = list[object] | tuple[object, ...] | bytes | int
+
+
+class StructuredJSON_V2(DTypeConfig_V2[StructuredName_V2, None]):
+    """
+    A wrapper around the JSON representation of the ``Structured`` data type in Zarr V2.
+
+    The ``name`` field is a sequence of sequences, where each inner sequence has two values:
+    the field name and the data type name for that field (which could be another sequence).
+    The data type names are strings, and the object codec ID is always None.
+
+    References
+    ----------
+    The structure of the ``name`` field is defined in the Zarr V2
+    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+
+    Examples
+    --------
+    ```python
+    {
+        "name": [
+            ["f0", "<m8[10s]"],
+            ["f1", "<m8[10s]"],
+        ],
+        "object_codec_id": None
+    }
+    ```
+    """
+
+
+class StructuredJSON_V3(
+    NamedConfig[Literal["structured"], dict[str, Sequence[Sequence[str | DTypeJSON]]]]
+):
+    """
+    A JSON representation of a structured data type in Zarr V3.
+
+    References
+    ----------
+    This representation is not currently defined in an external specification.
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "structured",
+        "configuration": {
+            "fields": [
+                ["f0", "int32"],
+                ["f1", "float64"],
+            ]
+        }
+    }
+    ```
+    """
+
+
+@dataclass(frozen=True, kw_only=True)
+class Structured(ZDType[np.dtypes.VoidDType[int], np.void], HasItemSize):
+    """
+    A Zarr data type for arrays containing structured scalars, AKA "record arrays".
+
+    Wraps the NumPy `np.dtypes.VoidDType` if the data type has fields. Scalars for this data
+    type are instances of `np.void`, with a ``fields`` attribute.
+
+    Attributes
+    ----------
+    fields : Sequence[tuple[str, ZDType]]
+        The fields of the structured dtype.
+
+    References
+    ----------
+    This data type does not have a Zarr V3 specification.
+
+    The Zarr V2 data type specification can be found [here](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+    """
+
+    _zarr_v3_name: ClassVar[Literal["structured"]] = "structured"
+    dtype_cls = np.dtypes.VoidDType  # type: ignore[assignment]
+    fields: tuple[tuple[str, ZDType[TBaseDType, TBaseScalar]], ...]
+
+    def __post_init__(self) -> None:
+        if len(self.fields) < 1:
+            raise ValueError(f"must have at least one field. Got {self.fields!r}")
+
+    @classmethod
+    def _check_native_dtype(cls, dtype: TBaseDType) -> TypeGuard[np.dtypes.VoidDType[int]]:
+        """
+        Check that this dtype is a numpy structured dtype
+
+        Parameters
+        ----------
+        dtype : np.dtypes.DTypeLike
+            The dtype to check.
+
+        Returns
+        -------
+        TypeGuard[np.dtypes.VoidDType]
+            True if the dtype matches, False otherwise.
+        """
+        return isinstance(dtype, cls.dtype_cls) and dtype.fields is not None
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create a Structured ZDType from a native NumPy data type.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The native data type.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input data type is not an instance of np.dtypes.VoidDType with a non-null
+            ``fields`` attribute.
+
+        Notes
+        -----
+        This method attempts to resolve the fields of the structured dtype using the data type
+        registry.
+        """
+        from zarr.core.dtype import get_data_type_from_native_dtype
+
+        fields: list[tuple[str, ZDType[TBaseDType, TBaseScalar]]] = []
+        if cls._check_native_dtype(dtype):
+            # fields of a structured numpy dtype are either 2-tuples or 3-tuples. we only
+            # care about the first element in either case.
+            for key, (dtype_instance, *_) in dtype.fields.items():  # type: ignore[union-attr]
+                dtype_wrapped = get_data_type_from_native_dtype(dtype_instance)
+                fields.append((key, dtype_wrapped))
+
+            return cls(fields=tuple(fields))
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> np.dtypes.VoidDType[int]:
+        """
+        Convert the structured Zarr data type to a native NumPy void dtype.
+
+        This method constructs a NumPy dtype with fields corresponding to the
+        fields of the structured Zarr data type, by converting each field's
+        data type to its native dtype representation.
+
+        Returns
+        -------
+        np.dtypes.VoidDType[int]
+            The native NumPy void dtype representing the structured data type.
+        """
+
+        return cast(
+            "np.dtypes.VoidDType[int]",
+            np.dtype([(key, dtype.to_native_dtype()) for (key, dtype) in self.fields]),
+        )
+
+    @classmethod
+    def _check_json_v2(
+        cls,
+        data: DTypeJSON,
+    ) -> TypeGuard[StructuredJSON_V2]:
+        """
+        Check if the input is a valid JSON representation of a Structured data type
+        for Zarr V2.
+
+        The input data must be a mapping that contains a "name" key that is not a str,
+        and an "object_codec_id" key that is None.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[StructuredJSON_V2]
+            True if the input is a valid JSON representation of a Structured data type
+            for Zarr V2, False otherwise.
+        """
+        return (
+            check_dtype_spec_v2(data)
+            and not isinstance(data["name"], str)
+            and check_structured_dtype_name_v2(data["name"])
+            and data["object_codec_id"] is None
+        )
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[StructuredJSON_V3]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[StructuredJSON_V3]
+            True if the input is a valid JSON representation of a structured data type for Zarr V3,
+            False otherwise.
+        """
+
+        return (
+            isinstance(data, dict)
+            and set(data.keys()) == {"name", "configuration"}
+            and data["name"] == cls._zarr_v3_name
+            and isinstance(data["configuration"], dict)
+            and set(data["configuration"].keys()) == {"fields"}
+        )
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        # avoid circular import
+        from zarr.core.dtype import get_data_type_from_json
+
+        if cls._check_json_v2(data):
+            # structured dtypes are constructed directly from a list of lists
+            # note that we do not handle the object codec here! this will prevent structured
+            # dtypes from containing object dtypes.
+            return cls(
+                fields=tuple(  # type: ignore[misc]
+                    (  # type: ignore[misc]
+                        f_name,
+                        get_data_type_from_json(
+                            {"name": f_dtype, "object_codec_id": None}, zarr_format=2
+                        ),
+                    )
+                    for f_name, f_dtype in data["name"]
+                )
+            )
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a JSON array of arrays"
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        # avoid circular import
+        from zarr.core.dtype import get_data_type_from_json
+
+        if cls._check_json_v3(data):
+            config = data["configuration"]
+            meta_fields = config["fields"]
+            return cls(
+                fields=tuple(
+                    (f_name, get_data_type_from_json(f_dtype, zarr_format=3))  # type: ignore[misc]
+                    for f_name, f_dtype in meta_fields
+                )
+            )
+        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a JSON object with the key {cls._zarr_v3_name!r}"
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> StructuredJSON_V2: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> StructuredJSON_V3: ...
+
+    def to_json(self, zarr_format: ZarrFormat) -> StructuredJSON_V2 | StructuredJSON_V3:
+        """
+        Convert the structured data type to a JSON-serializable form.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version. Accepted values are 2 and 3.
+
+        Returns
+        -------
+        StructuredJSON_V2 | StructuredJSON_V3
+            The JSON representation of the structured data type.
+
+        Raises
+        ------
+        ValueError
+            If the zarr_format is not 2 or 3.
+        """
+        if zarr_format == 2:
+            fields = [
+                [f_name, f_dtype.to_json(zarr_format=zarr_format)["name"]]
+                for f_name, f_dtype in self.fields
+            ]
+            return {"name": fields, "object_codec_id": None}
+        elif zarr_format == 3:
+            v3_unstable_dtype_warning(self)
+            fields = [
+                [f_name, f_dtype.to_json(zarr_format=zarr_format)]  # type: ignore[list-item]
+                for f_name, f_dtype in self.fields
+            ]
+            base_dict = {
+                "name": self._zarr_v3_name,
+                "configuration": {"fields": fields},
+            }
+            return cast("StructuredJSON_V3", base_dict)
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def _check_scalar(self, data: object) -> TypeGuard[StructuredScalarLike]:
+        # TODO: implement something more precise here!
+        """
+        Check that the input is a valid scalar value for this structured data type.
+
+        Parameters
+        ----------
+        data : object
+            The scalar value to check.
+
+        Returns
+        -------
+        TypeGuard[StructuredScalarLike]
+            Whether the input is a valid scalar value for this structured data type.
+        """
+        return isinstance(data, (bytes, list, tuple, int, np.void))
+
+    def _cast_scalar_unchecked(self, data: StructuredScalarLike) -> np.void:
+        """
+        Cast a python object to a numpy structured scalar without type checking.
+
+        Parameters
+        ----------
+        data : StructuredScalarLike
+            The data to cast.
+
+        Returns
+        -------
+        np.void
+            The casted data as a numpy structured scalar.
+
+        Notes
+        -----
+        This method does not perform any type checking.
+        The input data must be castable to a numpy structured scalar.
+
+        """
+        na_dtype = self.to_native_dtype()
+        if isinstance(data, bytes):
+            res = np.frombuffer(data, dtype=na_dtype)[0]
+        elif isinstance(data, list | tuple):
+            res = np.array([tuple(data)], dtype=na_dtype)[0]
+        else:
+            res = np.array([data], dtype=na_dtype)[0]
+        return cast("np.void", res)
+
+    def cast_scalar(self, data: object) -> np.void:
+        """
+        Cast a Python object to a NumPy structured scalar.
+
+        This function attempts to cast the provided data to a NumPy structured scalar.
+        If the data is compatible with the structured scalar type, it is cast without
+        type checking. Otherwise, a TypeError is raised.
+
+        Parameters
+        ----------
+        data : object
+            The data to be cast to a NumPy structured scalar.
+
+        Returns
+        -------
+        np.void
+            The data cast as a NumPy structured scalar.
+
+        Raises
+        ------
+        TypeError
+            If the data cannot be converted to a NumPy structured scalar.
+        """
+
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        msg = (
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)
+
+    def default_scalar(self) -> np.void:
+        """
+        Get the default scalar value for this structured data type.
+
+        Returns
+        -------
+        np.void
+            The default scalar value, which is the scalar representation of 0
+            cast to this structured data type.
+        """
+
+        return self._cast_scalar_unchecked(0)
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.void:
+        """
+        Read a JSON-serializable value as a NumPy structured scalar.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON-serializable value.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        np.void
+            The NumPy structured scalar.
+
+        Raises
+        ------
+        TypeError
+            If the input is not a base64-encoded string.
+        """
+        if check_json_str(data):
+            as_bytes = bytes_from_json(data, zarr_format=zarr_format)
+            dtype = self.to_native_dtype()
+            return cast("np.void", np.array([as_bytes]).view(dtype)[0])
+        raise TypeError(f"Invalid type: {data}. Expected a string.")
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
+        """
+        Convert a scalar to a JSON-serializable string representation.
+
+        Parameters
+        ----------
+        data : object
+            The scalar to convert.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        str
+            A string representation of the scalar, which is a base64-encoded
+            string of the bytes that make up the scalar.
+        """
+        return bytes_to_json(self.cast_scalar(data).tobytes(), zarr_format)
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return self.to_native_dtype().itemsize

.venv/lib/python3.11/site-packages/zarr/core/dtype/npy/time.py

@@ -0,0 +1,885 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Literal,
+    Self,
+    TypedDict,
+    TypeGuard,
+    TypeVar,
+    cast,
+    get_args,
+    overload,
+)
+
+import numpy as np
+from typing_extensions import ReadOnly
+
+from zarr.core.common import NamedConfig
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    DTypeConfig_V2,
+    DTypeJSON,
+    HasEndianness,
+    HasItemSize,
+    check_dtype_spec_v2,
+)
+from zarr.core.dtype.npy.common import (
+    DATETIME_UNIT,
+    DateTimeUnit,
+    check_json_int,
+    endianness_to_numpy_str,
+    get_endianness_from_numpy_dtype,
+)
+from zarr.core.dtype.wrapper import TBaseDType, ZDType
+
+if TYPE_CHECKING:
+    from zarr.core.common import JSON, ZarrFormat
+
+TimeDeltaLike = str | int | bytes | np.timedelta64 | timedelta | None
+DateTimeLike = str | int | bytes | np.datetime64 | datetime | None
+
+
+def datetime_from_int(data: int, *, unit: DateTimeUnit, scale_factor: int) -> np.datetime64:
+    """
+    Convert an integer to a datetime64.
+
+    Parameters
+    ----------
+    data : int
+        The integer to convert.
+    unit : DateTimeUnit
+        The unit of the datetime64.
+    scale_factor : int
+        The scale factor of the datetime64.
+
+    Returns
+    -------
+    numpy.datetime64
+        The datetime64 value.
+    """
+    dtype_name = f"datetime64[{scale_factor}{unit}]"
+    return cast("np.datetime64", np.int64(data).view(dtype_name))
+
+
+def datetimelike_to_int(data: np.datetime64 | np.timedelta64) -> int:
+    """
+    Convert a datetime64 or a timedelta64 to an integer.
+
+    Parameters
+    ----------
+    data : np.datetime64 | numpy.timedelta64
+        The value to convert.
+
+    Returns
+    -------
+    int
+        An integer representation of the scalar.
+    """
+    return data.view(np.int64).item()
+
+
+def check_json_time(data: JSON) -> TypeGuard[Literal["NaT"] | int]:
+    """
+    Type guard to check if the input JSON data is the literal string "NaT"
+    or an integer.
+    """
+    return check_json_int(data) or data == "NaT"
+
+
+BaseTimeDType_co = TypeVar(
+    "BaseTimeDType_co",
+    bound=np.dtypes.TimeDelta64DType | np.dtypes.DateTime64DType,
+    covariant=True,
+)
+BaseTimeScalar_co = TypeVar(
+    "BaseTimeScalar_co", bound=np.timedelta64 | np.datetime64, covariant=True
+)
+
+
+class TimeConfig(TypedDict):
+    """
+    The configuration for the numpy.timedelta64 or numpy.datetime64 data type in Zarr V3.
+
+    Attributes
+    ----------
+    unit : ReadOnly[DateTimeUnit]
+        A string encoding a unit of time.
+    scale_factor : ReadOnly[int]
+        A scale factor.
+
+    Examples
+    --------
+    ```python
+    {"unit": "ms", "scale_factor": 1}
+    ```
+    """
+
+    unit: ReadOnly[DateTimeUnit]
+    scale_factor: ReadOnly[int]
+
+
+class DateTime64JSON_V3(NamedConfig[Literal["numpy.datetime64"], TimeConfig]):
+    """
+    The JSON representation of the ``numpy.datetime64`` data type in Zarr V3.
+
+    References
+    ----------
+    This representation is defined in the ``numpy.datetime64``
+    [specification document](https://zarr-specs.readthedocs.io/en/latest/spec/v3/datatypes.html#numpy-datetime64).
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "numpy.datetime64",
+        "configuration": {
+            "unit": "ms",
+            "scale_factor": 1
+            }
+    }
+    ```
+    """
+
+
+class TimeDelta64JSON_V3(NamedConfig[Literal["numpy.timedelta64"], TimeConfig]):
+    """
+    The JSON representation of the ``TimeDelta64`` data type in Zarr V3.
+
+    References
+    ----------
+    This representation is defined in the numpy.timedelta64
+    [specification document](https://zarr-specs.readthedocs.io/en/latest/spec/v3/datatypes.html#numpy-timedelta64).
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "numpy.timedelta64",
+        "configuration": {
+            "unit": "ms",
+            "scale_factor": 1
+            }
+    }
+    ```
+    """
+
+
+class TimeDelta64JSON_V2(DTypeConfig_V2[str, None]):
+    """
+    A wrapper around the JSON representation of the ``TimeDelta64`` data type in Zarr V2.
+
+    The ``name`` field of this class contains the value that would appear under the
+    ``dtype`` field in Zarr V2 array metadata.
+
+    References
+    ----------
+    The structure of the ``name`` field is defined in the Zarr V2
+    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "<m8[1s]",
+        "object_codec_id": None
+    }
+    ```
+    """
+
+
+class DateTime64JSON_V2(DTypeConfig_V2[str, None]):
+    """
+    A wrapper around the JSON representation of the ``DateTime64`` data type in Zarr V2.
+
+    The ``name`` field of this class contains the value that would appear under the
+    ``dtype`` field in Zarr V2 array metadata.
+
+    References
+    ----------
+    The structure of the ``name`` field is defined in the Zarr V2
+    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+
+
+    Examples
+    --------
+    ```python
+    {
+        "name": "<M8[10s]",
+        "object_codec_id": None
+    }
+    ```
+    """
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class TimeDTypeBase(ZDType[BaseTimeDType_co, BaseTimeScalar_co], HasEndianness, HasItemSize):
+    """
+    A base class for data types that represent time via the NumPy TimeDelta64 and DateTime64 data
+    types.
+
+    Attributes
+    ----------
+    scale_factor : int
+        The scale factor for the time unit.
+    unit : str
+        The unit of time.
+    """
+
+    _numpy_name: ClassVar[Literal["datetime64", "timedelta64"]]
+    scale_factor: int
+    unit: DateTimeUnit
+
+    def __post_init__(self) -> None:
+        if self.scale_factor < 1:
+            raise ValueError(f"scale_factor must be > 0, got {self.scale_factor}.")
+        if self.scale_factor >= 2**31:
+            raise ValueError(f"scale_factor must be < 2147483648, got {self.scale_factor}.")
+        if self.unit not in get_args(DateTimeUnit):
+            raise ValueError(f"unit must be one of {get_args(DateTimeUnit)}, got {self.unit!r}.")
+
+    @classmethod
+    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
+        """
+        Create an instance of this class from a native NumPy data type.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The native NumPy dtype to convert.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the dtype is not a valid representation of this class.
+        """
+
+        if cls._check_native_dtype(dtype):
+            unit, scale_factor = np.datetime_data(dtype.name)
+            unit = cast("DateTimeUnit", unit)
+            return cls(
+                unit=unit,
+                scale_factor=scale_factor,
+                endianness=get_endianness_from_numpy_dtype(dtype),
+            )
+        raise DataTypeValidationError(
+            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
+        )
+
+    def to_native_dtype(self) -> BaseTimeDType_co:
+        # Numpy does not allow creating datetime64 or timedelta64 via
+        # np.dtypes.{dtype_name}()
+        # so we use np.dtype with a formatted string.
+        """
+        Convert this data type to a NumPy temporal data type with the appropriate
+        unit and scale factor.
+
+        Returns
+        -------
+        BaseTimeDType_co
+            A NumPy data type object representing the time data type with
+            the specified unit, scale factor, and byte order.
+        """
+
+        dtype_string = f"{self._numpy_name}[{self.scale_factor}{self.unit}]"
+        return np.dtype(dtype_string).newbyteorder(endianness_to_numpy_str(self.endianness))  # type: ignore[return-value]
+
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
+        """
+        Convert a python object to a JSON representation of a datetime64 or timedelta64 scalar.
+
+        Parameters
+        ----------
+        data : object
+            The python object to convert.
+        zarr_format : ZarrFormat
+            The Zarr format version (2 or 3).
+
+        Returns
+        -------
+        int
+            The JSON representation of the scalar.
+        """
+        return datetimelike_to_int(data)  # type: ignore[arg-type]
+
+    @property
+    def item_size(self) -> int:
+        """
+        The size of a single scalar in bytes.
+
+        Returns
+        -------
+        int
+            The size of a single scalar in bytes.
+        """
+        return 8
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class TimeDelta64(TimeDTypeBase[np.dtypes.TimeDelta64DType, np.timedelta64], HasEndianness):
+    """
+    A Zarr data type for arrays containing NumPy TimeDelta64 data.
+
+    Wraps the ``np.dtypesTimeDelta64DType`` data type. Scalars for this data type
+    are instances of `np.timedelta64`.
+
+    Attributes
+    ----------
+    dtype_cls : Type[np.dtypesTimeDelta64DType]
+        The NumPy dtype class for this data type.
+    scale_factor : int
+        The scale factor for this data type.
+    unit : DateTimeUnit
+        The unit for this data type.
+
+    References
+    ----------
+    The Zarr V2 representation of this data type is defined in the Zarr V2
+    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+
+    The Zarr V3 representation of this data type is defined in the ``numpy.timedelta64``
+    [specification document](https://github.com/zarr-developers/zarr-extensions/tree/main/data-types/numpy.timedelta64)
+    """
+
+    # mypy infers the type of np.dtypes.TimeDelta64DType to be
+    # "Callable[[Literal['Y', 'M', 'W', 'D'] | Literal['h', 'm', 's', 'ms', 'us', 'ns', 'ps', 'fs', 'as']], Never]"
+    dtype_cls = np.dtypes.TimeDelta64DType  # type: ignore[assignment]
+    unit: DateTimeUnit = "generic"
+    scale_factor: int = 1
+    _zarr_v3_name: ClassVar[Literal["numpy.timedelta64"]] = "numpy.timedelta64"
+    _zarr_v2_names: ClassVar[tuple[Literal[">m8"], Literal["<m8"]]] = (">m8", "<m8")
+    _numpy_name: ClassVar[Literal["timedelta64"]] = "timedelta64"
+
+    @classmethod
+    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[TimeDelta64JSON_V2]:
+        """
+        Validate that the provided JSON input accurately represents a NumPy timedelta64 data type,
+        which could be in the form of strings like "<m8" or ">m8[10s]". This method serves as a type
+        guard, helping to refine the type of unknown JSON input by confirming its adherence to the
+        expected format for NumPy timedelta64 data types.
+
+        The JSON input should contain a "name" key with a value that matches the expected string
+        pattern for NumPy timedelta64 data types. The pattern includes an optional unit enclosed
+        within square brackets, following the base type identifier.
+
+        Returns
+        -------
+        bool
+            True if the JSON input is a valid representation of this class,
+            otherwise False.
+        """
+        if not check_dtype_spec_v2(data):
+            return False
+        name = data["name"]
+        # match <m[ns], >m[M], etc
+        # consider making this a standalone function
+        if not isinstance(name, str):
+            return False
+        if not name.startswith(cls._zarr_v2_names):
+            return False
+        if len(name) == 3:
+            # no unit, and
+            # we already checked that this string is either <m8 or >m8
+            return True
+        else:
+            return name[4:-1].endswith(DATETIME_UNIT) and name[-1] == "]"
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[DateTime64JSON_V3]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Returns
+        -------
+        TypeGuard[DateTime64JSON_V3]
+            True if the JSON input is a valid representation of this class,
+            otherwise False.
+        """
+        return (
+            isinstance(data, dict)
+            and set(data.keys()) == {"name", "configuration"}
+            and data["name"] == cls._zarr_v3_name
+            and isinstance(data["configuration"], dict)
+            and set(data["configuration"].keys()) == {"unit", "scale_factor"}
+        )
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create a TimeDelta64 from a Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        TimeDelta64
+            An instance of TimeDelta64.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v2(data):
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        msg = (
+            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a string "
+            f"representation of an instance of {cls.dtype_cls}"
+        )
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create a TimeDelta64 from a Zarr V3-flavored JSON.
+
+        The JSON representation of a TimeDelta64 in Zarr V3 is a dict with a 'name' key
+        with the value 'numpy.timedelta64', and a 'configuration' key with a value of a dict
+        with a 'unit' key and a 'scale_factor' key.
+
+        For example:
+
+        ```json
+        {
+            "name": "numpy.timedelta64",
+            "configuration": {
+                "unit": "generic",
+                "scale_factor": 1
+            }
+        }
+        ```
+
+        """
+        if cls._check_json_v3(data):
+            unit = data["configuration"]["unit"]
+            scale_factor = data["configuration"]["scale_factor"]
+            return cls(unit=unit, scale_factor=scale_factor)
+        msg = (
+            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a dict "
+            f"with a 'name' key with the value 'numpy.timedelta64', "
+            "and a 'configuration' key with a value of a dict with a 'unit' key and a "
+            "'scale_factor' key"
+        )
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> TimeDelta64JSON_V2: ...
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> TimeDelta64JSON_V3: ...
+
+    def to_json(self, zarr_format: ZarrFormat) -> TimeDelta64JSON_V2 | TimeDelta64JSON_V3:
+        """
+        Serialize this data type to JSON.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version (2 or 3).
+
+        Returns
+        -------
+        TimeDelta64JSON_V2 | TimeDelta64JSON_V3
+            The JSON representation of the data type.
+
+        Raises
+        ------
+        ValueError
+            If the zarr_format is not 2 or 3.
+        """
+        if zarr_format == 2:
+            name = self.to_native_dtype().str
+            return {"name": name, "object_codec_id": None}
+        elif zarr_format == 3:
+            return {
+                "name": self._zarr_v3_name,
+                "configuration": {"unit": self.unit, "scale_factor": self.scale_factor},
+            }
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def _check_scalar(self, data: object) -> TypeGuard[TimeDeltaLike]:
+        """
+        Check if the input is a scalar of this data type.
+
+        Parameters
+        ----------
+        data : object
+            The object to check.
+
+        Returns
+        -------
+        TypeGuard[TimeDeltaLike]
+            True if the input is a scalar of this data type, False otherwise.
+        """
+        if data is None:
+            return True
+        return isinstance(data, str | int | bytes | np.timedelta64 | timedelta)
+
+    def _cast_scalar_unchecked(self, data: TimeDeltaLike) -> np.timedelta64:
+        """
+        Cast the provided scalar input to a numpy timedelta64 without any type checking.
+
+        This method assumes that the input data is already a valid scalar of this data type,
+        and does not perform any validation or type checks. It directly casts the input
+        to a numpy timedelta64 scalar using the unit and scale factor defined in the class.
+
+        Parameters
+        ----------
+        data : TimeDeltaLike
+            The scalar input data to cast.
+
+        Returns
+        -------
+        numpy.timedelta64
+            The input data cast as a numpy timedelta64 scalar.
+        """
+        return self.to_native_dtype().type(data, f"{self.scale_factor}{self.unit}")
+
+    def cast_scalar(self, data: object) -> np.timedelta64:
+        """
+        Cast the input to a numpy timedelta64 scalar. If the input is not a scalar of this data type,
+        raise a TypeError.
+        """
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        msg = (
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)
+
+    def default_scalar(self) -> np.timedelta64:
+        """
+        Return a default scalar of this data type.
+
+        This method provides a default value for the timedelta64 scalar, which is
+        a 'Not-a-Time' (NaT) value.
+        """
+        return np.timedelta64("NaT")
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.timedelta64:
+        """
+        Create a scalar of this data type from JSON input.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON representation of the scalar value.
+        zarr_format : int
+            The zarr format to use for the JSON representation.
+
+        Returns
+        -------
+        numpy.timedelta64
+            The scalar value of this data type.
+
+        Raises
+        ------
+        TypeError
+            If the input JSON is not a valid representation of a scalar for this data type.
+        """
+        if check_json_time(data):
+            return self.to_native_dtype().type(data, f"{self.scale_factor}{self.unit}")
+        raise TypeError(f"Invalid type: {data}. Expected an integer.")  # pragma: no cover
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class DateTime64(TimeDTypeBase[np.dtypes.DateTime64DType, np.datetime64], HasEndianness):
+    """
+    A Zarr data type for arrays containing NumPy Datetime64 data.
+
+    Wraps the ``np.dtypes.TimeDelta64DType`` data type. Scalars for this data type
+    are instances of ``np.datetime64``.
+
+    Attributes
+    ----------
+    dtype_cls : Type[np.dtypesTimeDelta64DType]
+        The numpy dtype class for this data type.
+    unit : DateTimeUnit
+        The unit of time for this data type.
+    scale_factor : int
+        The scale factor for the time unit.
+
+    References
+    ----------
+    The Zarr V2 representation of this data type is defined in the Zarr V2
+    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
+
+    The Zarr V3 representation of this data type is defined in the ``numpy.datetime64``
+    [specification document](https://github.com/zarr-developers/zarr-extensions/tree/main/data-types/numpy.datetime64)
+    """
+
+    dtype_cls = np.dtypes.DateTime64DType  # type: ignore[assignment]
+    _zarr_v3_name: ClassVar[Literal["numpy.datetime64"]] = "numpy.datetime64"
+    _zarr_v2_names: ClassVar[tuple[Literal[">M8"], Literal["<M8"]]] = (">M8", "<M8")
+    _numpy_name: ClassVar[Literal["datetime64"]] = "datetime64"
+    unit: DateTimeUnit = "generic"
+    scale_factor: int = 1
+
+    @classmethod
+    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[DateTime64JSON_V2]:
+        """
+        Check that the input is a valid JSON representation of this data type.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[DateTime64JSON_V2]
+            True if the input is a valid JSON representation of a NumPy datetime64 data type,
+            otherwise False.
+        """
+        if not check_dtype_spec_v2(data):
+            return False
+        name = data["name"]
+        if not isinstance(name, str):
+            return False
+        if not name.startswith(cls._zarr_v2_names):
+            return False
+        if len(name) == 3:
+            # no unit, and
+            # we already checked that this string is either <M8 or >M8
+            return True
+        else:
+            return name[4:-1].endswith(DATETIME_UNIT) and name[-1] == "]"
+
+    @classmethod
+    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[DateTime64JSON_V3]:
+        """
+        Check that the input is a valid JSON representation of this class in Zarr V3.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        TypeGuard[DateTime64JSON_V3]
+            True if the input is a valid JSON representation of a numpy datetime64 data type in Zarr V3, False otherwise.
+        """
+
+        return (
+            isinstance(data, dict)
+            and set(data.keys()) == {"name", "configuration"}
+            and data["name"] == cls._zarr_v3_name
+            and isinstance(data["configuration"], dict)
+            and set(data["configuration"].keys()) == {"unit", "scale_factor"}
+        )
+
+    @classmethod
+    def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from a Zarr V2-flavored JSON representation.
+
+        This method checks if the provided JSON data is a valid representation of this class.
+        If valid, it creates an instance using the native NumPy dtype. Otherwise, it raises a
+        DataTypeValidationError.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to parse.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+
+        if cls._check_json_v2(data):
+            name = data["name"]
+            return cls.from_native_dtype(np.dtype(name))
+        msg = (
+            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a string "
+            f"representation of an instance of {cls.dtype_cls}"
+        )
+        raise DataTypeValidationError(msg)
+
+    @classmethod
+    def _from_json_v3(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of this data type from a Zarr V3-flavored JSON representation.
+
+        This method checks if the provided JSON data is a valid representation of this class.
+        If valid, it creates an instance using the native NumPy dtype. Otherwise, it raises a
+        DataTypeValidationError.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to parse.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of this class.
+        """
+        if cls._check_json_v3(data):
+            unit = data["configuration"]["unit"]
+            scale_factor = data["configuration"]["scale_factor"]
+            return cls(unit=unit, scale_factor=scale_factor)
+        msg = (
+            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a dict "
+            f"with a 'name' key with the value 'numpy.datetime64', "
+            "and a 'configuration' key with a value of a dict with a 'unit' key and a "
+            "'scale_factor' key"
+        )
+        raise DataTypeValidationError(msg)
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DateTime64JSON_V2: ...
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> DateTime64JSON_V3: ...
+
+    def to_json(self, zarr_format: ZarrFormat) -> DateTime64JSON_V2 | DateTime64JSON_V3:
+        """
+        Serialize this data type to JSON.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version (2 or 3).
+
+        Returns
+        -------
+        DateTime64JSON_V2 | DateTime64JSON_V3
+            The JSON representation of the data type.
+
+        Raises
+        ------
+        ValueError
+            If the zarr_format is not 2 or 3.
+        """
+        if zarr_format == 2:
+            name = self.to_native_dtype().str
+            return {"name": name, "object_codec_id": None}
+        elif zarr_format == 3:
+            return {
+                "name": self._zarr_v3_name,
+                "configuration": {"unit": self.unit, "scale_factor": self.scale_factor},
+            }
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    def _check_scalar(self, data: object) -> TypeGuard[DateTimeLike]:
+        """
+        Check if the input is convertible to a scalar of this data type.
+
+        Parameters
+        ----------
+        data : object
+            The object to check.
+
+        Returns
+        -------
+        TypeGuard[DateTimeLike]
+            True if the input is a scalar of this data type, False otherwise.
+        """
+        if data is None:
+            return True
+        return isinstance(data, str | int | bytes | np.datetime64 | datetime)
+
+    def _cast_scalar_unchecked(self, data: DateTimeLike) -> np.datetime64:
+        """
+        Cast the input to a scalar of this data type without any type checking.
+
+        Parameters
+        ----------
+        data : DateTimeLike
+            The scalar data to cast.
+
+        Returns
+        -------
+        numpy.datetime64
+            The input cast to a NumPy datetime scalar.
+        """
+        return self.to_native_dtype().type(data, f"{self.scale_factor}{self.unit}")
+
+    def cast_scalar(self, data: object) -> np.datetime64:
+        """
+        Cast the input to a scalar of this data type after a type check.
+
+        Parameters
+        ----------
+        data : object
+            The scalar value to cast.
+
+        Returns
+        -------
+        numpy.datetime64
+            The input cast to a NumPy datetime scalar.
+
+        Raises
+        ------
+        TypeError
+            If the data cannot be converted to a numpy datetime scalar.
+        """
+        if self._check_scalar(data):
+            return self._cast_scalar_unchecked(data)
+        msg = (
+            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
+            f"data type {self}."
+        )
+        raise TypeError(msg)
+
+    def default_scalar(self) -> np.datetime64:
+        """
+        Return the default scalar value for this data type.
+
+        Returns
+        -------
+        numpy.datetime64
+            The default scalar value, which is a 'Not-a-Time' (NaT) value
+        """
+
+        return np.datetime64("NaT")
+
+    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.datetime64:
+        """
+        Read a JSON-serializable value as a scalar.
+
+        Parameters
+        ----------
+        data : JSON
+            The JSON-serializable value.
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        numpy.datetime64
+            The numpy datetime scalar.
+
+        Raises
+        ------
+        TypeError
+            If the input is not a valid integer type.
+        """
+        if check_json_time(data):
+            return self._cast_scalar_unchecked(data)
+        raise TypeError(f"Invalid type: {data}. Expected an integer.")  # pragma: no cover

.venv/lib/python3.11/site-packages/zarr/core/dtype/registry.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Self
+
+import numpy as np
+
+from zarr.core.dtype.common import (
+    DataTypeValidationError,
+    DTypeJSON,
+)
+
+if TYPE_CHECKING:
+    from importlib.metadata import EntryPoint
+
+    from zarr.core.common import ZarrFormat
+    from zarr.core.dtype.wrapper import TBaseDType, TBaseScalar, ZDType
+
+
+# This class is different from the other registry classes, which inherit from
+# dict. IMO it's simpler to just do a dataclass. But long-term we should
+# have just 1 registry class in use.
+@dataclass(frozen=True, kw_only=True)
+class DataTypeRegistry:
+    """
+    A registry for ZDType classes.
+
+    This registry is a mapping from Zarr data type names to their
+    corresponding ZDType classes.
+
+    Attributes
+    ----------
+    contents : dict[str, type[ZDType[TBaseDType, TBaseScalar]]]
+        The mapping from Zarr data type names to their corresponding
+        ZDType classes.
+    """
+
+    contents: dict[str, type[ZDType[TBaseDType, TBaseScalar]]] = field(
+        default_factory=dict, init=False
+    )
+
+    _lazy_load_list: list[EntryPoint] = field(default_factory=list, init=False)
+
+    def _lazy_load(self) -> None:
+        """
+        Load all data types from the lazy load list and register them with
+        the registry. After loading, clear the lazy load list.
+        """
+        for e in self._lazy_load_list:
+            self.register(e.load()._zarr_v3_name, e.load())
+
+        self._lazy_load_list.clear()
+
+    def register(self: Self, key: str, cls: type[ZDType[TBaseDType, TBaseScalar]]) -> None:
+        """
+        Register a data type with the registry.
+
+        Parameters
+        ----------
+        key : str
+            The Zarr V3 name of the data type.
+        cls : type[ZDType[TBaseDType, TBaseScalar]]
+            The class of the data type to register.
+
+        Notes
+        -----
+        This method is idempotent. If the data type is already registered, this
+        method does nothing.
+        """
+        if key not in self.contents or self.contents[key] != cls:
+            self.contents[key] = cls
+
+    def unregister(self, key: str) -> None:
+        """
+        Unregister a data type from the registry.
+
+        Parameters
+        ----------
+        key : str
+            The key associated with the ZDType class to be unregistered.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        KeyError
+            If the data type is not found in the registry.
+        """
+        if key in self.contents:
+            del self.contents[key]
+        else:
+            raise KeyError(f"Data type '{key}' not found in registry.")
+
+    def get(self, key: str) -> type[ZDType[TBaseDType, TBaseScalar]]:
+        """
+        Retrieve a registered ZDType class by its key.
+
+        Parameters
+        ----------
+        key : str
+            The key associated with the desired ZDType class.
+
+        Returns
+        -------
+        type[ZDType[TBaseDType, TBaseScalar]]
+            The ZDType class registered under the given key.
+
+        Raises
+        ------
+        KeyError
+            If the key is not found in the registry.
+        """
+
+        return self.contents[key]
+
+    def match_dtype(self, dtype: TBaseDType) -> ZDType[TBaseDType, TBaseScalar]:
+        """
+        Match a native data type, e.g. a NumPy data type, to a registered ZDType.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The native data type to match.
+
+        Returns
+        -------
+        ZDType[TBaseDType, TBaseScalar]
+            The matched ZDType corresponding to the provided NumPy data type.
+
+        Raises
+        ------
+        ValueError
+            If the data type is a NumPy "Object" type, which is ambiguous, or if multiple
+            or no Zarr data types are found that match the provided dtype.
+
+        Notes
+        -----
+        This function attempts to resolve a Zarr data type from a given native data type.
+        If the dtype is a NumPy "Object" data type, it raises a ValueError, as this type
+        can represent multiple Zarr data types. In such cases, a specific Zarr data type
+        should be explicitly constructed instead of relying on dynamic resolution.
+
+        If multiple matches are found, it will also raise a ValueError. In this case
+        conflicting data types must be unregistered, or the Zarr data type should be explicitly
+        constructed.
+        """
+
+        if dtype == np.dtype("O"):
+            msg = (
+                f"Zarr data type resolution from {dtype} failed. "
+                'Attempted to resolve a zarr data type from a numpy "Object" data type, which is '
+                'ambiguous, as multiple zarr data types can be represented by the numpy "Object" '
+                "data type. "
+                "In this case you should construct your array by providing a specific Zarr data "
+                'type. For a list of Zarr data types that are compatible with the numpy "Object"'
+                "data type, see https://github.com/zarr-developers/zarr-python/issues/3117"
+            )
+            raise ValueError(msg)
+        matched: list[ZDType[TBaseDType, TBaseScalar]] = []
+        for val in self.contents.values():
+            # DataTypeValidationError means "this dtype doesn't match me", which is
+            # expected and suppressed. Other exceptions (e.g. ValueError for a dtype
+            # that matches the type but has an invalid configuration) are propagated
+            # to the caller.
+            with contextlib.suppress(DataTypeValidationError):
+                matched.append(val.from_native_dtype(dtype))
+        if len(matched) == 1:
+            return matched[0]
+        elif len(matched) > 1:
+            msg = (
+                f"Zarr data type resolution from {dtype} failed. "
+                f"Multiple data type wrappers found that match dtype '{dtype}': {matched}. "
+                "You should unregister one of these data types, or avoid Zarr data type inference "
+                "entirely by providing a specific Zarr data type when creating your array."
+                "For more information, see https://github.com/zarr-developers/zarr-python/issues/3117"
+            )
+            raise ValueError(msg)
+        raise ValueError(f"No Zarr data type found that matches dtype '{dtype!r}'")
+
+    def match_json(
+        self, data: DTypeJSON, *, zarr_format: ZarrFormat
+    ) -> ZDType[TBaseDType, TBaseScalar]:
+        """
+        Match a JSON representation of a data type to a registered ZDType.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON representation of a data type to match.
+        zarr_format : ZarrFormat
+            The Zarr format version to consider when matching data types.
+
+        Returns
+        -------
+        ZDType[TBaseDType, TBaseScalar]
+            The matched ZDType corresponding to the JSON representation.
+
+        Raises
+        ------
+        ValueError
+            If no matching Zarr data type is found for the given JSON data.
+        """
+
+        for val in self.contents.values():
+            try:
+                return val.from_json(data, zarr_format=zarr_format)
+            except DataTypeValidationError:
+                pass
+        raise ValueError(f"No Zarr data type found that matches {data!r}")

.venv/lib/python3.11/site-packages/zarr/core/dtype/wrapper.py

@@ -0,0 +1,300 @@
+"""
+Wrapper for native array data types.
+
+The ``ZDType`` class is an abstract base class for wrapping native array data types, e.g. NumPy dtypes.
+``ZDType`` provides a common interface for working with data types in a way that is independent of the
+underlying data type system.
+
+The wrapper class encapsulates a native data type. Instances of the class can be created from a
+native data type instance, and a native data type instance can be created from an instance of the
+wrapper class.
+
+The wrapper class is responsible for:
+- Serializing and deserializing a native data type to Zarr V2 or Zarr V3 metadata.
+  This ensures that the data type can be properly stored and retrieved from array metadata.
+- Serializing and deserializing scalar values to Zarr V2 or Zarr V3 metadata. This is important for
+  storing a fill value for an array in a manner that is valid for the data type.
+
+You can add support for a new data type in Zarr by subclassing ``ZDType`` wrapper class and adapt its methods
+to support your native data type. The wrapper class must be added to a data type registry
+(defined elsewhere) before array creation routines or array reading routines can use your new data
+type.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Generic,
+    Literal,
+    Self,
+    TypeGuard,
+    TypeVar,
+    overload,
+)
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from zarr.core.common import JSON, ZarrFormat
+    from zarr.core.dtype.common import DTypeJSON, DTypeSpec_V2, DTypeSpec_V3
+
+# This the upper bound for the scalar types we support. It's numpy scalars + str,
+# because the new variable-length string dtype in numpy does not have a corresponding scalar type
+TBaseScalar = np.generic | str | bytes
+# This is the bound for the dtypes that we support. If we support non-numpy dtypes,
+# then this bound will need to be widened.
+TBaseDType = np.dtype[np.generic]
+
+# These two type parameters are covariant because we want
+# x : ZDType[BaseDType, BaseScalar] = ZDType[SubDType, SubScalar]
+# to type check
+TScalar_co = TypeVar("TScalar_co", bound=TBaseScalar, covariant=True)
+TDType_co = TypeVar("TDType_co", bound=TBaseDType, covariant=True)
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class ZDType(ABC, Generic[TDType_co, TScalar_co]):
+    """
+    Abstract base class for wrapping native array data types, e.g. numpy dtypes
+
+    Attributes
+    ----------
+    dtype_cls : ClassVar[type[TDType]]
+        The wrapped dtype class. This is a class variable.
+    _zarr_v3_name : ClassVar[str]
+        The name given to the data type by a Zarr v3 data type specification. This is a
+        class variable, and it should generally be unique across different data types.
+    """
+
+    # this class will create a native data type
+    dtype_cls: ClassVar[type[TDType_co]]
+    _zarr_v3_name: ClassVar[str]
+
+    @classmethod
+    def _check_native_dtype(cls: type[Self], dtype: TBaseDType) -> TypeGuard[TDType_co]:
+        """
+        Check that a native data type matches the dtype_cls class attribute.
+
+        Used as a type guard.
+
+        Parameters
+        ----------
+        dtype : TDType
+            The dtype to check.
+
+        Returns
+        -------
+        Bool
+            True if the dtype matches, False otherwise.
+        """
+        return type(dtype) is cls.dtype_cls
+
+    @classmethod
+    @abstractmethod
+    def from_native_dtype(cls: type[Self], dtype: TBaseDType) -> Self:
+        """
+        Create a ZDType instance from a native data type.
+
+        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.
+
+        Parameters
+        ----------
+        dtype : TDType
+            The native data type object to wrap.
+
+        Returns
+        -------
+        Self
+            The ZDType that wraps the native data type.
+
+        Raises
+        ------
+        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:
+        """
+        Return an instance of the wrapped data type. This operation inverts ``from_native_dtype``.
+
+        Returns
+        -------
+        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:
+        raise NotImplementedError  # pragma: no cover
+
+    @classmethod
+    @abstractmethod
+    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:
+        """
+        Create an instance of this ZDType from JSON data.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON representation of the data type.
+
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        Self
+            An instance of this data type.
+        """
+        if zarr_format == 2:
+            return cls._from_json_v2(data)
+        if zarr_format == 3:
+            return cls._from_json_v3(data)
+        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
+
+    @overload
+    def to_json(self, zarr_format: Literal[2]) -> DTypeSpec_V2: ...
+
+    @overload
+    def to_json(self, zarr_format: Literal[3]) -> DTypeSpec_V3: ...
+
+    @abstractmethod
+    def to_json(self, zarr_format: ZarrFormat) -> DTypeSpec_V2 | DTypeSpec_V3:
+        """
+        Serialize this ZDType to JSON.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The zarr format version.
+
+        Returns
+        -------
+        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:
+        """
+        Check that a python object is a valid scalar value for the wrapped data type.
+
+        Parameters
+        ----------
+        data : object
+            A value to check.
+
+        Returns
+        -------
+        Bool
+            True if the object is valid, False otherwise.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    @abstractmethod
+    def cast_scalar(self, data: object) -> TScalar_co:
+        """
+        Cast a python object to the wrapped scalar type.
+
+        The type of the provided scalar is first checked for compatibility.
+        If it's incompatible with the associated scalar type, a ``TypeError`` will be raised.
+
+        Parameters
+        ----------
+        data : object
+            The python object to cast.
+
+        Returns
+        -------
+        TScalar
+            The cast value.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    @abstractmethod
+    def default_scalar(self) -> TScalar_co:
+        """
+        Get the default scalar value for the wrapped data type.
+
+        This is a method, rather than an attribute, because the default value for some data types depends on parameters that are
+        not known until a concrete data type is wrapped. For example, data types parametrized by a
+        length like fixed-length strings or bytes will generate scalars consistent with that length.
+
+        Returns
+        -------
+        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:
+        """
+        Read a JSON-serializable value as a scalar.
+
+        Parameters
+        ----------
+        data : JSON
+            A JSON representation of a scalar value.
+        zarr_format : ZarrFormat
+            The zarr format version. This is specified because the JSON serialization of scalars
+            differs between Zarr V2 and Zarr V3.
+
+        Returns
+        -------
+        TScalar
+            The deserialized scalar value.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    @abstractmethod
+    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> JSON:
+        """
+        Serialize a python object to the JSON representation of a scalar.
+
+        The value will first be cast to the scalar type associated with this ZDType, then serialized
+        to JSON.
+
+        Parameters
+        ----------
+        data : object
+            The value to convert.
+        zarr_format : ZarrFormat
+            The zarr format version. This is specified because the JSON serialization of scalars
+            differs between Zarr V2 and Zarr V3.
+
+        Returns
+        -------
+        JSON
+            The JSON-serialized scalar.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+
+def scalar_failed_type_check_msg(
+    cls_instance: ZDType[TBaseDType, TBaseScalar], bad_scalar: object
+) -> str:
+    """
+    Generate an error message reporting that a particular value failed a type check when attempting
+    to cast that value to a scalar.
+    """
+    return (
+        f"The value {bad_scalar!r} failed a type check. "
+        f"It cannot be safely cast to a scalar compatible with {cls_instance}. "
+        f"Consult the documentation for {cls_instance} to determine the possible values that can "
+        "be cast to scalars of the wrapped data type."
+    )