documentation

Author: alimanfoo

docs/api/creation.rst

@@ -7,7 +7,7 @@ Array creation (``zarr.creation``)
 .. autofunction:: ones
 .. autofunction:: full
 .. autofunction:: array
-.. autofunction:: open
+.. autofunction:: open_array
 .. autofunction:: empty_like
 .. autofunction:: zeros_like
 .. autofunction:: ones_like

docs/api/hierarchy.rst

@@ -7,8 +7,31 @@ Groups (``zarr.hierarchy``)
 
 .. autoclass:: Group
 
+    .. automethod:: __len__
+    .. automethod:: __contains__
     .. automethod:: __getitem__
+    .. automethod:: __setitem__
+    .. automethod:: __iter__
+    .. automethod:: keys
+    .. automethod:: values
+    .. automethod:: items
+    .. automethod:: group_keys
+    .. automethod:: groups
+    .. automethod:: array_keys
+    .. automethod:: arrays
     .. automethod:: create_group
     .. automethod:: require_group
+    .. automethod:: create_groups
+    .. automethod:: require_groups
     .. automethod:: create_dataset
     .. automethod:: require_dataset
+    .. automethod:: create
+    .. automethod:: empty
+    .. automethod:: zeros
+    .. automethod:: ones
+    .. automethod:: full
+    .. automethod:: array
+    .. automethod:: empty_like
+    .. automethod:: zeros_like
+    .. automethod:: ones_like
+    .. automethod:: full_like

docs/index.rst

@@ -16,6 +16,7 @@ Highlights
 * Store arrays in memory, on disk, inside a Zip file, on S3, ...
 * Read an array concurrently from multiple threads or processes.
 * Write to an array concurrently from multiple threads or processes.
+* Organize arrays into hierarchies via groups.
 
 Status
 ------

docs/release.rst

@@ -1,6 +1,21 @@
 Release notes
 =============
 
+.. _release_2.0.0:
+
+2.0.0
+-----
+
+Hierarchies
+~~~~~~~~~~~
+
+Support has been added for organizing arrays into hierarchies via groups. See
+the tutorial section on :ref:`tutorial_groups` and the :mod:`zarr.hierarchy`
+API docs for more information.
+
+To accommodate support for hierarchies the Zarr format has been modified. See
+the :ref:`spec_v2` for more information.
+
 .. _release_1.1.0:
 
 1.1.0

docs/spec/v2.rst

@@ -193,7 +193,7 @@ file system).
 Groups
 ~~~~~~
 
-Arrays can be organised into groups which can also contain other groups. A 
+Arrays can be organized into groups which can also contain other groups. A
 group is created by storing group metadata under the '.zgroup' key under some 
 logical path. E.g., a group exists at the root of an array store if the 
 '.zgroup' key exists in the store, and a group exists at logical path 'foo/bar' 

docs/tutorial.rst

@@ -178,7 +178,7 @@ and can be configured in a variety of ways to improve the compression
 ratio for different types of data. Blosc is in fact a
 "meta-compressor", which means that it can used a number of different
 compression algorithms internally to compress the data. Blosc also
-provides highly optimised implementations of byte and bit shuffle
+provides highly optimized implementations of byte and bit shuffle
 filters, which can significantly improve compression ratios for some
 data.
 

zarr/compressors.py

@@ -138,7 +138,7 @@ def normalize_opts(cls, compression_opts):
             if shuffle not in [0, 1, 2]:
                 raise ValueError('invalid shuffle: %s' % shuffle)
 
-            # construct normalised options
+            # construct normalized options
             compression_opts = dict(
                 cname=cname, clevel=clevel, shuffle=shuffle
             )

zarr/core.py

@@ -1,6 +1,5 @@
 # -*- coding: utf-8 -*-
 from __future__ import absolute_import, print_function, division
-from functools import reduce  # TODO PY2 compatibility
 import operator
 import itertools
 
@@ -17,21 +16,25 @@
 from zarr.meta import decode_array_metadata, encode_array_metadata
 from zarr.attrs import Attributes
 from zarr.errors import ReadOnlyError
+from zarr.compat import reduce
 
 
 class Array(object):
-    """Instantiate an array from an initialised store.
+    """Instantiate an array from an initialized store.
 
     Parameters
     ----------
     store : MutableMapping
-        Array store, already initialised.
+        Array store, already initialized.
+    path : string, optional
+        Storage path.
     readonly : bool, optional
         True if array should be protected against modification.
 
     Attributes
     ----------
     store
+    path
     name
     readonly
     shape
@@ -56,23 +59,11 @@ class Array(object):
     resize
     append
 
-    Examples
-    --------
-    >>> import zarr
-    >>> store = dict()
-    >>> zarr.init_array(store, shape=(10000, 10000), chunks=(1000, 1000))
-    >>> z = zarr.Array(store)
-    >>> z
-    zarr.core.Array((10000, 10000), float64, chunks=(1000, 1000), order=C)
-      compression: blosc; compression_opts: {'clevel': 5, 'cname': 'lz4', 'shuffle': 1}
-      nbytes: 762.9M; nbytes_stored: 316; ratio: 2531645.6; initialized: 0/100
-      store: builtins.dict
-
     """  # flake8: noqa
 
     def __init__(self, store, path=None, readonly=False):
-        # N.B., expect at this point store is fully initialised with all
-        # configuration metadata fully specified and normalised
+        # N.B., expect at this point store is fully initialized with all
+        # configuration metadata fully specified and normalized
 
         self._store = store
         self._path = normalize_storage_path(path)
@@ -82,7 +73,7 @@ def __init__(self, store, path=None, readonly=False):
             self._key_prefix = ''
         self._readonly = readonly
 
-        # initialise metadata
+        # initialize metadata
         try:
             mkey = self._key_prefix + array_meta_key
             meta_bytes = store[mkey]
@@ -101,7 +92,7 @@ def __init__(self, store, path=None, readonly=False):
             compressor_cls = get_compressor_cls(self._compression)
             self._compressor = compressor_cls(self._compression_opts)
 
-        # initialise attributes
+        # initialize attributes
         akey = self._key_prefix + attrs_key
         self._attrs = Attributes(store, key=akey, readonly=readonly)
 
@@ -120,12 +111,12 @@ def store(self):
 
     @property
     def path(self):
-        """TODO doc me"""
+        """Storage path."""
         return self._path
 
     @property
     def name(self):
-        """TODO doc me"""
+        """Array name following h5py convention."""
         if self.path:
             # follow h5py convention: add leading slash
             name = self.path
@@ -136,7 +127,7 @@ def name(self):
 
     @property
     def readonly(self):
-        """A boolean, True if write operations are not permitted."""
+        """A boolean, True if modification operations are not permitted."""
         return self._readonly
 
     @property

zarr/creation.py

@@ -31,7 +31,7 @@ def create(shape, chunks, dtype=None, compression='default',
         Options to primary compressor. E.g., for blosc, provide a dictionary
         with keys 'cname', 'clevel' and 'shuffle'.
     fill_value : object
-        Default value to use for uninitialised portions of the array.
+        Default value to use for uninitialized portions of the array.
     order : {'C', 'F'}, optional
         Memory layout to be used within each chunk.
     store : MutableMapping, optional
@@ -64,7 +64,7 @@ def create(shape, chunks, dtype=None, compression='default',
 
     """  # flake8: noqa
 
-    # initialise store
+    # initialize store
     if store is None:
         store = dict()
     init_array(store, shape=shape, chunks=chunks, dtype=dtype,
@@ -105,7 +105,7 @@ def zeros(shape, chunks, dtype=None, compression='default',
           compression_opts=None, order='C', store=None, synchronizer=None,
           path=None, overwrite=False):
     """Create an array, with zero being used as the default value for
-    uninitialised portions of the array.
+    uninitialized portions of the array.
 
     For parameter definitions see :func:`zarr.creation.create`.
 
@@ -135,7 +135,7 @@ def ones(shape, chunks, dtype=None, compression='default',
          compression_opts=None, order='C', store=None, synchronizer=None,
          path=None, overwrite=False):
     """Create an array, with one being used as the default value for
-    uninitialised portions of the array.
+    uninitialized portions of the array.
 
     For parameter definitions see :func:`zarr.creation.create`.
 
@@ -164,7 +164,7 @@ def full(shape, chunks, fill_value, dtype=None, compression='default',
          compression_opts=None, order='C', store=None, synchronizer=None,
          path=None, overwrite=False):
     """Create an array, with `fill_value` being used as the default value for
-    uninitialised portions of the array.
+    uninitialized portions of the array.
 
     For parameter definitions see :func:`zarr.creation.create`.
 
@@ -246,11 +246,11 @@ def array(data, chunks=None, dtype=None, compression='default',
     return z
 
 
-# noinspection PyShadowingBuiltins
 def open_array(path, mode='a', shape=None, chunks=None, dtype=None,
                compression='default', compression_opts=None, fill_value=0,
                order='C', synchronizer=None):
-    """Open an array stored in a directory on the file system.
+    """Convenience function to instantiate an array stored in a
+    directory on the file system.
 
     Parameters
     ----------
@@ -274,7 +274,7 @@ def open_array(path, mode='a', shape=None, chunks=None, dtype=None,
         Options to primary compressor. E.g., for blosc, provide a dictionary
         with keys 'cname', 'clevel' and 'shuffle'.
     fill_value : object
-        Default value to use for uninitialised portions of the array.
+        Default value to use for uninitialized portions of the array.
     order : {'C', 'F'}, optional
         Memory layout to be used within each chunk.
     synchronizer : zarr.sync.ArraySynchronizer, optional
@@ -288,15 +288,15 @@ def open_array(path, mode='a', shape=None, chunks=None, dtype=None,
     --------
     >>> import numpy as np
     >>> import zarr
-    >>> z1 = zarr.open('example.zarr', mode='w', shape=(10000, 10000),
-    ...                chunks=(1000, 1000), fill_value=0)
+    >>> z1 = zarr.open_array('example.zarr', mode='w', shape=(10000, 10000),
+    ...                      chunks=(1000, 1000), fill_value=0)
     >>> z1[:] = np.arange(100000000).reshape(10000, 10000)
     >>> z1
     zarr.core.Array((10000, 10000), float64, chunks=(1000, 1000), order=C)
       compression: blosc; compression_opts: {'clevel': 5, 'cname': 'lz4', 'shuffle': 1}
       nbytes: 762.9M; nbytes_stored: 24.8M; ratio: 30.8; initialized: 100/100
       store: zarr.storage.DirectoryStore
-    >>> z2 = zarr.open('example.zarr', mode='r')
+    >>> z2 = zarr.open_array('example.zarr', mode='r')
     >>> z2
     zarr.core.Array((10000, 10000), float64, chunks=(1000, 1000), order=C)
       compression: blosc; compression_opts: {'clevel': 5, 'cname': 'lz4', 'shuffle': 1}