Use Error subclasses instead of functions. (#590)

I believe this has several advantage:

  1) reading the code it is obvious we are directly raising instead of
  doing more stuff.

  2) in traceback the last frame will be correct, so it's easier to find
  where the error occurs.

  3) All of these are now subclasses which can be caught independently
  by libraries while still being subclass of ValueError, so backward
  compatible. Can be caught without catching other ValueErrors.

  4) the name of the class is descriptive

I'm not too sure about some naming. Is ContainsXxxxError sufficient to
understand that it contain Xxxxx but Xxxx was not expected ?

Author: Carreau

docs/release.rst

@@ -17,6 +17,10 @@ Next release
 * Explicitly close stores during testing.
   By :user:`Elliott Sales de Andrade <QuLogic>`; :issue:`442`
 
+* Many of the convenience functions to emit errors (``err_*`` from
+  ``zarr.errors``  have been replaced by ``ValueError`` subclasses. The
+  functions are deprecated and will be removed in the future. :issue:`590` )
+
 * Improve consistency of terminology regarding arrays and datasets in the 
   documentation.
   By :user:`Josh Moore <joshmoore>`; :issue:`571`.

zarr/convenience.py

@@ -8,7 +8,7 @@
 from zarr.core import Array
 from zarr.creation import array as _create_array
 from zarr.creation import normalize_store_arg, open_array
-from zarr.errors import CopyError, err_path_not_found
+from zarr.errors import CopyError, PathNotFoundError
 from zarr.hierarchy import Group
 from zarr.hierarchy import group as _create_group
 from zarr.hierarchy import open_group
@@ -99,7 +99,7 @@ def open(store=None, mode='a', **kwargs):
         elif contains_group(store, path):
             return open_group(store, mode=mode, **kwargs)
         else:
-            err_path_not_found(path)
+            raise PathNotFoundError(path)
 
 
 def save_array(store, arr, **kwargs):

zarr/core.py

@@ -12,7 +12,7 @@
 
 from zarr.attrs import Attributes
 from zarr.codecs import AsType, get_codec
-from zarr.errors import err_array_not_found, err_read_only
+from zarr.errors import ArrayNotFoundError, ReadOnlyError
 from zarr.indexing import (BasicIndexer, CoordinateIndexer, MaskIndexer,
                            OIndex, OrthogonalIndexer, VIndex, check_fields,
                            check_no_multi_fields, ensure_tuple,
@@ -149,7 +149,7 @@ def _load_metadata_nosync(self):
             mkey = self._key_prefix + array_meta_key
             meta_bytes = self._store[mkey]
         except KeyError:
-            err_array_not_found(self._path)
+            raise ArrayNotFoundError(self._path)
         else:
 
             # decode and store metadata as instance members
@@ -1197,7 +1197,7 @@ def set_basic_selection(self, selection, value, fields=None):
 
         # guard conditions
         if self._read_only:
-            err_read_only()
+            raise ReadOnlyError()
 
         # refresh metadata
         if not self._cache_metadata:
@@ -1288,7 +1288,7 @@ def set_orthogonal_selection(self, selection, value, fields=None):
 
         # guard conditions
         if self._read_only:
-            err_read_only()
+            raise ReadOnlyError()
 
         # refresh metadata
         if not self._cache_metadata:
@@ -1360,7 +1360,7 @@ def set_coordinate_selection(self, selection, value, fields=None):
 
         # guard conditions
         if self._read_only:
-            err_read_only()
+            raise ReadOnlyError()
 
         # refresh metadata
         if not self._cache_metadata:
@@ -1441,7 +1441,7 @@ def set_mask_selection(self, selection, value, fields=None):
 
         # guard conditions
         if self._read_only:
-            err_read_only()
+            raise ReadOnlyError()
 
         # refresh metadata
         if not self._cache_metadata:
@@ -1966,7 +1966,7 @@ def _write_op(self, f, *args, **kwargs):
 
         # guard condition
         if self._read_only:
-            err_read_only()
+            raise ReadOnlyError()
 
         return self._synchronized_op(f, *args, **kwargs)
 

zarr/creation.py

@@ -5,8 +5,11 @@
 from numcodecs.registry import codec_registry
 
 from zarr.core import Array
-from zarr.errors import (err_array_not_found, err_contains_array,
-                         err_contains_group)
+from zarr.errors import (
+    ArrayNotFoundError,
+    ContainsArrayError,
+    ContainsGroupError,
+)
 from zarr.n5 import N5Store
 from zarr.storage import (DirectoryStore, ZipStore, contains_array,
                           contains_group, default_compressor, init_array,
@@ -466,9 +469,9 @@ def open_array(store=None, mode='a', shape=None, chunks=True, dtype=None,
 
     if mode in ['r', 'r+']:
         if contains_group(store, path=path):
-            err_contains_group(path)
+            raise ContainsGroupError(path)
         elif not contains_array(store, path=path):
-            err_array_not_found(path)
+            raise ArrayNotFoundError(path)
 
     elif mode == 'w':
         init_array(store, shape=shape, chunks=chunks, dtype=dtype,
@@ -478,7 +481,7 @@ def open_array(store=None, mode='a', shape=None, chunks=True, dtype=None,
 
     elif mode == 'a':
         if contains_group(store, path=path):
-            err_contains_group(path)
+            raise ContainsGroupError(path)
         elif not contains_array(store, path=path):
             init_array(store, shape=shape, chunks=chunks, dtype=dtype,
                        compressor=compressor, fill_value=fill_value,
@@ -487,9 +490,9 @@ def open_array(store=None, mode='a', shape=None, chunks=True, dtype=None,
 
     elif mode in ['w-', 'x']:
         if contains_group(store, path=path):
-            err_contains_group(path)
+            raise ContainsGroupError(path)
         elif contains_array(store, path=path):
-            err_contains_array(path)
+            raise ContainsArrayError(path)
         else:
             init_array(store, shape=shape, chunks=chunks, dtype=dtype,
                        compressor=compressor, fill_value=fill_value,

zarr/errors.py

@@ -9,37 +9,69 @@ class CopyError(RuntimeError):
     pass
 
 
+class _BaseZarrError(ValueError):
+    _msg = ""
+
+    def __init__(self, *args):
+        super().__init__(self._msg.format(*args))
+
+
+class ContainsGroupError(_BaseZarrError):
+    _msg = "path {0!r} contains a group"
+
+
 def err_contains_group(path):
-    raise ValueError('path %r contains a group' % path)
+    raise ContainsGroupError(path)  # pragma: no cover
+
+
+class ContainsArrayError(_BaseZarrError):
+    _msg = "path {0!r} contains an array"
 
 
 def err_contains_array(path):
-    raise ValueError('path %r contains an array' % path)
+    raise ContainsArrayError(path)  # pragma: no cover
+
+
+class ArrayNotFoundError(_BaseZarrError):
+    _msg = "array not found at path %r' {0!r}"
 
 
 def err_array_not_found(path):
-    raise ValueError('array not found at path %r' % path)
+    raise ArrayNotFoundError(path)  # pragma: no cover
+
+
+class GroupNotFoundError(_BaseZarrError):
+    _msg = "group not found at path {0!r}"
 
 
 def err_group_not_found(path):
-    raise ValueError('group not found at path %r' % path)
+    raise GroupNotFoundError(path)  # pragma: no cover
+
+
+class PathNotFoundError(_BaseZarrError):
+    _msg = "nothing found at path {0!r}"
 
 
 def err_path_not_found(path):
-    raise ValueError('nothing found at path %r' % path)
+    raise PathNotFoundError(path)  # pragma: no cover
 
 
 def err_bad_compressor(compressor):
     raise ValueError('bad compressor; expected Codec object, found %r' %
                      compressor)
 
 
-def err_fspath_exists_notdir(fspath):
-    raise ValueError('path exists but is not a directory: %r' % fspath)
+class FSPathExistNotDir(GroupNotFoundError):
+    _msg = "path exists but is not a directory: %r"
+
+
+class ReadOnlyError(PermissionError):
+    def __init__(self):
+        super().__init__("object is read-only")
 
 
 def err_read_only():
-    raise PermissionError('object is read-only')
+    raise ReadOnlyError()  # pragma: no cover
 
 
 def err_boundscheck(dim_len):

zarr/hierarchy.py

@@ -9,8 +9,12 @@
 from zarr.creation import (array, create, empty, empty_like, full, full_like,
                            normalize_store_arg, ones, ones_like, zeros,
                            zeros_like)
-from zarr.errors import (err_contains_array, err_contains_group,
-                         err_group_not_found, err_read_only)
+from zarr.errors import (
+    ContainsArrayError,
+    ContainsGroupError,
+    GroupNotFoundError,
+    ReadOnlyError,
+)
 from zarr.meta import decode_group_metadata
 from zarr.storage import (MemoryStore, attrs_key, contains_array,
                           contains_group, group_meta_key, init_group, listdir,
@@ -105,14 +109,14 @@ def __init__(self, store, path=None, read_only=False, chunk_store=None,
 
         # guard conditions
         if contains_array(store, path=self._path):
-            err_contains_array(path)
+            raise ContainsArrayError(path)
 
         # initialize metadata
         try:
             mkey = self._key_prefix + group_meta_key
             meta_bytes = store[mkey]
         except KeyError:
-            err_group_not_found(path)
+            raise GroupNotFoundError(path)
         else:
             meta = decode_group_metadata(meta_bytes)
             self._meta = meta
@@ -645,7 +649,7 @@ def _write_op(self, f, *args, **kwargs):
 
         # guard condition
         if self._read_only:
-            err_read_only()
+            raise ReadOnlyError()
 
         if self._synchronizer is None:
             # no synchronization
@@ -1154,24 +1158,24 @@ def open_group(store=None, mode='a', cache_attrs=True, synchronizer=None, path=N
 
     if mode in ['r', 'r+']:
         if contains_array(store, path=path):
-            err_contains_array(path)
+            raise ContainsArrayError(path)
         elif not contains_group(store, path=path):
-            err_group_not_found(path)
+            raise GroupNotFoundError(path)
 
     elif mode == 'w':
         init_group(store, overwrite=True, path=path, chunk_store=chunk_store)
 
     elif mode == 'a':
         if contains_array(store, path=path):
-            err_contains_array(path)
+            raise ContainsArrayError(path)
         if not contains_group(store, path=path):
             init_group(store, path=path, chunk_store=chunk_store)
 
     elif mode in ['w-', 'x']:
         if contains_array(store, path=path):
-            err_contains_array(path)
+            raise ContainsArrayError(path)
         elif contains_group(store, path=path):
-            err_contains_group(path)
+            raise ContainsGroupError(path)
         else:
             init_group(store, path=path, chunk_store=chunk_store)