add PaErrorCode enum; allow code-less pa errors

+ Added PaErrorCode enumeration of portaudio error codes

+ Modified PortAudioError to allow for exception cases when there is no
  associated portaudio error code. (paerrcode = None)

+ Corrected two PortAudioError exception cases to ValueError exceptions

+ Added attributes documentation to PortAudioError class

+ changed *errno PortAudioError attributes to *errcode to avoid
  confusion with OSError errno attribute

Author: tgarc

sounddevice.py

@@ -517,7 +517,7 @@ def playrec(data, samplerate=None, channels=None, dtype=None,
     input_frames = ctx.check_out(out, output_frames, channels, dtype,
                                  input_mapping)
     if input_frames != output_frames:
-        raise PortAudioError('len(data) != len(out)')
+        raise ValueError('len(data) != len(out)')
     ctx.frames = input_frames
 
     def callback(indata, outdata, frames, time, status):
@@ -924,7 +924,7 @@ def __init__(self, kind, samplerate=None, blocksize=None, device=None,
             self._channels = iparameters.channelCount, oparameters.channelCount
             self._samplesize = isize, osize
             if isamplerate != osamplerate:
-                raise PortAudioError(
+                raise ValueError(
                     'Input and output device must have the same samplerate')
             else:
                 samplerate = isamplerate
@@ -2265,38 +2265,66 @@ def reset(self):
 if not hasattr(_ffi, 'I_AM_FAKE'):
     # This object shadows the 'default' class, except when building the docs.
     default = default()
-
+    # A simple enumeration of the Portaudio error codes
+    PaErrorCode = type('PaErrorCode', (), _ffi.typeof('PaErrorCode').relements)
 
 class PortAudioError(Exception):
-    """This exception will be raised on PortAudio errors."""
-    def __init__(self, *args):
-        """PortAudioError(PaErrorCode[,msg])
-        """
-        super(PortAudioError, self).__init__(*args)
-        self.paerrno = args[0]
-        self.hosterrno = self.hostapi = self.hosterrmsg = None
-
-        if self.paerrno == _lib.paUnanticipatedHostError:
-            info = _lib.Pa_GetLastHostErrorInfo()
-            hostapi = _lib.Pa_HostApiTypeIdToHostApiIndex(info.hostApiType)
-            apiinfo = _lib.Pa_GetHostApiInfo(hostapi)
-            apiname = _ffi.string(apiinfo.name).decode() if apiinfo else 'unknown'
-            errmsg = _ffi.string(info.errorText).decode()
-            self.hosterrno = info.errorCode
-            self.hostapi = apiname
-            self.hosterrmsg = errmsg
+    """This exception will be raised on PortAudio errors.
 
-    def __str__(self):
-        errmsg = "[PaErrno {0:d}] ".format(self.paerrno)
-        if self.hosterrno is not None:
-            errmsg += "Unanticipated {0:r} host error".format(self.hostapi)
+    Parameters
+    ----------
+    msg : optional
+        User error message.
+    errcode : int or None, optional
+        PaErrorCode value or None if there is no PaErrorCode associated
+        with the error.
+
+    Notes
+    -----
+    - Some PortAudioError's do not have an associated PaErrorCode. In
+      such a case `paerrcode` will be None.
+
+    - The `hostapi`, `hosterrcode`, and `hosterrmsg` attributes will be
+      None except for the case when `paerrcode` ==
+      `paUnanticipatedHostError`.
+    
+    Attributes
+    ----------
+    paerrcode : int or None
+        The PaErrorCode integer value or None if there is no associated
+        error code.
+    hostapi : str or None
+        The name of the host API which returned the error code.
+    hosterrcode : int or None
+        The host error code returned.
+    hosterrmsg : str or None
+        A textual description of the host error if available, otherwise
+        a zero-length string.
+    """
+    def __init__(self, msg=None, errcode=None):
+        self.paerrcode = errcode
+        self.hosterrcode = self.hostapi = self.hosterrmsg = None
+
+        if errcode:
+            errmsg = "[PaErrorCode {0:d}] ".format(self.paerrcode)
+            if errcode == _lib.paUnanticipatedHostError:
+                info = _lib.Pa_GetLastHostErrorInfo()
+                hostapi = _lib.Pa_HostApiTypeIdToHostApiIndex(info.hostApiType)
+                apiinfo = _lib.Pa_GetHostApiInfo(hostapi)
+                self.hosterrcode = info.errorCode
+                self.hostapi = _ffi.string(apiinfo.name).decode() if apiinfo else 'unknown'
+                self.hosterrmsg = _ffi.string(info.errorText).decode()
+                errmsg += "Unanticipated {0!r} host error".format(self.hostapi)
+            else:
+                errmsg += _ffi.string(_lib.Pa_GetErrorText(errcode)).decode()
+            if msg is not None:
+                errmsg += ": {0!s}".format(msg)
+            elif self.hosterrmsg:
+                errmsg += ": {0}".format(self.hosterrmsg)
         else:
-            errmsg += _ffi.string(_lib.Pa_GetErrorText(paerrno)).decode()
-        if len(self.args) > 1:
-            errmsg += ": {0!s}".format(self.args[1])
-        elif self.hosterrmsg:
-            errmsg += ": {0}".format(self.hosterrmsg)
-        return errmsg
+            errmsg = msg or ''
+
+        super(PortAudioError, self).__init__(errmsg)
 
 
 class CallbackStop(Exception):
@@ -2685,10 +2713,10 @@ def _split(value):
     return invalue, outvalue
 
 
-def _check(err, msg=""):
+def _check(err, msg=None):
     """Raise error for non-zero error codes."""
     if err < 0:
-        raise PortAudioError(err, msg)
+        raise PortAudioError(msg, err)
     return err