Hierarchical storage

.gitignore

@@ -66,3 +66,5 @@ zarr/version.py
 *.zarr
 *~
 *.zip
+example*
+doesnotexist

docs/api.rst

@@ -6,6 +6,7 @@ API reference
 
     api/creation
     api/core
+    api/hierarchy
     api/storage
     api/compressors
     api/sync

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

@@ -0,0 +1,33 @@
+Groups (``zarr.hierarchy``)
+===========================
+.. module:: zarr.hierarchy
+
+.. autofunction:: group
+.. autofunction:: open_group
+
+.. autoclass:: Group
+
+    .. automethod:: __len__
+    .. automethod:: __iter__
+    .. automethod:: __contains__
+    .. automethod:: __getitem__
+    .. 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/api/storage.rst

@@ -2,11 +2,13 @@ Storage (``zarr.storage``)
 ==========================
 .. module:: zarr.storage
 
-This module contains a single :class:`DirectoryStore` class providing
-a ``MutableMapping`` interface to a directory on the file
-system. However, note that any object implementing the
-``MutableMapping`` interface can be used as a Zarr array store.
+This module contains storage classes for use with Zarr arrays and groups.
+However, note that any object implementing the ``MutableMapping`` interface
+can be used as a Zarr array store.
 
-.. autofunction:: init_store
+.. autofunction:: init_array
+.. autofunction:: init_group
 
+.. autoclass:: DictStore
 .. autoclass:: DirectoryStore
+.. autoclass:: ZipStore

docs/api/sync.rst

@@ -4,4 +4,3 @@ Synchronization (``zarr.sync``)
 
 .. autoclass:: ThreadSynchronizer
 .. autoclass:: ProcessSynchronizer
-.. autoclass:: SynchronizedArray

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.rst

@@ -1,7 +1,10 @@
+.. _spec:
+
 Specifications
 ==============
 
 .. toctree::
     :maxdepth: 3
 
     spec/v1
+    spec/v2

docs/spec/v1.rst

@@ -10,6 +10,11 @@ NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
 interpreted as described in `RFC 2119
 <https://www.ietf.org/rfc/rfc2119.txt>`_.
 
+Status
+------
+
+This specification is deprecated. See :ref:`spec` for the latest version.
+
 Storage
 -------