doco; repr tweaks

Author: alimanfoo

README.rst

@@ -42,18 +42,18 @@ Create an array::
 
     >>> import numpy as np
     >>> import zarr
-    >>> z = zarr.empty((10000, 1000), dtype='i4', chunks=(1000, 100))
+    >>> z = zarr.empty(shape=(10000, 1000), dtype='i4', chunks=(1000, 100))
     >>> z
     zarr.ext.SynchronizedArray((10000, 1000), int32, chunks=(1000, 100))
-      cname: 'blosclz'; clevel: 5; shuffle: 1 (BYTESHUFFLE)
+      cname: blosclz; clevel: 5; shuffle: 1 (BYTESHUFFLE)
       nbytes: 38.1M; cbytes: 0; initialized: 0/100
 
 Fill it with some data::
 
     >>> z[:] = np.arange(10000000, dtype='i4').reshape(10000, 1000)
     >>> z
     zarr.ext.SynchronizedArray((10000, 1000), int32, chunks=(1000, 100))
-      cname: 'blosclz'; clevel: 5; shuffle: 1 (BYTESHUFFLE)
+      cname: blosclz; clevel: 5; shuffle: 1 (BYTESHUFFLE)
       nbytes: 38.1M; cbytes: 2.0M; ratio: 19.3; initialized: 100/100
 
 Obtain a NumPy array by slicing::
@@ -88,12 +88,12 @@ Resize the array and add more data::
     >>> z.resize(20000, 1000)
     >>> z
     zarr.ext.SynchronizedArray((20000, 1000), int32, chunks=(1000, 100))
-      cname: 'blosclz'; clevel: 5; shuffle: 1 (BYTESHUFFLE)
+      cname: blosclz; clevel: 5; shuffle: 1 (BYTESHUFFLE)
       nbytes: 76.3M; cbytes: 2.0M; ratio: 38.5; initialized: 100/200
     >>> z[10000:, :] = np.arange(10000000, dtype='i4').reshape(10000, 1000)
     >>> z
     zarr.ext.SynchronizedArray((20000, 1000), int32, chunks=(1000, 100))
-      cname: 'blosclz'; clevel: 5; shuffle: 1 (BYTESHUFFLE)
+      cname: blosclz; clevel: 5; shuffle: 1 (BYTESHUFFLE)
       nbytes: 76.3M; cbytes: 4.0M; ratio: 19.3; initialized: 200/200
 
 For convenience, an ``append()`` method is also available, which can be used to
@@ -103,19 +103,34 @@ append data to any axis::
     >>> z = zarr.array(a, chunks=(1000, 100))
     >>> z
     zarr.ext.SynchronizedArray((10000, 1000), int32, chunks=(1000, 100))
-      cname: 'blosclz'; clevel: 5; shuffle: 1 (BYTESHUFFLE)
+      cname: blosclz; clevel: 5; shuffle: 1 (BYTESHUFFLE)
       nbytes: 38.1M; cbytes: 2.0M; ratio: 19.3; initialized: 100/100
     >>> z.append(a+a)
     >>> z
     zarr.ext.SynchronizedArray((20000, 1000), int32, chunks=(1000, 100))
-      cname: 'blosclz'; clevel: 5; shuffle: 1 (BYTESHUFFLE)
+      cname: blosclz; clevel: 5; shuffle: 1 (BYTESHUFFLE)
       nbytes: 76.3M; cbytes: 3.6M; ratio: 21.2; initialized: 200/200
     >>> z.append(np.vstack([a, a]), axis=1)
     >>> z
     zarr.ext.SynchronizedArray((20000, 2000), int32, chunks=(1000, 100))
-      cname: 'blosclz'; clevel: 5; shuffle: 1 (BYTESHUFFLE)
+      cname: blosclz; clevel: 5; shuffle: 1 (BYTESHUFFLE)
       nbytes: 152.6M; cbytes: 7.6M; ratio: 20.2; initialized: 400/400
 
+Create a persistent array (data saved to disk)::
+
+    >>> import tempfile
+    >>> path = 'example.zarr'
+    >>> z = zarr.open(path, shape=(10000, 1000), dtype='i4', chunks=(1000, 100))
+    >>> z[:] = np.arange(10000000, dtype='i4').reshape(10000, 1000)
+    >>> z
+    zarr.ext.PersistentArray((10000, 1000), int32, chunks=(1000, 100))
+      cname: blosclz; clevel: 5; shuffle: 1 (BYTESHUFFLE)
+      nbytes: 38.1M; cbytes: 2.0M; ratio: 19.3; initialized: 100/100
+      mode: a; path: example.zarr
+
+There is no need to close a persistent array. Data are automatically flushed
+to disk.
+
 Tuning
 ------
 

zarr/__init__.py

@@ -2,7 +2,7 @@
 from __future__ import absolute_import, print_function, division
 
 
-from zarr.core import empty, zeros, ones, full, array
+from zarr.core import empty, zeros, ones, full, array, open
 from zarr import defaults
 from zarr import constants
 from zarr.version import version as __version__

zarr/core.py

@@ -231,3 +231,15 @@ def array(data, chunks=None, dtype=None, cname=None, clevel=None,
     z[:] = data
 
     return z
+
+
+def open(path, mode='a', shape=None, chunks=None, dtype=None, cname=None,
+         clevel=None, shuffle=None, fill_value=None):
+    """TODO"""
+
+    # TODO synchronized option
+
+    cls = _ext.PersistentArray
+    return cls(path=path, mode=mode, shape=shape, chunks=chunks, dtype=dtype,
+               cname=cname, clevel=clevel, shuffle=shuffle,
+               fill_value=fill_value)

zarr/ext.pyx

@@ -869,7 +869,7 @@ cdef class BaseArray:
         r += ', %s' % str(self._dtype)
         r += ', chunks=%s' % str(self._chunks)
         r += ')'
-        r += '\n  cname: %r' % str(self._cname, 'ascii')
+        r += '\n  cname: %s' % str(self._cname, 'ascii')
         r += '; clevel: %s' % self._clevel
         r += '; shuffle: %s' % _repr_shuffle[self._shuffle]
         r += '\n  nbytes: %s' % _util.human_readable_size(self.nbytes)
@@ -1171,7 +1171,7 @@ cdef class PersistentArray(BaseArray):
             self._cdata[cidx] = self.create_chunk(cidx)
 
     def _create(self, path, shape=None, chunks=None, dtype=None,
-               cname=None, clevel=None, shuffle=None, fill_value=None):
+                cname=None, clevel=None, shuffle=None, fill_value=None):
 
         # create directories
         data_path = os.path.join(path, defaults.datapath)
@@ -1289,7 +1289,7 @@ cdef class PersistentArray(BaseArray):
 
     def __repr__(self):
         r = super(PersistentArray, self).__repr__()
-        r += '\n  path: %s' % self._path
+        r += '\n  mode: %s; path: %s' % (self._mode, self._path)
         return r
 
     def iter_chunks(self):