Merge pull request #272 from Jajcus/SoundFileError_exception

SoundFileError exception added

Author: bastibe

README.rst

@@ -71,6 +71,17 @@ Binaries for Python Extension Packages <http://www.lfd.uci.edu/~gohlke/pythonlib
 
 .. _Anaconda: https://www.continuum.io/downloads
 
+Error Reporting
+---------------
+
+In case of API usage errors the ``soundfile`` module raises the usual `ValueError` or `TypeError`.
+
+For other errors `SoundFileError` is raised (used to be `RuntimeError`).
+Particularly, a `LibsndfileError` subclass of this exception is raised on
+errors reported by the libsndfile library. In that case the exception object
+provides the libsndfile internal error code in the `LibsndfileError.code` attribute and the raw
+libsndfile error message in the `LibsndfileError.error_string` attribute.
+
 Read/Write Functions
 --------------------
 

soundfile.py

@@ -1072,7 +1072,7 @@ def blocks(self, blocksize=None, overlap=0, frames=-1, dtype='float64',
         import numpy as np
 
         if 'r' not in self.mode and '+' not in self.mode:
-            raise RuntimeError("blocks() is not allowed in write-only mode")
+            raise SoundFileRuntimeError("blocks() is not allowed in write-only mode")
 
         if out is None:
             if blocksize is None:
@@ -1130,7 +1130,9 @@ def truncate(self, frames=None):
                               _ffi.new("sf_count_t*", frames),
                               _ffi.sizeof("sf_count_t"))
         if err:
-            raise RuntimeError("Error truncating the file")
+            # get the actual error code
+            err = _snd.sf_error(self._file)
+            raise LibsndfileError(err, "Error truncating the file")
         self._info.frames = frames
 
     def flush(self):
@@ -1256,7 +1258,7 @@ def _check_if_closed(self):
 
         """
         if self.closed:
-            raise RuntimeError("I/O operation on closed file")
+            raise SoundFileRuntimeError("I/O operation on closed file")
 
     def _check_frames(self, frames, fill_value):
         """Reduce frames to no more than are available in the file."""
@@ -1350,10 +1352,9 @@ def _prepare_read(self, start, stop, frames):
 
 
 def _error_check(err, prefix=""):
-    """Pretty-print a numerical error code if there is an error."""
+    """Raise LibsndfileError if there is an error."""
     if err != 0:
-        err_str = _snd.sf_error_number(err)
-        raise RuntimeError(prefix + _ffi.string(err_str).decode('utf-8', 'replace'))
+        raise LibsndfileError(err, prefix=prefix)
 
 
 def _format_int(format, subtype, endian):
@@ -1508,3 +1509,37 @@ def _has_virtual_io_attrs(file, mode_int):
         hasattr(file, 'write') or readonly,
         hasattr(file, 'read') or hasattr(file, 'readinto') or writeonly,
     ])
+
+
+class SoundFileError(Exception):
+    """Base class for all SoundFile-specific errors."""
+    pass
+
+class SoundFileRuntimeError(SoundFileError, RuntimeError):
+    """SoundFile runtime error.
+
+    Errors that used to be `RuntimeError`."""
+    pass
+
+class LibsndfileError(SoundFileRuntimeError):
+    """libsndfile errors.
+
+
+    Attributes
+    ----------
+    code
+        libsndfile internal error number.
+    """
+    def __init__(self, code, prefix=""):
+        SoundFileRuntimeError.__init__(self, code, prefix)
+        self.code = code
+        self.prefix = prefix
+
+    @property
+    def error_string(self):
+        """Raw libsndfile error message."""
+        err_str = _snd.sf_error_number(self.code)
+        return _ffi.string(err_str).decode('utf-8', 'replace')
+
+    def __str__(self):
+        return self.prefix + self.error_string

tests/test_pysoundfile.py

@@ -232,11 +232,12 @@ def test_read_mono_into_2d_out(file_mono_r):
 
 
 def test_read_non_existing_file():
-    with pytest.raises(RuntimeError) as excinfo:
+    with pytest.raises(sf.SoundFileError) as excinfo:
         sf.read("i_do_not_exist.wav")
     assert "Error opening 'i_do_not_exist.wav'" in str(excinfo.value)
 
 
+
 # -----------------------------------------------------------------------------
 # Test write() function
 # -----------------------------------------------------------------------------
@@ -418,7 +419,7 @@ def test_blocks_wplus(sf_stereo_wplus):
 
 
 def test_blocks_write(sf_stereo_w):
-    with pytest.raises(RuntimeError):
+    with pytest.raises(sf.SoundFileError):
         list(sf_stereo_w.blocks(blocksize=2))
 
 
@@ -644,9 +645,9 @@ def test_seek_in_read_mode(sf_stereo_r):
     assert sf_stereo_r.tell() == 2
     assert sf_stereo_r.seek(2, sf.SEEK_CUR) == 4
     assert sf_stereo_r.seek(-2, sf.SEEK_END) == len(data_stereo) - 2
-    with pytest.raises(RuntimeError):
+    with pytest.raises(sf.SoundFileError):
         sf_stereo_r.seek(666)
-    with pytest.raises(RuntimeError):
+    with pytest.raises(sf.SoundFileError):
         sf_stereo_r.seek(-666)
 
 
@@ -685,8 +686,9 @@ def test_truncate(file_stereo_rplus, use_default):
     else:
         # file objects don't support truncate()
         with sf.SoundFile(file_stereo_rplus, 'r+', closefd=False) as f:
-            with pytest.raises(RuntimeError) as excinfo:
+            with pytest.raises(sf.SoundFileError) as excinfo:
                 f.truncate()
+            assert isinstance(excinfo.value, RuntimeError)
             assert "Error truncating" in str(excinfo.value)
 
 
@@ -696,7 +698,7 @@ def test_truncate(file_stereo_rplus, use_default):
 
 
 def test_read_write_only(sf_stereo_w):
-    with pytest.raises(RuntimeError):
+    with pytest.raises(sf.SoundFileError):
         sf_stereo_w.read(2)
 
 
@@ -796,7 +798,7 @@ def test_buffer_read_into(sf_stereo_r):
 
 
 def test_write_to_read_only_file_should_fail(sf_stereo_r):
-    with pytest.raises(RuntimeError):
+    with pytest.raises(sf.SoundFileError):
         sf_stereo_r.write(data_stereo)
 
 
@@ -887,8 +889,9 @@ def test_closing_should_close_file(file_stereo_r):
 def test_anything_on_closed_file(file_stereo_r):
     with sf.SoundFile(file_stereo_r) as f:
         pass
-    with pytest.raises(RuntimeError) as excinfo:
+    with pytest.raises(sf.SoundFileError) as excinfo:
         f.seek(0)
+    assert isinstance(excinfo.value, RuntimeError)
     assert "closed" in str(excinfo.value)
 
 
@@ -1014,8 +1017,9 @@ def test_write_non_seekable_file(file_w):
         f.write(data_mono)
         assert f.frames == len(data_mono)
 
-        with pytest.raises(RuntimeError) as excinfo:
+        with pytest.raises(sf.SoundFileError) as excinfo:
             f.seek(2)
+        assert isinstance(excinfo.value, RuntimeError)
         assert "unseekable" in str(excinfo.value)
 
     with sf.SoundFile(filename_new) as f:
@@ -1026,8 +1030,9 @@ def test_write_non_seekable_file(file_w):
         data = f.read(666, dtype='int16')
         assert np.all(data == data_mono[3:])
 
-        with pytest.raises(RuntimeError) as excinfo:
+        with pytest.raises(sf.SoundFileError) as excinfo:
             f.seek(2)
+        assert isinstance(excinfo.value, RuntimeError)
         assert "unseekable" in str(excinfo.value)
 
         with pytest.raises(ValueError) as excinfo:
@@ -1041,3 +1046,32 @@ def test_write_non_seekable_file(file_w):
     with pytest.raises(ValueError) as excinfo:
         sf.read(filename_new, start=3)
     assert "start is only allowed for seekable files" in str(excinfo.value)
+
+
+# -----------------------------------------------------------------------------
+# Test LibsndfileError
+# -----------------------------------------------------------------------------
+
+def test_libsndfile_error():
+    err = sf.LibsndfileError(2)
+    assert isinstance(err, sf.SoundFileError)
+    assert err.error_string # cannot assume exact message generated by libsndfile
+    assert str(err) == err.error_string
+
+def test_libsndfile_error_with_prefix():
+    err = sf.LibsndfileError(2, prefix="XX ")
+    assert isinstance(err, sf.SoundFileError)
+    assert err.error_string # cannot assume exact message generated by libsndfile
+    assert str(err) == "XX " + err.error_string
+
+def test_rasing_libsndfile_error():
+    with pytest.raises(sf.LibsndfileError) as excinfo:
+        sf.read("i_do_not_exist.wav")
+    assert isinstance(excinfo.value, sf.SoundFileError)
+    assert isinstance(excinfo.value, RuntimeError)
+    assert excinfo.value.code == 2 # SF_ERR_SYSTEM
+    if sys.version_info[0] == 2:
+        assert isinstance(excinfo.value.error_string, unicode)
+    else:
+        assert isinstance(excinfo.value.error_string, str)
+    assert excinfo.value.error_string in str(excinfo.value)