fix API docs for lru store cache

Author: alimanfoo

docs/api/storage.rst

@@ -23,8 +23,9 @@ Storage (``zarr.storage``)
 
 .. autoclass:: LRUStoreCache
 
-    .. automethod:: clear_values
-    .. automethod:: clear_keys
+    .. automethod:: invalidate
+    .. automethod:: invalidate_values
+    .. automethod:: invalidate_keys
 
 .. autofunction:: init_array
 .. autofunction:: init_group

zarr/storage.py

@@ -1732,8 +1732,14 @@ class LRUStoreCache(MutableMapping):
         >>> root = zarr.group(store=cache)
         >>> z = root['foo/bar/baz']
         >>> from timeit import timeit
-        >>> timeit('print(z.tostring())', number=1)  # first time is relatively slow
-        >>> timeit('print(z.tostring())', number=1)  # second time is fast, uses cache
+        >>> # first data access is relatively slow, retrieved from store
+        ... timeit('print(z[:].tostring())', number=1, globals=globals())  # doctest: +SKIP
+        b'Hello from the cloud!'
+        0.1081731989979744
+        >>> # second data access is faster, uses cache
+        ... timeit('print(z[:].tostring())', number=1, globals=globals())  # doctest: +SKIP
+        b'Hello from the cloud!'
+        0.0009490990014455747
 
     """
 
@@ -1760,7 +1766,7 @@ def __setstate__(self, state):
         self._mutex = Lock()
 
     def __len__(self):
-        return len(self._store)
+        return len(self._keys())
 
     def __iter__(self):
         return self.keys()
@@ -1771,14 +1777,18 @@ def __contains__(self, key):
                 self._contains_cache = set(self._keys())
             return key in self._contains_cache
 
+    def clear(self):
+        self._store.clear()
+        self.invalidate()
+
     def keys(self):
         with self._mutex:
-            return self._keys()
+            return iter(self._keys())
 
     def _keys(self):
         if self._keys_cache is None:
             self._keys_cache = list(self._store.keys())
-        return iter(self._keys_cache)
+        return self._keys_cache
 
     def listdir(self, path=None):
         with self._mutex:
@@ -1816,22 +1826,28 @@ def _cache_value(self, key, value):
             self._values_cache[key] = value
             self._current_size += value_size
 
-    def clear_values(self):
+    def invalidate(self):
+        """Completely clear the cache."""
+        with self._mutex:
+            self._values_cache.clear()
+            self._invalidate_keys()
+
+    def invalidate_values(self):
         """Clear the values cache."""
         with self._mutex:
             self._values_cache.clear()
 
-    def clear_keys(self):
+    def invalidate_keys(self):
         """Clear the keys cache."""
         with self._mutex:
-            self._clear_keys()
+            self._invalidate_keys()
 
-    def _clear_keys(self):
+    def _invalidate_keys(self):
         self._keys_cache = None
         self._contains_cache = None
         self._listdir_cache.clear()
 
-    def _clear_value(self, key):
+    def _invalidate_value(self, key):
         if key in self._values_cache:
             value = self._values_cache.pop(key)
             self._current_size -= buffer_size(value)
@@ -1861,12 +1877,12 @@ def __getitem__(self, key):
     def __setitem__(self, key, value):
         self._store[key] = value
         with self._mutex:
-            self._clear_keys()
-            self._clear_value(key)
+            self._invalidate_keys()
+            self._invalidate_value(key)
             self._cache_value(key, value)
 
     def __delitem__(self, key):
         del self._store[key]
         with self._mutex:
-            self._clear_keys()
-            self._clear_value(key)
+            self._invalidate_keys()
+            self._invalidate_value(key)

zarr/tests/test_storage.py

@@ -889,11 +889,15 @@ def test_cache_values_no_max_size(self):
         assert 2 == cache.hits
         assert 1 == cache.misses
 
-        # manually clear all cached values
-        cache.clear_values()
+        # manually invalidate all cached values
+        cache.invalidate_values()
         assert b'zzz' == cache['foo']
         assert 2 == store.counter['__getitem__', 'foo']
         assert 2 == store.counter['__setitem__', 'foo']
+        cache.invalidate()
+        assert b'zzz' == cache['foo']
+        assert 3 == store.counter['__getitem__', 'foo']
+        assert 2 == store.counter['__setitem__', 'foo']
 
         # test __delitem__
         del cache['foo']
@@ -1037,20 +1041,20 @@ def test_cache_keys(self):
         assert keys == sorted(cache.keys())
         assert 2 == store.counter['keys']
 
-        # manually clear keys
-        cache.clear_keys()
+        # manually invalidate keys
+        cache.invalidate_keys()
         keys = sorted(cache.keys())
         assert keys == ['bar', 'baz', 'foo']
         assert 3 == store.counter['keys']
         assert 0 == store.counter['__contains__', 'foo']
         assert 0 == store.counter['__iter__']
-        cache.clear_keys()
+        cache.invalidate_keys()
         keys = sorted(cache)
         assert keys == ['bar', 'baz', 'foo']
         assert 4 == store.counter['keys']
         assert 0 == store.counter['__contains__', 'foo']
         assert 0 == store.counter['__iter__']
-        cache.clear_keys()
+        cache.invalidate_keys()
         assert 'foo' in cache
         assert 5 == store.counter['keys']
         assert 0 == store.counter['__contains__', 'foo']