document attributes

Author: alimanfoo

docs/api.rst

@@ -8,6 +8,7 @@ API reference
     api/core
     api/hierarchy
     api/storage
+    api/convenience
     api/codecs
+    api/attrs
     api/sync
-    api/convenience

docs/api/attrs.rst

@@ -0,0 +1,15 @@
+The Attributes class (``zarr.attrs``)
+=====================================
+.. module:: zarr.attrs
+
+.. autoclass:: Attributes
+
+    .. automethod:: __getitem__
+    .. automethod:: __setitem__
+    .. automethod:: __delitem__
+    .. automethod:: __iter__
+    .. automethod:: __len__
+    .. automethod:: keys
+    .. automethod:: asdict
+    .. automethod:: put
+    .. automethod:: update

zarr/attrs.py

@@ -11,7 +11,22 @@
 class Attributes(MutableMapping):
     """Class providing access to user attributes on an array or group. Should not be
     instantiated directly, will be available via the `.attrs` property of an array or
-    group."""
+    group.
+
+    Parameters
+    ----------
+    store : MutableMapping
+        The store in which to store the attributes.
+    key : str, optional
+        The key under which the attributes will be stored.
+    read_only : bool, optional
+        If True, attributes cannot be modified.
+    cache : bool, optional
+        If True (default), attributes will be cached locally.
+    synchronizer : Synchronizer
+        Only necessary if attributes may be modified from multiple threads or processes.
+
+    """
 
     def __init__(self, store, key='.zattrs', read_only=False, cache=True,
                  synchronizer=None):

zarr/tests/test_attrs.py

@@ -115,66 +115,98 @@ def test_key_completions(self):
 
     def test_caching_on(self):
         # caching is turned on by default
+
+        # setup store
         store = CountingDict()
         eq(0, store.counter['__getitem__', 'attrs'])
         eq(0, store.counter['__setitem__', 'attrs'])
         store['attrs'] = json.dumps(dict(foo='xxx', bar=42)).encode('ascii')
         eq(0, store.counter['__getitem__', 'attrs'])
         eq(1, store.counter['__setitem__', 'attrs'])
+
+        # setup attributes
         a = self.init_attributes(store)
+
+        # test __getitem__ causes all attributes to be cached
         eq(a['foo'], 'xxx')
         eq(1, store.counter['__getitem__', 'attrs'])
         eq(a['bar'], 42)
         eq(1, store.counter['__getitem__', 'attrs'])
         eq(a['foo'], 'xxx')
         eq(1, store.counter['__getitem__', 'attrs'])
+
+        # test __setitem__ updates the cache
         a['foo'] = 'yyy'
         eq(2, store.counter['__getitem__', 'attrs'])
         eq(2, store.counter['__setitem__', 'attrs'])
         eq(a['foo'], 'yyy')
         eq(2, store.counter['__getitem__', 'attrs'])
         eq(2, store.counter['__setitem__', 'attrs'])
+
+        # test update() updates the cache
         a.update(foo='zzz', bar=84)
         eq(3, store.counter['__getitem__', 'attrs'])
         eq(3, store.counter['__setitem__', 'attrs'])
         eq(a['foo'], 'zzz')
         eq(a['bar'], 84)
         eq(3, store.counter['__getitem__', 'attrs'])
         eq(3, store.counter['__setitem__', 'attrs'])
+
+        # test __contains__ uses the cache
         assert 'foo' in a
         eq(3, store.counter['__getitem__', 'attrs'])
         eq(3, store.counter['__setitem__', 'attrs'])
         assert 'spam' not in a
         eq(3, store.counter['__getitem__', 'attrs'])
         eq(3, store.counter['__setitem__', 'attrs'])
 
+        # test __delitem__ updates the cache
+        del a['bar']
+        eq(4, store.counter['__getitem__', 'attrs'])
+        eq(4, store.counter['__setitem__', 'attrs'])
+        assert 'bar' not in a
+        eq(4, store.counter['__getitem__', 'attrs'])
+        eq(4, store.counter['__setitem__', 'attrs'])
+
     def test_caching_off(self):
+
+        # setup store
         store = CountingDict()
         eq(0, store.counter['__getitem__', 'attrs'])
         eq(0, store.counter['__setitem__', 'attrs'])
         store['attrs'] = json.dumps(dict(foo='xxx', bar=42)).encode('ascii')
         eq(0, store.counter['__getitem__', 'attrs'])
         eq(1, store.counter['__setitem__', 'attrs'])
+
+        # setup attributes
         a = self.init_attributes(store, cache=False)
+
+        # test __getitem__
         eq(a['foo'], 'xxx')
         eq(1, store.counter['__getitem__', 'attrs'])
         eq(a['bar'], 42)
         eq(2, store.counter['__getitem__', 'attrs'])
         eq(a['foo'], 'xxx')
         eq(3, store.counter['__getitem__', 'attrs'])
+
+        # test __setitem__
         a['foo'] = 'yyy'
         eq(4, store.counter['__getitem__', 'attrs'])
         eq(2, store.counter['__setitem__', 'attrs'])
         eq(a['foo'], 'yyy')
         eq(5, store.counter['__getitem__', 'attrs'])
         eq(2, store.counter['__setitem__', 'attrs'])
+
+        # test update()
         a.update(foo='zzz', bar=84)
         eq(6, store.counter['__getitem__', 'attrs'])
         eq(3, store.counter['__setitem__', 'attrs'])
         eq(a['foo'], 'zzz')
         eq(a['bar'], 84)
         eq(8, store.counter['__getitem__', 'attrs'])
         eq(3, store.counter['__setitem__', 'attrs'])
+
+        # test __contains__
         assert 'foo' in a
         eq(9, store.counter['__getitem__', 'attrs'])
         eq(3, store.counter['__setitem__', 'attrs'])