Merge pull request #8 from BD2KGenomics/features/add-require

Add require() to compliment assert()

Author: hannes-ucsc

src/bd2k/util/exceptions.py

@@ -31,7 +31,37 @@ def __enter__( self ):
         self.exc_info = sys.exc_info( )
 
     def __exit__( self, *exc_info ):
-        if self.log is not None and exc_info and exc_info[0]:
+        if self.log is not None and exc_info and exc_info[ 0 ]:
             self.log.warn( "Exception during panic", exc_info=exc_info )
         exc_type, exc_value, traceback = self.exc_info
         raise exc_type, exc_value, traceback
+
+
+class RequirementError( Exception ):
+    """
+    The expcetion raised bye require(). Where AssertionError is raised when there is likely an
+    internal problem within the code base, i.e. a bug, an instance of this class is raised when
+    the cause lies outside the code base, e.g. with the user or caller.
+    """
+    pass
+
+
+def require( value, message ):
+    """
+    Raise RequirementError with the given message if the given value is considered false. See
+    https://docs.python.org/2/library/stdtypes.html#truth-value-testing for a defintiion of which
+    values are false. This function is commonly used for validating user input. It is meant to be
+    complimentary to assert. See RequirementError for more on that.
+
+    :param Any value: the value to be tested
+    :param message:
+    :return:
+
+    >>> require(1 + 1 == 2, 'You made a terrible mistake')
+    >>> require(1 + 1 == 3, 'You made a terrible mistake')
+    Traceback (most recent call last):
+    ...
+    RequirementError: You made a terrible mistake
+    """
+    if not value:
+        raise RequirementError( message )