def test_open_group():
# test the open_group() convenience function
store = 'data/group.zarr'
# mode == 'w'
g = open_group(store, mode='w')
assert_is_instance(g, Group)
assert_is_instance(g.store, DirectoryStore)
eq(0, len(g))
g.create_groups('foo', 'bar')
eq(2, len(g))
# mode in 'r', 'r+'
open_array('data/array.zarr', shape=100, chunks=10, mode='w')
for mode in 'r', 'r+':
with assert_raises(ValueError):
open_group('doesnotexist', mode=mode)
with assert_raises(ValueError):
open_group('data/array.zarr', mode=mode)
g = open_group(store, mode='r')
assert_is_instance(g, Group)
eq(2, len(g))
with assert_raises(PermissionError):
g.create_group('baz')
g = open_group(store, mode='r+')
assert_is_instance(g, Group)
eq(2, len(g))
g.create_groups('baz', 'quux')
eq(4, len(g))
# mode == 'a'
shutil.rmtree(store)
g = open_group(store, mode='a')
assert_is_instance(g, Group)
assert_is_instance(g.store, DirectoryStore)
eq(0, len(g))
g.create_groups('foo', 'bar')
eq(2, len(g))
with assert_raises(ValueError):
open_group('data/array.zarr', mode='a')
# mode in 'w-', 'x'
for mode in 'w-', 'x':
shutil.rmtree(store)
g = open_group(store, mode=mode)
assert_is_instance(g, Group)
assert_is_instance(g.store, DirectoryStore)
eq(0, len(g))
g.create_groups('foo', 'bar')
eq(2, len(g))
with assert_raises(ValueError):
open_group(store, mode=mode)
with assert_raises(ValueError):
open_group('data/array.zarr', mode=mode)
# open with path
g = open_group(store, path='foo/bar')
assert_is_instance(g, Group)
eq('foo/bar', g.path)
def test_open_group():
# test the open_group() convenience function
store = 'example'
# mode == 'w'
g = open_group(store, mode='w')
assert_is_instance(g, Group)
assert_is_instance(g.store, DirectoryStore)
eq(0, len(g))
g.create_groups('foo', 'bar')
eq(2, len(g))
# mode in 'r', 'r+'
open_array('example_array', shape=100, chunks=10, mode='w')
for mode in 'r', 'r+':
with assert_raises(KeyError):
open_group('doesnotexist', mode=mode)
with assert_raises(KeyError):
open_group('example_array', mode=mode)
g = open_group(store, mode='r')
assert_is_instance(g, Group)
eq(2, len(g))
with assert_raises(PermissionError):
g.create_group('baz')
g = open_group(store, mode='r+')
assert_is_instance(g, Group)
eq(2, len(g))
g.create_groups('baz', 'quux')
eq(4, len(g))
# mode == 'a'
shutil.rmtree(store)
g = open_group(store, mode='a')
assert_is_instance(g, Group)
assert_is_instance(g.store, DirectoryStore)
eq(0, len(g))
g.create_groups('foo', 'bar')
eq(2, len(g))
with assert_raises(KeyError):
open_group('example_array', mode='a')
# mode in 'w-', 'x'
for mode in 'w-', 'x':
shutil.rmtree(store)
g = open_group(store, mode=mode)
assert_is_instance(g, Group)
assert_is_instance(g.store, DirectoryStore)
eq(0, len(g))
g.create_groups('foo', 'bar')
eq(2, len(g))
with assert_raises(KeyError):
open_group(store, mode=mode)
with assert_raises(KeyError):
open_group('example_array', mode=mode)
# open with path
g = open_group(store, path='foo/bar')
assert_is_instance(g, Group)
eq('foo/bar', g.path)
def test_open_group():
# test the open_group() convenience function
store = 'data/group.zarr'
# mode == 'w'
g = open_group(store, mode='w')
assert isinstance(g, Group)
assert isinstance(g.store, DirectoryStore)
assert 0 == len(g)
g.create_groups('foo', 'bar')
assert 2 == len(g)
# mode in 'r', 'r+'
open_array('data/array.zarr', shape=100, chunks=10, mode='w')
for mode in 'r', 'r+':
with pytest.raises(ValueError):
open_group('doesnotexist', mode=mode)
with pytest.raises(ValueError):
open_group('data/array.zarr', mode=mode)
g = open_group(store, mode='r')
assert isinstance(g, Group)
assert 2 == len(g)
with pytest.raises(PermissionError):
g.create_group('baz')
g = open_group(store, mode='r+')
assert isinstance(g, Group)
assert 2 == len(g)
g.create_groups('baz', 'quux')
assert 4 == len(g)
# mode == 'a'
shutil.rmtree(store)
g = open_group(store, mode='a')
assert isinstance(g, Group)
assert isinstance(g.store, DirectoryStore)
assert 0 == len(g)
g.create_groups('foo', 'bar')
assert 2 == len(g)
with pytest.raises(ValueError):
open_group('data/array.zarr', mode='a')
# mode in 'w-', 'x'
for mode in 'w-', 'x':
shutil.rmtree(store)
g = open_group(store, mode=mode)
assert isinstance(g, Group)
assert isinstance(g.store, DirectoryStore)
assert 0 == len(g)
g.create_groups('foo', 'bar')
assert 2 == len(g)
with pytest.raises(ValueError):
open_group(store, mode=mode)
with pytest.raises(ValueError):
open_group('data/array.zarr', mode=mode)
# open with path
g = open_group(store, path='foo/bar')
assert isinstance(g, Group)
assert 'foo/bar' == g.path
def test_open_array_n5(zarr_version):
store = 'data/array.zarr'
kwargs = _init_creation_kwargs(zarr_version)
# for N5 store
store = 'data/array.n5'
z = open_array(store, mode='w', shape=100, chunks=10, **kwargs)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, N5Store)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
store = 'data/group.n5'
group_kwargs = kwargs.copy()
# if zarr_version == 3:
# group_kwargs['path'] = 'group'
z = open_group(store, mode='w', **group_kwargs)
i = z.create_group('inner')
a = i.zeros("array", shape=100, chunks=10)
a[:] = 42
# Edit inner/attributes.json to not include "n5"
with open('data/group.n5/inner/attributes.json', 'w') as o:
o.write("{}")
# Re-open
a = open_group(store, **group_kwargs)["inner"]["array"]
assert isinstance(a, Array)
assert isinstance(z.store, N5Store)
assert (100, ) == a.shape
assert (10, ) == a.chunks
assert_array_equal(np.full(100, fill_value=42), a[:])
def test_open_array_infer_separator_from_store(zarr_version,
dimension_separator):
if zarr_version == 3:
StoreClass = DirectoryStoreV3
path = 'data'
else:
StoreClass = DirectoryStore
path = None
store = StoreClass('data/array.zarr',
dimension_separator=dimension_separator)
# Note: no dimension_separator kwarg to open_array
# we are testing here that it gets inferred from store
z = open_array(store, path=path, mode='w', shape=100, chunks=10)
z[:] = 42
assert isinstance(z, Array)
if z._store._store_version == 2:
assert isinstance(z.store, DirectoryStore)
else:
assert isinstance(z.store, DirectoryStoreV3)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
if dimension_separator is None:
assert z._dimension_separator == '/' if zarr_version == 3 else '.'
else:
assert z._dimension_separator == dimension_separator
def test_open_array_dict_store():
# dict will become a KVStore
store = dict()
# mode == 'w'
z = open_array(store, mode='w', shape=100, chunks=10)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, KVStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
def test_open_array_dict_store(zarr_version):
# dict will become a KVStore
store = dict()
kwargs = _init_creation_kwargs(zarr_version)
expected_store_type = KVStoreV3 if zarr_version == 3 else KVStore
# mode == 'w'
z = open_array(store, mode='w', shape=100, chunks=10, **kwargs)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, expected_store_type)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
def test_open_array():
store = 'data/array.zarr'
# mode == 'w'
z = open_array(store, mode='w', shape=100, chunks=10)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, DirectoryStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
# mode in 'r', 'r+'
open_group('data/group.zarr', mode='w')
for mode in 'r', 'r+':
with pytest.raises(ValueError):
open_array('doesnotexist', mode=mode)
with pytest.raises(ValueError):
open_array('data/group.zarr', mode=mode)
z = open_array(store, mode='r')
assert isinstance(z, Array)
assert isinstance(z.store, DirectoryStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
with pytest.raises(PermissionError):
z[:] = 43
z = open_array(store, mode='r+')
assert isinstance(z, Array)
assert isinstance(z.store, DirectoryStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
z[:] = 43
assert_array_equal(np.full(100, fill_value=43), z[:])
# mode == 'a'
shutil.rmtree(store)
z = open_array(store, mode='a', shape=100, chunks=10)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, DirectoryStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
with pytest.raises(ValueError):
open_array('data/group.zarr', mode='a')
# mode in 'w-', 'x'
for mode in 'w-', 'x':
shutil.rmtree(store)
z = open_array(store, mode=mode, shape=100, chunks=10)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, DirectoryStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
with pytest.raises(ValueError):
open_array(store, mode=mode)
with pytest.raises(ValueError):
open_array('data/group.zarr', mode=mode)
# with synchronizer
z = open_array(store, synchronizer=ThreadSynchronizer())
assert isinstance(z, Array)
# with path
z = open_array(store, shape=100, path='foo/bar', mode='w')
assert isinstance(z, Array)
assert 'foo/bar' == z.path
# with chunk store
meta_store = 'data/meta.zarr'
chunk_store = 'data/chunks.zarr'
z = open_array(store=meta_store,
chunk_store=chunk_store,
shape=11,
mode='w')
z[:] = 42
assert os.path.abspath(meta_store) == z.store.path
assert os.path.abspath(chunk_store) == z.chunk_store.path
# for N5 store
store = 'data/array.n5'
z = open_array(store, mode='w', shape=100, chunks=10)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, N5Store)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
def test_open_array():
store = 'data/array.zarr'
# mode == 'w'
z = open_array(store, mode='w', shape=100, chunks=10)
z[:] = 42
assert_is_instance(z, Array)
assert_is_instance(z.store, DirectoryStore)
eq((100,), z.shape)
eq((10,), z.chunks)
assert_array_equal(np.full(100, fill_value=42), z[:])
# mode in 'r', 'r+'
open_group('data/group.zarr', mode='w')
for mode in 'r', 'r+':
with assert_raises(ValueError):
open_array('doesnotexist', mode=mode)
with assert_raises(ValueError):
open_array('data/group.zarr', mode=mode)
z = open_array(store, mode='r')
assert_is_instance(z, Array)
assert_is_instance(z.store, DirectoryStore)
eq((100,), z.shape)
eq((10,), z.chunks)
assert_array_equal(np.full(100, fill_value=42), z[:])
with assert_raises(PermissionError):
z[:] = 43
z = open_array(store, mode='r+')
assert_is_instance(z, Array)
assert_is_instance(z.store, DirectoryStore)
eq((100,), z.shape)
eq((10,), z.chunks)
assert_array_equal(np.full(100, fill_value=42), z[:])
z[:] = 43
assert_array_equal(np.full(100, fill_value=43), z[:])
# mode == 'a'
shutil.rmtree(store)
z = open_array(store, mode='a', shape=100, chunks=10)
z[:] = 42
assert_is_instance(z, Array)
assert_is_instance(z.store, DirectoryStore)
eq((100,), z.shape)
eq((10,), z.chunks)
assert_array_equal(np.full(100, fill_value=42), z[:])
with assert_raises(ValueError):
open_array('data/group.zarr', mode='a')
# mode in 'w-', 'x'
for mode in 'w-', 'x':
shutil.rmtree(store)
z = open_array(store, mode=mode, shape=100, chunks=10)
z[:] = 42
assert_is_instance(z, Array)
assert_is_instance(z.store, DirectoryStore)
eq((100,), z.shape)
eq((10,), z.chunks)
assert_array_equal(np.full(100, fill_value=42), z[:])
with assert_raises(ValueError):
open_array(store, mode=mode)
with assert_raises(ValueError):
open_array('data/group.zarr', mode=mode)
# with synchronizer
z = open_array(store, synchronizer=ThreadSynchronizer())
assert_is_instance(z, Array)
# with path
z = open_array(store, shape=100, path='foo/bar', mode='w')
assert_is_instance(z, Array)
eq('foo/bar', z.path)
def test_open_array():
store = 'data/array.zarr'
# mode == 'w'
z = open_array(store, mode='w', shape=100, chunks=10)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, DirectoryStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
# mode in 'r', 'r+'
open_group('data/group.zarr', mode='w')
for mode in 'r', 'r+':
with pytest.raises(ValueError):
open_array('doesnotexist', mode=mode)
with pytest.raises(ValueError):
open_array('data/group.zarr', mode=mode)
z = open_array(store, mode='r')
assert isinstance(z, Array)
assert isinstance(z.store, DirectoryStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
with pytest.raises(PermissionError):
z[:] = 43
z = open_array(store, mode='r+')
assert isinstance(z, Array)
assert isinstance(z.store, DirectoryStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
z[:] = 43
assert_array_equal(np.full(100, fill_value=43), z[:])
# mode == 'a'
shutil.rmtree(store)
z = open_array(store, mode='a', shape=100, chunks=10)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, DirectoryStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
with pytest.raises(ValueError):
open_array('data/group.zarr', mode='a')
# mode in 'w-', 'x'
for mode in 'w-', 'x':
shutil.rmtree(store)
z = open_array(store, mode=mode, shape=100, chunks=10)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, DirectoryStore)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
with pytest.raises(ValueError):
open_array(store, mode=mode)
with pytest.raises(ValueError):
open_array('data/group.zarr', mode=mode)
# with synchronizer
z = open_array(store, synchronizer=ThreadSynchronizer())
assert isinstance(z, Array)
# with path
z = open_array(store, shape=100, path='foo/bar', mode='w')
assert isinstance(z, Array)
assert 'foo/bar' == z.path
# with chunk store
meta_store = 'data/meta.zarr'
chunk_store = 'data/chunks.zarr'
z = open_array(store=meta_store,
chunk_store=chunk_store,
shape=11,
mode='w')
z[:] = 42
assert os.path.abspath(meta_store) == z.store.path
assert os.path.abspath(chunk_store) == z.chunk_store.path
# for N5 store
store = 'data/array.n5'
z = open_array(store, mode='w', shape=100, chunks=10)
z[:] = 42
assert isinstance(z, Array)
assert isinstance(z.store, N5Store)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
store = 'data/group.n5'
z = open_group(store, mode='w')
i = z.create_group('inner')
a = i.zeros("array", shape=100, chunks=10)
a[:] = 42
# Edit inner/attributes.json to not include "n5"
with open('data/group.n5/inner/attributes.json', 'w') as o:
o.write("{}")
# Re-open
a = open_group(store)["inner"]["array"]
assert isinstance(a, Array)
assert isinstance(z.store, N5Store)
assert (100, ) == a.shape
assert (10, ) == a.chunks
assert_array_equal(np.full(100, fill_value=42), a[:])
def open(store: StoreLike = None, mode: str = "a", **kwargs):
"""Convenience function to open a group or array using file-mode-like semantics.
Parameters
----------
store : Store or string, optional
Store or path to directory in file system or name of zip file.
mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
Persistence mode: 'r' means read only (must exist); 'r+' means
read/write (must exist); 'a' means read/write (create if doesn't
exist); 'w' means create (overwrite if exists); 'w-' means create
(fail if exists).
**kwargs
Additional parameters are passed through to :func:`zarr.creation.open_array` or
:func:`zarr.hierarchy.open_group`.
Returns
-------
z : :class:`zarr.core.Array` or :class:`zarr.hierarchy.Group`
Array or group, depending on what exists in the given store.
See Also
--------
zarr.creation.open_array, zarr.hierarchy.open_group
Examples
--------
Storing data in a directory 'data/example.zarr' on the local file system::
>>> import zarr
>>> store = 'data/example.zarr'
>>> zw = zarr.open(store, mode='w', shape=100, dtype='i4') # open new array
>>> zw
<zarr.core.Array (100,) int32>
>>> za = zarr.open(store, mode='a') # open existing array for reading and writing
>>> za
<zarr.core.Array (100,) int32>
>>> zr = zarr.open(store, mode='r') # open existing array read-only
>>> zr
<zarr.core.Array (100,) int32 read-only>
>>> gw = zarr.open(store, mode='w') # open new group, overwriting previous data
>>> gw
<zarr.hierarchy.Group '/'>
>>> ga = zarr.open(store, mode='a') # open existing group for reading and writing
>>> ga
<zarr.hierarchy.Group '/'>
>>> gr = zarr.open(store, mode='r') # open existing group read-only
>>> gr
<zarr.hierarchy.Group '/' read-only>
"""
path = kwargs.get('path', None)
# handle polymorphic store arg
clobber = mode == 'w'
# we pass storage options explicitly, since normalize_store_arg might construct
# a store if the input is a fsspec-compatible URL
_store: BaseStore = normalize_store_arg(store,
clobber=clobber,
storage_options=kwargs.pop(
"storage_options", {}))
path = normalize_storage_path(path)
if mode in {'w', 'w-', 'x'}:
if 'shape' in kwargs:
return open_array(_store, mode=mode, **kwargs)
else:
return open_group(_store, mode=mode, **kwargs)
elif mode == "a":
if "shape" in kwargs or contains_array(_store, path):
return open_array(_store, mode=mode, **kwargs)
else:
return open_group(_store, mode=mode, **kwargs)
else:
if contains_array(_store, path):
return open_array(_store, mode=mode, **kwargs)
elif contains_group(_store, path):
return open_group(_store, mode=mode, **kwargs)
else:
raise PathNotFoundError(path)
def open(store, mode='a', **kwargs):
"""Convenience function to open a group or array using file-mode-like semantics.
Parameters
----------
store : MutableMapping or string
Store or path to directory in file system or name of zip file.
mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
Persistence mode: 'r' means read only (must exist); 'r+' means
read/write (must exist); 'a' means read/write (create if doesn't
exist); 'w' means create (overwrite if exists); 'w-' means create
(fail if exists).
**kwargs
Additional parameters are passed through to :func:`zarr.open_array` or
:func:`zarr.open_group`.
See Also
--------
zarr.open_array, zarr.open_group
Examples
--------
Storing data in a directory 'data/example.zarr' on the local file system::
>>> import zarr
>>> store = 'data/example.zarr'
>>> zw = zarr.open(store, mode='w', shape=100, dtype='i4') # open new array
>>> zw
<zarr.core.Array (100,) int32>
>>> za = zarr.open(store, mode='a') # open existing array for reading and writing
>>> za
<zarr.core.Array (100,) int32>
>>> zr = zarr.open(store, mode='r') # open existing array read-only
>>> zr
<zarr.core.Array (100,) int32 read-only>
>>> gw = zarr.open(store, mode='w') # open new group, overwriting previous data
>>> gw
<zarr.hierarchy.Group '/'>
>>> ga = zarr.open(store, mode='a') # open existing group for reading and writing
>>> ga
<zarr.hierarchy.Group '/'>
>>> gr = zarr.open(store, mode='r') # open existing group read-only
>>> gr
<zarr.hierarchy.Group '/' read-only>
"""
path = kwargs.get('path', None)
# handle polymorphic store arg
store = normalize_store_arg(store, clobber=(mode == 'w'))
path = normalize_storage_path(path)
if mode in {'w', 'w-', 'x'}:
if 'shape' in kwargs:
return open_array(store, mode=mode, **kwargs)
else:
return open_group(store, mode=mode, **kwargs)
elif mode == 'a':
if contains_array(store, path):
return open_array(store, mode=mode, **kwargs)
elif contains_group(store, path):
return open_group(store, mode=mode, **kwargs)
elif 'shape' in kwargs:
return open_array(store, mode=mode, **kwargs)
else:
return open_group(store, mode=mode, **kwargs)
else:
if contains_array(store, path):
return open_array(store, mode=mode, **kwargs)
elif contains_group(store, path):
return open_group(store, mode=mode, **kwargs)
else:
err_path_not_found(path)
def test_open_array():
store = 'example'
# mode == 'w'
z = open_array(store, mode='w', shape=100, chunks=10)
z[:] = 42
assert_is_instance(z, Array)
assert_is_instance(z.store, DirectoryStore)
eq((100, ), z.shape)
eq((10, ), z.chunks)
assert_array_equal(np.full(100, fill_value=42), z[:])
# mode in 'r', 'r+'
open_group('example_group', mode='w')
for mode in 'r', 'r+':
with assert_raises(KeyError):
open_array('doesnotexist', mode=mode)
with assert_raises(KeyError):
open_array('example_group', mode=mode)
z = open_array(store, mode='r')
assert_is_instance(z, Array)
assert_is_instance(z.store, DirectoryStore)
eq((100, ), z.shape)
eq((10, ), z.chunks)
assert_array_equal(np.full(100, fill_value=42), z[:])
with assert_raises(PermissionError):
z[:] = 43
z = open_array(store, mode='r+')
assert_is_instance(z, Array)
assert_is_instance(z.store, DirectoryStore)
eq((100, ), z.shape)
eq((10, ), z.chunks)
assert_array_equal(np.full(100, fill_value=42), z[:])
z[:] = 43
assert_array_equal(np.full(100, fill_value=43), z[:])
# mode == 'a'
shutil.rmtree(store)
z = open_array(store, mode='a', shape=100, chunks=10)
z[:] = 42
assert_is_instance(z, Array)
assert_is_instance(z.store, DirectoryStore)
eq((100, ), z.shape)
eq((10, ), z.chunks)
assert_array_equal(np.full(100, fill_value=42), z[:])
with assert_raises(KeyError):
open_array('example_group', mode='a')
# mode in 'w-', 'x'
for mode in 'w-', 'x':
shutil.rmtree(store)
z = open_array(store, mode=mode, shape=100, chunks=10)
z[:] = 42
assert_is_instance(z, Array)
assert_is_instance(z.store, DirectoryStore)
eq((100, ), z.shape)
eq((10, ), z.chunks)
assert_array_equal(np.full(100, fill_value=42), z[:])
with assert_raises(KeyError):
open_array(store, mode=mode)
with assert_raises(KeyError):
open_array('example_group', mode=mode)
# with synchronizer
z = open_array(store, synchronizer=ThreadSynchronizer())
assert_is_instance(z, Array)
# with path
z = open_array(store, shape=100, path='foo/bar', mode='w')
assert_is_instance(z, Array)
eq('foo/bar', z.path)
def open(store, mode='a', **kwargs):
"""Convenience function to open a group or array using file-mode-like semantics.
Parameters
----------
store : MutableMapping or string
Store or path to directory in file system or name of zip file.
mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
Persistence mode: 'r' means read only (must exist); 'r+' means
read/write (must exist); 'a' means read/write (create if doesn't
exist); 'w' means create (overwrite if exists); 'w-' means create
(fail if exists).
**kwargs
Additional parameters are passed through to :func:`zarr.open_array` or
:func:`zarr.open_group`.
See Also
--------
zarr.open_array, zarr.open_group
Examples
--------
Storing data in a directory 'data/example.zarr' on the local file system::
>>> import zarr
>>> store = 'data/example.zarr'
>>> zw = zarr.open(store, mode='w', shape=100, dtype='i4') # open new array
>>> zw
<zarr.core.Array (100,) int32>
>>> za = zarr.open(store, mode='a') # open existing array for reading and writing
>>> za
<zarr.core.Array (100,) int32>
>>> zr = zarr.open(store, mode='r') # open existing array read-only
>>> zr
<zarr.core.Array (100,) int32 read-only>
>>> gw = zarr.open(store, mode='w') # open new group, overwriting previous data
>>> gw
<zarr.hierarchy.Group '/'>
>>> ga = zarr.open(store, mode='a') # open existing group for reading and writing
>>> ga
<zarr.hierarchy.Group '/'>
>>> gr = zarr.open(store, mode='r') # open existing group read-only
>>> gr
<zarr.hierarchy.Group '/' read-only>
"""
path = kwargs.get('path', None)
# handle polymorphic store arg
store = normalize_store_arg(store, clobber=(mode == 'w'))
path = normalize_storage_path(path)
if mode in {'w', 'w-', 'x'}:
if 'shape' in kwargs:
return open_array(store, mode=mode, **kwargs)
else:
return open_group(store, mode=mode, **kwargs)
elif mode == 'a':
if contains_array(store, path):
return open_array(store, mode=mode, **kwargs)
elif contains_group(store, path):
return open_group(store, mode=mode, **kwargs)
elif 'shape' in kwargs:
return open_array(store, mode=mode, **kwargs)
else:
return open_group(store, mode=mode, **kwargs)
else:
if contains_array(store, path):
return open_array(store, mode=mode, **kwargs)
elif contains_group(store, path):
return open_group(store, mode=mode, **kwargs)
else:
err_path_not_found(path)
def test_open_array_none():
# open with both store and zarr_version = None
z = open_array(mode='w', shape=100, chunks=10)
assert isinstance(z, Array)
assert z._version == 2
def test_open_array(zarr_version, dimension_separator):
store = 'data/array.zarr'
kwargs = _init_creation_kwargs(zarr_version)
# mode == 'w'
z = open_array(store,
mode='w',
shape=100,
chunks=10,
dimension_separator=dimension_separator,
**kwargs)
z[:] = 42
assert isinstance(z, Array)
if z._store._store_version == 2:
assert isinstance(z.store, DirectoryStore)
else:
assert isinstance(z.store, DirectoryStoreV3)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
if dimension_separator is None:
assert z._dimension_separator == '/' if zarr_version == 3 else '.'
else:
assert z._dimension_separator == dimension_separator
# mode in 'r', 'r+'
group_kwargs = kwargs.copy()
if zarr_version == 3:
group_kwargs['path'] = 'group'
open_group('data/group.zarr', mode='w', **group_kwargs)
for mode in 'r', 'r+':
with pytest.raises(ValueError):
open_array('doesnotexist', mode=mode)
with pytest.raises(ValueError):
open_array('data/group.zarr', mode=mode)
z = open_array(store, mode='r', **kwargs)
assert isinstance(z, Array)
if z._store._store_version == 2:
assert isinstance(z.store, DirectoryStore)
else:
assert isinstance(z.store, DirectoryStoreV3)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
with pytest.raises(PermissionError):
z[:] = 43
z = open_array(store, mode='r+', **kwargs)
assert isinstance(z, Array)
if z._store._store_version == 2:
assert isinstance(z.store, DirectoryStore)
else:
assert isinstance(z.store, DirectoryStoreV3)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
z[:] = 43
assert_array_equal(np.full(100, fill_value=43), z[:])
# mode == 'a'
shutil.rmtree(store)
z = open_array(store, mode='a', shape=100, chunks=10, **kwargs)
z[:] = 42
assert isinstance(z, Array)
if z._store._store_version == 2:
assert isinstance(z.store, DirectoryStore)
else:
assert isinstance(z.store, DirectoryStoreV3)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
expected_error = TypeError if zarr_version == 3 else ValueError
# v3 path does not conflict, but will raise TypeError without shape kwarg
with pytest.raises(expected_error):
# array would end up at data/group.zarr/meta/root/array.array.json
open_array('data/group.zarr', mode='a', **kwargs)
# mode in 'w-', 'x'
for mode in 'w-', 'x':
shutil.rmtree(store)
z = open_array(store, mode=mode, shape=100, chunks=10, **kwargs)
z[:] = 42
assert isinstance(z, Array)
if z._store._store_version == 2:
assert isinstance(z.store, DirectoryStore)
else:
assert isinstance(z.store, DirectoryStoreV3)
assert (100, ) == z.shape
assert (10, ) == z.chunks
assert_array_equal(np.full(100, fill_value=42), z[:])
with pytest.raises(ValueError):
open_array(store, mode=mode, **kwargs)
expected_error = TypeError if zarr_version == 3 else ValueError
# v3 path does not conflict, but will raise TypeError without shape kwarg
with pytest.raises(expected_error):
open_array('data/group.zarr', mode=mode, **kwargs)
# with synchronizer
z = open_array(store, synchronizer=ThreadSynchronizer(), **kwargs)
assert isinstance(z, Array)
# with path
kwargs_no_path = kwargs.copy()
kwargs_no_path.pop('path', None)
z = open_array(store,
shape=100,
path='foo/bar',
mode='w',
**kwargs_no_path)
assert isinstance(z, Array)
assert 'foo/bar' == z.path
# with chunk store
meta_store = 'data/meta.zarr'
chunk_store = 'data/chunks.zarr'
z = open_array(store=meta_store,
chunk_store=chunk_store,
shape=11,
mode='w',
**kwargs)
z[:] = 42
assert os.path.abspath(meta_store) == z.store.path
assert os.path.abspath(chunk_store) == z.chunk_store.path