Skip to content

Commit 4238567

Browse files
dstansbydstansby
committed
Use docstests
1 parent f6be517 commit 4238567

File tree

1 file changed

+119
-98
lines changed

1 file changed

+119
-98
lines changed

‎docs/quickstart.rst‎

Lines changed: 119 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,10 @@
1-
.. ipython:: python
2-
:suppress:
1+
.. only:: doctest
32

4-
rm -r data/
5-
6-
.. ipython:: python
7-
:suppress:
8-
9-
import numpy as np
10-
np.random.seed(0)
3+
>>> import shutil
4+
>>> shutil.rmtree('data', ignore_errors=True)
5+
>>>
6+
>>> import numpy as np
7+
>>> np.random.seed(0)
118

129
Quickstart
1310
==========
@@ -37,24 +34,32 @@ or `conda`:
3734
Creating an Array
3835
-----------------
3936

40-
To get started, you can create a simple Zarr array:
41-
42-
.. ipython:: python
43-
44-
import zarr
45-
import numpy as np
46-
47-
# Create a 2D Zarr array
48-
z = zarr.create_array(
49-
store="data/example-1.zarr",
50-
shape=(100, 100),
51-
chunks=(10, 10),
52-
dtype="f4"
53-
)
54-
55-
# Assign data to the array
56-
z[:, :] = np.random.random((100, 100))
57-
z.info
37+
To get started, you can create a simple Zarr array::
38+
39+
>>> import zarr
40+
>>> import numpy as np
41+
>>>
42+
>>> # Create a 2D Zarr array
43+
>>> z = zarr.create_array(
44+
... store="data/example-1.zarr",
45+
... shape=(100, 100),
46+
... chunks=(10, 10),
47+
... dtype="f4"
48+
... )
49+
>>>
50+
>>> # Assign data to the array
51+
>>> z[:, :] = np.random.random((100, 100))
52+
>>> z.info
53+
Type : Array
54+
Zarr format : 3
55+
Data type : DataType.float32
56+
Shape : (100, 100)
57+
Chunk shape : (10, 10)
58+
Order : C
59+
Read-only : False
60+
Store type : LocalStore
61+
Codecs : [{'endian': <Endian.little: 'little'>}, {'level': 0, 'checksum': False}]
62+
No. bytes : 40000 (39.1K)
5863

5964
Here, we created a 2D array of shape ``(100, 100)``, chunked into blocks of
6065
``(10, 10)``, and filled it with random floating-point data. This array was
@@ -63,43 +68,53 @@ written to a ``LocalStore`` in the ``data/example-1.zarr`` directory.
6368
Compression and Filters
6469
~~~~~~~~~~~~~~~~~~~~~~~
6570

66-
Zarr supports data compression and filters. For example, to use Blosc compression:
67-
68-
.. ipython:: python
69-
70-
z = zarr.create_array(
71-
"data/example-3.zarr",
72-
mode="w", shape=(100, 100),
73-
chunks=(10, 10), dtype="f4",
74-
compressor=zarr.codecs.BloscCodec(cname="zstd", clevel=3, shuffle=zarr.codecs.BloscShuffle.SHUFFLE)
75-
)
76-
z[:, :] = np.random.random((100, 100))
77-
78-
z.info
71+
Zarr supports data compression and filters. For example, to use Blosc compression::
72+
73+
>>> z = zarr.create_array(
74+
... "data/example-3.zarr",
75+
... mode="w", shape=(100, 100),
76+
... chunks=(10, 10), dtype="f4",
77+
... compressor=zarr.codecs.BloscCodec(cname="zstd", clevel=3, shuffle=zarr.codecs.BloscShuffle.SHUFFLE)
78+
... )
79+
>>> z[:, :] = np.random.random((100, 100))
80+
>>>
81+
>>> z.info
82+
Type : Array
83+
Zarr format : 3
84+
Data type : DataType.float32
85+
Shape : (100, 100)
86+
Chunk shape : (10, 10)
87+
Order : C
88+
Read-only : False
89+
Store type : LocalStore
90+
Codecs : [{'endian': <Endian.little: 'little'>}, {'level': 0, 'checksum': False}]
91+
No. bytes : 40000 (39.1K)
7992

8093
This compresses the data using the Zstandard codec with shuffle enabled for better compression.
8194

8295
Hierarchical Groups
8396
-------------------
8497

85-
Zarr allows you to create hierarchical groups, similar to directories:
86-
87-
.. ipython:: python
88-
89-
# Create nested groups and add arrays
90-
root = zarr.group("data/example-2.zarr")
91-
foo = root.create_group(name="foo")
92-
bar = root.create_array(
93-
name="bar", shape=(100, 10), chunks=(10, 10)
94-
)
95-
spam = foo.create_array(name="spam", shape=(10,), dtype="i4")
96-
97-
# Assign values
98-
bar[:, :] = np.random.random((100, 10))
99-
spam[:] = np.arange(10)
100-
101-
# print the hierarchy
102-
root.tree()
98+
Zarr allows you to create hierarchical groups, similar to directories::
99+
100+
>>> # Create nested groups and add arrays
101+
>>> root = zarr.group("data/example-2.zarr")
102+
>>> foo = root.create_group(name="foo")
103+
>>> bar = root.create_array(
104+
... name="bar", shape=(100, 10), chunks=(10, 10)
105+
... )
106+
>>> spam = foo.create_array(name="spam", shape=(10,), dtype="i4")
107+
>>>
108+
>>> # Assign values
109+
>>> bar[:, :] = np.random.random((100, 10))
110+
>>> spam[:] = np.arange(10)
111+
>>>
112+
>>> # print the hierarchy
113+
>>> root.tree()
114+
/
115+
└── foo
116+
└── spam (10,) int32
117+
<BLANKLINE>
103118

104119
This creates a group with two datasets: ``foo`` and ``bar``.
105120

@@ -108,38 +123,47 @@ Persistent Storage
108123

109124
Zarr supports persistent storage to disk or cloud-compatible backends. While examples above
110125
utilized a :class:`zarr.storage.LocalStore`, a number of other storage options are available,
111-
including the :class:`zarr.storage.ZipStore` and :class:`zarr.storage.FsspecStore`.
112-
113-
.. ipython:: python
114-
115-
# Store the array in a ZIP file
116-
store = zarr.storage.ZipStore("data/example-3.zip", mode='w')
117-
118-
z = zarr.create_array(
119-
store=store,
120-
mode="w",
121-
shape=(100, 100),
122-
chunks=(10, 10),
123-
dtype="f4"
124-
)
125-
126-
# write to the array
127-
z[:, :] = np.random.random((100, 100))
128-
129-
# the ZipStore must be explicitly closed
130-
store.close()
131-
132-
To open an existing array:
133-
134-
.. ipython:: python
135-
136-
# Open the ZipStore in read-only mode
137-
store = zarr.storage.ZipStore("data/example-3.zip", read_only=True)
138-
139-
z = zarr.open_array(store, mode='r')
140-
141-
# read the data as a NumPy Array
142-
z[:]
126+
including the :class:`zarr.storage.ZipStore` and :class:`zarr.storage.FsspecStore`::
127+
128+
>>> # Store the array in a ZIP file
129+
>>> store = zarr.storage.ZipStore("data/example-3.zip", mode='w')
130+
>>>
131+
>>> z = zarr.create_array(
132+
... store=store,
133+
... mode="w",
134+
... shape=(100, 100),
135+
... chunks=(10, 10),
136+
... dtype="f4"
137+
... )
138+
>>>
139+
>>> # write to the array
140+
>>> z[:, :] = np.random.random((100, 100))
141+
>>>
142+
>>> # the ZipStore must be explicitly closed
143+
>>> store.close()
144+
145+
To open an existing array::
146+
147+
>>> # Open the ZipStore in read-only mode
148+
>>> store = zarr.storage.ZipStore("data/example-3.zip", read_only=True)
149+
>>>
150+
>>> z = zarr.open_array(store, mode='r')
151+
>>>
152+
>>> # read the data as a NumPy Array
153+
>>> z[:]
154+
array([[0.66734236, 0.15667458, 0.98720884, ..., 0.36229587, 0.67443246,
155+
0.34315267],
156+
[0.65787303, 0.9544212 , 0.4830079 , ..., 0.33097172, 0.60423803,
157+
0.45621237],
158+
[0.27632037, 0.9947008 , 0.42434934, ..., 0.94860053, 0.6226942 ,
159+
0.6386924 ],
160+
...,
161+
[0.12854576, 0.934397 , 0.19524333, ..., 0.11838563, 0.4967675 ,
162+
0.43074256],
163+
[0.82029045, 0.4671437 , 0.8090906 , ..., 0.7814118 , 0.42650765,
164+
0.95929915],
165+
[0.4335856 , 0.7565437 , 0.7828931 , ..., 0.48119593, 0.66220033,
166+
0.6652362 ]], shape=(100, 100), dtype=float32)
143167

144168
Cloud Storage Backends
145169
~~~~~~~~~~~~~~~~~~~~~~
@@ -148,15 +172,12 @@ Zarr integrates seamlessly with cloud storage such as Amazon S3 and Google Cloud
148172
using external libraries like `s3fs <https://s3fs.readthedocs.io>`_ or
149173
`gcsfs <https://gcsfs.readthedocs.io>`_.
150174

151-
For example, to use S3:
152-
153-
.. ipython:: python
154-
:verbatim:
155-
156-
import s3fs
175+
For example, to use S3::
157176

158-
z = zarr.create_array("s3://example-bucket/foo", mode="w", shape=(100, 100), chunks=(10, 10))
159-
z[:, :] = np.random.random((100, 100))
177+
>>> import s3fs # doctest: +SKIP
178+
>>>
179+
>>> z = zarr.create_array("s3://example-bucket/foo", mode="w", shape=(100, 100), chunks=(10, 10)) # doctest: +SKIP
180+
>>> z[:, :] = np.random.random((100, 100)) # doctest: +SKIP
160181

161182
Read more about Zarr's :ref:`tutorial_storage` options in the User Guide.
162183

0 commit comments

Comments
 (0)