Skip to content

Commit 2ff8875

Browse files
Add API reference for V3 Implementation in the docs (#1345)
* Add API reference for V3 Implementation in the docs * Minor fix * Minor fix * Minor indentation fix * Update docs/api/v3.rst Co-authored-by: Jonathan Striebel <jstriebel@users.noreply.github.com> * Update docs/api/v3.rst Co-authored-by: Jonathan Striebel <jstriebel@users.noreply.github.com> * Update docs/api/v3.rst Co-authored-by: Jonathan Striebel <jstriebel@users.noreply.github.com> * Fix broken links --------- Co-authored-by: Jonathan Striebel <jstriebel@users.noreply.github.com>
1 parent f7ef424 commit 2ff8875

File tree

2 files changed

+78
-0
lines changed

2 files changed

+78
-0
lines changed

docs/api.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ API reference
1313
api/codecs
1414
api/attrs
1515
api/sync
16+
api/v3
1617

1718
Indices and tables
1819
------------------

docs/api/v3.rst

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
V3 Specification Implementation(``zarr._storage.v3``)
2+
=====================================================
3+
4+
This module contains the implementation of the `Zarr V3 Specification <https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html>`_.
5+
6+
.. warning::
7+
Since Zarr Python 2.12 release, this module provides experimental infrastructure for reading and
8+
writing the upcoming V3 spec of the Zarr format. Users wishing to prepare for the migration can set
9+
the environment variable ``ZARR_V3_EXPERIMENTAL_API=1`` to begin experimenting, however data
10+
written with this API should be expected to become stale, as the implementation will still change.
11+
12+
The new ``zarr._store.v3`` package has the necessary classes and functions for evaluating Zarr V3.
13+
Since the design is not finalised, the classes and functions are not automatically imported into
14+
the regular Zarr namespace.
15+
16+
Code snippet for creating Zarr V3 arrays::
17+
18+
>>> import zarr
19+
>>> z = zarr.create((10000, 10000),
20+
>>> chunks=(100, 100),
21+
>>> dtype='f8',
22+
>>> compressor='default',
23+
>>> path='path-where-you-want-zarr-v3-array',
24+
>>> zarr_version=3)
25+
26+
Further, you can use `z.info` to see details about the array you just created::
27+
28+
>>> z.info
29+
Name : path-where-you-want-zarr-v3-array
30+
Type : zarr.core.Array
31+
Data type : float64
32+
Shape : (10000, 10000)
33+
Chunk shape : (100, 100)
34+
Order : C
35+
Read-only : False
36+
Compressor : Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
37+
Store type : zarr._storage.v3.KVStoreV3
38+
No. bytes : 800000000 (762.9M)
39+
No. bytes stored : 557
40+
Storage ratio : 1436265.7
41+
Chunks initialized : 0/10000
42+
43+
You can also check ``Store type`` here (which indicates Zarr V3).
44+
45+
.. module:: zarr._storage.v3
46+
47+
.. autoclass:: RmdirV3
48+
.. autoclass:: KVStoreV3
49+
.. autoclass:: FSStoreV3
50+
.. autoclass:: MemoryStoreV3
51+
.. autoclass:: DirectoryStoreV3
52+
.. autoclass:: ZipStoreV3
53+
.. autoclass:: RedisStoreV3
54+
.. autoclass:: MongoDBStoreV3
55+
.. autoclass:: DBMStoreV3
56+
.. autoclass:: LMDBStoreV3
57+
.. autoclass:: SQLiteStoreV3
58+
.. autoclass:: LRUStoreCacheV3
59+
.. autoclass:: ConsolidatedMetadataStoreV3
60+
61+
In v3 `storage transformers <https://zarr-specs.readthedocs.io/en/latest/v3/array-storage-transformers/sharding/v1.0.html>`_
62+
can be set via ``zarr.create(…, storage_transformers=[…])``.
63+
The experimental sharding storage transformer can be tested by setting
64+
the environment variable ``ZARR_V3_SHARDING=1``. Data written with this flag
65+
enabled should be expected to become stale until
66+
`ZEP 2 <https://zarr.dev/zeps/draft/ZEP0002.html>`_ is approved
67+
and fully implemented.
68+
69+
.. module:: zarr._storage.v3_storage_transformers
70+
71+
.. autoclass:: ShardingStorageTransformer
72+
73+
The abstract base class for storage transformers is
74+
75+
.. module:: zarr._storage.store
76+
77+
.. autoclass:: StorageTransformer

0 commit comments

Comments
 (0)