0
# Core Classes
1
2
The fundamental array and group classes that form the core of zarr's object-oriented interface. These classes provide comprehensive functionality for array manipulation and hierarchical data organization.
3
4
## Capabilities
5
6
### Array Class
7
8
```python { .api }
9
class Array:
10
"""Synchronous zarr array supporting chunked, compressed N-dimensional arrays."""
11
12
# Core Properties
13
shape: tuple[int, ...]
14
dtype: np.dtype
15
chunks: tuple[int, ...]
16
size: int
17
nbytes: int
18
nchunks: int
19
cdata_shape: tuple[int, ...]
20
21
# Metadata
22
attrs: Attributes
23
metadata: ArrayMetadata
24
name: str
25
path: str
26
basename: str
27
28
# Storage
29
store: Store
30
store_path: StorePath
31
32
def __init__(
33
self,
34
store_path: StorePath,
35
metadata: ArrayMetadata,
36
order: MemoryOrder = 'C'
37
): ...
38
```
39
40
#### Array Indexing and Data Access
41
42
```python { .api }
43
def __getitem__(self, selection: Selection) -> np.ndarray: ...
44
def __setitem__(self, selection: Selection, value: Any) -> None: ...
45
46
def get_basic_selection(
47
self,
48
selection: BasicSelection,
49
out: np.ndarray = None,
50
fields: Fields = None
51
) -> np.ndarray: ...
52
53
def set_basic_selection(
54
self,
55
selection: BasicSelection,
56
value: Any,
57
fields: Fields = None
58
) -> None: ...
59
60
def get_orthogonal_selection(
61
self,
62
selection: OrthogonalSelection,
63
out: np.ndarray = None,
64
fields: Fields = None
65
) -> np.ndarray: ...
66
67
def set_orthogonal_selection(
68
self,
69
selection: OrthogonalSelection,
70
value: Any,
71
fields: Fields = None
72
) -> None: ...
73
74
def get_coordinate_selection(
75
self,
76
selection: CoordinateSelection,
77
out: np.ndarray = None,
78
fields: Fields = None
79
) -> np.ndarray: ...
80
81
def set_coordinate_selection(
82
self,
83
selection: CoordinateSelection,
84
value: Any,
85
fields: Fields = None
86
) -> None: ...
87
88
def get_mask_selection(
89
self,
90
selection: MaskSelection,
91
out: np.ndarray = None,
92
fields: Fields = None
93
) -> np.ndarray: ...
94
95
def set_mask_selection(
96
self,
97
selection: MaskSelection,
98
value: Any,
99
fields: Fields = None
100
) -> None: ...
101
```
102
103
#### Array Modification
104
105
```python { .api }
106
def resize(self, *args: int) -> None: ...
107
108
def append(
109
self,
110
data: ArrayLike,
111
axis: int = 0
112
) -> None: ...
113
114
def create_chunk(self, chunk_coords: tuple[int, ...]) -> None: ...
115
```
116
117
#### Array Views and Indexing Helpers
118
119
```python { .api }
120
@property
121
def oindex(self) -> OIndex: ...
122
123
@property
124
def vindex(self) -> VIndex: ...
125
126
@property
127
def blocks(self) -> BlockIndex: ...
128
```
129
130
#### Array Information and Utilities
131
132
```python { .api }
133
def info(self) -> ArrayInfo: ...
134
135
def __array__(self, dtype: np.dtype = None) -> np.ndarray: ...
136
137
def __repr__(self) -> str: ...
138
139
def __str__(self) -> str: ...
140
```
141
142
### AsyncArray Class
143
144
```python { .api }
145
class AsyncArray(Generic[ArrayMetadata]):
146
"""Asynchronous zarr array with same functionality as Array but async methods."""
147
148
# Same properties as Array
149
shape: tuple[int, ...]
150
dtype: np.dtype
151
chunks: tuple[int, ...]
152
size: int
153
nbytes: int
154
nchunks: int
155
attrs: Attributes
156
metadata: ArrayMetadata
157
158
def __init__(
159
self,
160
store_path: StorePath,
161
metadata: ArrayMetadata,
162
order: MemoryOrder = 'C'
163
): ...
164
165
# Async data access methods
166
async def getitem(
167
self,
168
selection: Selection,
169
prototype: BufferPrototype = None
170
) -> NDBuffer: ...
171
172
async def setitem(
173
self,
174
selection: Selection,
175
value: NDArrayLike
176
) -> None: ...
177
178
async def resize(self, *args: int) -> None: ...
179
180
async def info(self) -> ArrayInfo: ...
181
```
182
183
### Group Class
184
185
```python { .api }
186
class Group:
187
"""Synchronous zarr group for hierarchical organization of arrays and subgroups."""
188
189
# Core Properties
190
attrs: Attributes
191
metadata: GroupMetadata
192
name: str
193
path: str
194
basename: str
195
196
# Storage
197
store: Store
198
store_path: StorePath
199
200
def __init__(
201
self,
202
store_path: StorePath,
203
metadata: GroupMetadata = None
204
): ...
205
```
206
207
#### Group Navigation and Access
208
209
```python { .api }
210
def __getitem__(self, key: str) -> Union[Array, Group]: ...
211
def __setitem__(self, key: str, value: Any) -> None: ...
212
def __delitem__(self, key: str) -> None: ...
213
def __contains__(self, key: str) -> bool: ...
214
def __iter__(self) -> Iterator[str]: ...
215
def __len__(self) -> int: ...
216
217
def keys(self) -> Iterator[str]: ...
218
def values(self) -> Iterator[Union[Array, Group]]: ...
219
def items(self) -> Iterator[tuple[str, Union[Array, Group]]]: ...
220
221
@property
222
def members(self) -> dict[str, Union[Array, Group]]: ...
223
```
224
225
#### Array Creation within Groups
226
227
```python { .api }
228
def create_array(
229
self,
230
name: str,
231
shape: ShapeLike,
232
dtype: DTypeLike = 'float64',
233
chunks: ChunksLike = None,
234
compressor: CompressorLike = 'default',
235
fill_value: Any = None,
236
order: str = 'C',
237
filters: FiltersLike = None,
238
cache_metadata: bool = True,
239
cache_attrs: bool = True,
240
read_only: bool = False,
241
object_codec: Any = None,
242
dimension_separator: str = None,
243
write_empty_chunks: bool = True,
244
overwrite: bool = False,
245
**kwargs
246
) -> Array: ...
247
248
def array(
249
self,
250
name: str,
251
data: ArrayLike,
252
**kwargs
253
) -> Array: ...
254
255
def empty(
256
self,
257
name: str,
258
shape: ShapeLike,
259
**kwargs
260
) -> Array: ...
261
262
def zeros(
263
self,
264
name: str,
265
shape: ShapeLike,
266
**kwargs
267
) -> Array: ...
268
269
def ones(
270
self,
271
name: str,
272
shape: ShapeLike,
273
**kwargs
274
) -> Array: ...
275
276
def full(
277
self,
278
name: str,
279
shape: ShapeLike,
280
fill_value: Any,
281
**kwargs
282
) -> Array: ...
283
```
284
285
#### Subgroup Creation within Groups
286
287
```python { .api }
288
def create_group(
289
self,
290
name: str,
291
overwrite: bool = False,
292
cache_attrs: bool = True,
293
**kwargs
294
) -> Group: ...
295
296
def require_group(
297
self,
298
name: str,
299
overwrite: bool = False
300
) -> Group: ...
301
```
302
303
#### Group Utilities
304
305
```python { .api }
306
def info(self) -> GroupInfo: ...
307
308
def tree(self, expand: bool = False, level: int = None) -> Any: ...
309
310
def __repr__(self) -> str: ...
311
```
312
313
### AsyncGroup Class
314
315
```python { .api }
316
class AsyncGroup:
317
"""Asynchronous zarr group with same functionality as Group but async methods."""
318
319
# Same properties as Group
320
attrs: Attributes
321
metadata: GroupMetadata
322
name: str
323
path: str
324
325
# Async methods mirror Group methods
326
async def getitem(self, key: str) -> Union[AsyncArray, AsyncGroup]: ...
327
async def setitem(self, key: str, value: Any) -> None: ...
328
async def delitem(self, key: str) -> None: ...
329
async def contains(self, key: str) -> bool: ...
330
331
async def create_array(self, name: str, **kwargs) -> AsyncArray: ...
332
async def create_group(self, name: str, **kwargs) -> AsyncGroup: ...
333
```
334
335
## Type Definitions
336
337
```python { .api }
338
# Selection types
339
Selection = Union[BasicSelection, OrthogonalSelection, CoordinateSelection, MaskSelection]
340
BasicSelection = Union[slice, int, tuple]
341
OrthogonalSelection = tuple[Union[slice, int, np.ndarray], ...]
342
CoordinateSelection = tuple[np.ndarray, ...]
343
MaskSelection = np.ndarray
344
345
# Data types
346
ArrayLike = Union[np.ndarray, Array, list, tuple]
347
ShapeLike = Union[int, tuple[int, ...]]
348
DTypeLike = Union[str, np.dtype, type]
349
Fields = Union[str, list[str]]
350
351
# Memory order
352
MemoryOrder = Literal['C', 'F']
353
```
354
355
## Usage Examples
356
357
### Basic Array Operations
358
359
```python
360
import zarr
361
import numpy as np
362
363
# Create and access array
364
z = zarr.zeros((1000, 1000), chunks=(100, 100))
365
366
# Basic indexing
367
z[0, :] = 1.0
368
data = z[:10, :10]
369
370
# Advanced indexing
371
z.oindex[0, :] = 2.0 # Orthogonal indexing
372
z.vindex[[0, 1], [0, 1]] = 3.0 # Vectorized indexing
373
374
# Block access
375
for block in z.blocks:
376
print(block.shape)
377
378
# Array modification
379
z.resize(2000, 2000)
380
z.append(np.ones((100, 1000)), axis=0)
381
```
382
383
### Group Operations
384
385
```python
386
# Create group and add arrays
387
grp = zarr.group()
388
grp.create_array('temperature', shape=(365, 100, 100), chunks=(1, 50, 50))
389
grp.create_array('humidity', shape=(365, 100, 100), chunks=(1, 50, 50))
390
391
# Create nested groups
392
sub_grp = grp.create_group('processed_data')
393
sub_grp.create_array('average_temp', shape=(365,), chunks=(100,))
394
395
# Access data
396
temp_data = grp['temperature']
397
avg_temp = grp['processed_data/average_temp']
398
399
# Iterate through group
400
for name, item in grp.items():
401
if isinstance(item, zarr.Array):
402
print(f"Array {name}: shape={item.shape}")
403
elif isinstance(item, zarr.Group):
404
print(f"Group {name}: {len(item)} members")
405
```
406
407
### Working with Attributes
408
409
```python
410
# Set array attributes
411
z = zarr.zeros((100, 100))
412
z.attrs['units'] = 'temperature'
413
z.attrs['scale_factor'] = 0.1
414
z.attrs['add_offset'] = 273.15
415
416
# Set group attributes
417
grp = zarr.group()
418
grp.attrs['title'] = 'Weather Dataset'
419
grp.attrs['created'] = '2024-01-01'
420
421
# Access attributes
422
print(z.attrs['units'])
423
print(grp.attrs['title'])
424
```