Merge pull request #97 from opalmer/input_error_enhancement

Minor InputError Improvements

docs/source/changelog.rst

@@ -29,6 +29,8 @@ Notable enhancements and changes are:
     * All exposed APIs updated to use the new Windows equivalent Python types
       in :mod:`pywincffi.wintypes`.
     * All exposed APIs now explicitly require either text or binary data.
+    * Improved documentation for :class:`pywincffi.exceptions.InputError` and
+      added the ability to generate custom error messages.
 
 0.2.0
 ~~~~~

pywincffi/exceptions.py

@@ -30,9 +30,34 @@ class InputError(PyWinCFFIError):
     is provided to a function.  Because we're passing inputs to C we have
     to be sure that the input(s) being provided are what we're expecting so
     we fail early and provide better error messages.
+
+
+    :param str name:
+        The name of the parameter being checked
+
+    :param value:
+        The value of the parameter being checked
+
+    :param expected_types:
+        The expected type(s).  This may be either a single value or a
+        tuple/list of types.
+
+    :keyword allowed_values:
+        An explicit list of values which are allowed for ``value``.
+
+    :keyword ffi:
+        If ``value`` is a C object then you may pass in an instance of the
+        FFI instance to help understand the underlying type of ``value``
+
+    :keyword str message:
+        A custom error message.  This will override the default error messages
+        which :class:`InputError` would normally generate.  This can be
+        helpful if there is a problem with a given input parameter to a
+        function but it's unrelated to the type of input.
     """
     def __init__(  # pylint: disable=too-many-arguments
-            self, name, value, expected_types, allowed_values=None, ffi=None):
+            self, name, value, expected_types, allowed_values=None, ffi=None,
+            message=None):
         self.name = name
         self.value = value
         self.value_repr = value
@@ -53,7 +78,10 @@ def __init__(  # pylint: disable=too-many-arguments
                 self.value_repr = "%s(kind=%r, cname=%r)" % (
                     value.__class__.__name__, typeof.kind, typeof.cname)
 
-        if self.allowed_values is None:
+        if message is not None:
+            self.message = message
+
+        elif self.allowed_values is None:
             self.message = "Expected type(s) %r for %s.  Got %s instead." % (
                 self.expected_types, self.name, self.value_repr
             )

tests/test_exceptions.py

@@ -41,6 +41,11 @@ def test_str(self):
         error = InputError("name", "value", (str, int))
         self.assertEqual(str(error), error.message)
 
+    def test_custom_message(self):
+        error = InputError(
+            "name", "value", (str, int), message="Hello, world.")
+        self.assertEqual(str(error), "Hello, world.")
+
 
 class TestWindowsAPIError(TestCase):
     """