0
# Storage Backends
1

2
Storage backend classes for persisting zarr data across different storage systems. These provide the flexibility to use zarr with various storage infrastructures from local filesystems to cloud object stores.
3

4
## Capabilities
5

6
### Local and Memory Storage
7

8
```python { .api }
9
class LocalStore:
10
    """Local filesystem storage backend."""
11
    
12
    def __init__(
13
        self,
14
        root: Union[str, os.PathLike],
15
        normalize_keys: bool = True,
16
        map_size: int = 2**26,
17
        **kwargs
18
    ): ...
19
    
20
    def __getitem__(self, key: str) -> bytes: ...
21
    def __setitem__(self, key: str, value: bytes) -> None: ...
22
    def __delitem__(self, key: str) -> None: ...
23
    def __contains__(self, key: str) -> bool: ...
24
    def __iter__(self) -> Iterator[str]: ...
25
    def __len__(self) -> int: ...
26
    
27
    def list(self) -> list[str]: ...
28
    def list_prefix(self, prefix: str) -> list[str]: ...
29
    def list_dir(self, prefix: str = "") -> list[str]: ...
30
```
31

32
```python { .api }
33
class MemoryStore:
34
    """In-memory storage backend for temporary arrays."""
35
    
36
    def __init__(
37
        self,
38
        normalize_keys: bool = True,
39
        **kwargs
40
    ): ...
41
    
42
    def __getitem__(self, key: str) -> bytes: ...
43
    def __setitem__(self, key: str, value: bytes) -> None: ...
44
    def __delitem__(self, key: str) -> None: ...
45
    def __contains__(self, key: str) -> bool: ...
46
    def __iter__(self) -> Iterator[str]: ...
47
    def __len__(self) -> int: ...
48
    
49
    def clear(self) -> None: ...
50
```
51

52
```python { .api }
53
class GpuMemoryStore:
54
    """GPU memory storage backend using CuPy arrays."""
55
    
56
    def __init__(
57
        self,
58
        normalize_keys: bool = True,
59
        **kwargs
60
    ): ...
61
    
62
    # Same interface as MemoryStore but uses GPU memory
63
```
64

65
### Archive Storage
66

67
```python { .api }
68
class ZipStore:
69
    """ZIP file storage backend."""
70
    
71
    def __init__(
72
        self,
73
        path: Union[str, os.PathLike, io.IOBase],
74
        mode: str = 'r',
75
        compression: int = zipfile.ZIP_STORED,
76
        allowZip64: bool = True,
77
        **kwargs
78
    ): ...
79
    
80
    def __getitem__(self, key: str) -> bytes: ...
81
    def __setitem__(self, key: str, value: bytes) -> None: ...
82
    def __delitem__(self, key: str) -> None: ...  
83
    def __contains__(self, key: str) -> bool: ...
84
    def __iter__(self) -> Iterator[str]: ...
85
    
86
    def close(self) -> None: ...
87
    def flush(self) -> None: ...
88
```
89

90
### Cloud and Network Storage
91

92
```python { .api }
93
class FsspecStore:
94
    """Storage backend using fsspec for various filesystems."""
95
    
96
    def __init__(
97
        self,
98
        url: str,
99
        normalize_keys: bool = True,
100
        key_separator: str = '/',
101
        **storage_options
102
    ): ...
103
    
104
    def __getitem__(self, key: str) -> bytes: ...
105
    def __setitem__(self, key: str, value: bytes) -> None: ...
106
    def __delitem__(self, key: str) -> None: ...
107
    def __contains__(self, key: str) -> bool: ...
108
    def __iter__(self) -> Iterator[str]: ...
109
    
110
    @property
111
    def fs(self) -> fsspec.AbstractFileSystem: ...
112
    @property 
113
    def path(self) -> str: ...
114
```
115

116
```python { .api }
117
class ObjectStore:
118
    """High-performance cloud object storage backend."""
119
    
120
    def __init__(
121
        self,
122
        url: str,
123
        normalize_keys: bool = True,
124
        **kwargs
125
    ): ...
126
    
127
    def __getitem__(self, key: str) -> bytes: ...
128
    def __setitem__(self, key: str, value: bytes) -> None: ...
129
    def __delitem__(self, key: str) -> None: ...
130
    def __contains__(self, key: str) -> bool: ...
131
    def __iter__(self) -> Iterator[str]: ...
132
    
133
    async def get_async(self, key: str) -> bytes: ...
134
    async def set_async(self, key: str, value: bytes) -> None: ...
135
```
136

137
### Store Wrappers and Utilities
138

139
```python { .api }
140
class LoggingStore:
141
    """Wrapper store that logs all operations for debugging."""
142
    
143
    def __init__(
144
        self,
145
        store: Store,
146
        log: logging.Logger = None,
147
        log_level: int = logging.INFO
148
    ): ...
149
    
150
    # Wraps all store operations with logging
151
```
152

153
```python { .api }
154
class WrapperStore:
155
    """Base class for creating store wrappers."""
156
    
157
    def __init__(self, store: Store): ...
158
    
159
    @property
160
    def inner_store(self) -> Store: ...
161
```
162

163
### Store Path Utilities
164

165
```python { .api }
166
class StorePath:
167
    """Path-like interface for store locations."""
168
    
169
    def __init__(
170
        self,
171
        store: Store,
172
        path: str = ""
173
    ): ...
174
    
175
    @property
176
    def store(self) -> Store: ...
177
    @property
178
    def path(self) -> str: ...
179
    @property
180
    def name(self) -> str: ...
181
    @property  
182
    def suffix(self) -> str: ...
183
    @property
184
    def parent(self) -> StorePath: ...
185
    
186
    def __truediv__(self, other: str) -> StorePath: ...
187
    def __str__(self) -> str: ...
188
```
189

190
## Type Definitions
191

192
```python { .api }
193
StoreLike = Union[str, os.PathLike, Store, MutableMapping]
194
Store = Union[LocalStore, MemoryStore, ZipStore, FsspecStore, ObjectStore, MutableMapping]
195
```
196

197
## Usage Examples
198

199
### Local Filesystem Storage
200

201
```python
202
import zarr
203
from zarr.storage import LocalStore
204

205
# Create local store
206
store = LocalStore('path/to/zarr/data')
207

208
# Use with zarr operations
209
arr = zarr.create_array(store, shape=(1000, 1000), chunks=(100, 100))
210
arr[:100, :100] = 1.0
211

212
# Direct store access
213
store['array_metadata/.zarray'] = b'{"shape": [1000, 1000]}'
214
metadata_bytes = store['array_metadata/.zarray']
215
```
216

217
### Memory Storage
218

219
```python
220
from zarr.storage import MemoryStore
221

222
# Create in-memory store
223
store = MemoryStore()
224

225
# Create temporary arrays
226
temp_arr = zarr.create_array(store, shape=(100, 100))
227
temp_arr[:] = 42
228

229
# Memory stores are automatically cleaned up
230
```
231

232
### ZIP File Storage
233

234
```python
235
from zarr.storage import ZipStore
236

237
# Create ZIP store for archival
238
with ZipStore('dataset.zip', mode='w') as store:
239
    arr1 = zarr.create_array(store, 'array1', shape=(500, 500))
240
    arr2 = zarr.create_array(store, 'array2', shape=(300, 300))
241
    
242
    # Data is compressed in ZIP format
243
    arr1[:] = np.random.random((500, 500))
244
    arr2[:] = np.random.random((300, 300))
245

246
# Read from ZIP store
247
with ZipStore('dataset.zip', mode='r') as store:
248
    arr1 = zarr.open_array(store, 'array1')
249
    data = arr1[:]
250
```
251

252
### Cloud Storage with Fsspec
253

254
```python
255
from zarr.storage import FsspecStore
256

257
# S3 storage
258
s3_store = FsspecStore(
259
    's3://my-bucket/zarr-data/',
260
    key='aws_access_key_id',
261
    secret='aws_secret_access_key'
262
)
263

264
# Create array in S3
265
arr = zarr.create_array(s3_store, shape=(10000, 10000), chunks=(1000, 1000))
266

267
# Google Cloud Storage
268
gcs_store = FsspecStore('gs://my-bucket/zarr-data/')
269
arr = zarr.create_array(gcs_store, shape=(5000, 5000))
270

271
# HTTP storage (read-only)
272
http_store = FsspecStore('https://example.com/data.zarr')
273
arr = zarr.open_array(http_store)
274
```
275

276
### High-Performance Object Storage
277

278
```python
279
from zarr.storage import ObjectStore
280

281
# Fast cloud object storage
282
store = ObjectStore('s3://bucket/path/')
283

284
# Supports async operations for better performance  
285
import asyncio
286

287
async def async_write():
288
    await store.set_async('data/chunk.0.0', chunk_data)
289
    
290
asyncio.run(async_write())
291
```
292

293
### Store Composition and Wrapping
294

295
```python
296
from zarr.storage import LoggingStore, LocalStore
297
import logging
298

299
# Add logging to any store
300
base_store = LocalStore('data/')
301
logged_store = LoggingStore(base_store, log_level=logging.DEBUG)
302

303
# All operations will be logged
304
arr = zarr.create_array(logged_store, shape=(100, 100))
305
```
306

307
### Store Path Navigation
308

309
```python
310
from zarr.storage import StorePath, LocalStore
311

312
store = LocalStore('root/data/')
313
path = StorePath(store, 'experiments/run1')
314

315
# Path-like operations
316
sub_path = path / 'results' / 'array1'
317
parent = sub_path.parent
318

319
# Use with zarr
320
arr = zarr.create_array(sub_path, shape=(100, 100))
321
```
322

323
### Store Configuration for Different Use Cases
324

325
```python
326
# High-performance local storage
327
fast_store = LocalStore('/fast/ssd/path', map_size=2**30)
328

329
# Network-optimized storage
330
network_store = FsspecStore(
331
    's3://bucket/data/',
332
    cache_type='blockcache',
333
    block_size=1024*1024
334
)
335

336
# Memory-efficient storage
337
efficient_store = LocalStore('/path', normalize_keys=False)
338
```