snim2's posterous

On StackOverflow someone asked a while ago whether you can find out what errors a module defines and throws. In Python, a function does not declare that it throws a particular error object, so you need to look inside the module to see what exceptions it defines, or what exception it raises. You can do this by reading the docs (RTFM!) but of course they may be out of date, or what have you, so an alternative is to use the Python API to do look for you.

Which errors does a module define?

To first find which exceptions a module defines, just write a simple script to go through each object in the module dictionary module.__dict__ and see if it ends in the word Error or if it is a subclass of Exception:

def listexns(mod):
    """Saved as: http://gist.github.com/402861
    """
    module = __import__(mod)
    exns = []
    for name in module.__dict__:
        if (isinstance(module.__dict__[name], Exception) or
            name.endswith('Error')):
            exns.append(name)
    for name in exns:
        print '%s.%s is an exception type' % (str(mod), name)
    return

If I run this on the shutils module from the standard library I get this:

$ python listexn.py shutil
Looking for exception types in module: shutil
shutil.Error is an exception type
shutil.WindowsError is an exception type
$

That tells you which errors are defined, but not which ones are thrown. Of course, if the module has errors with funny names, or ones that are not subclasses of Exception, then this code will miss them.

What errors are thrown by a module?

To find out what errors a module can throw, we need to walk over the abstract syntax tree generated when the Python interpreter parses the module, and look for every raise statement, then save a list of names which are raised. The code for this is a little long, but pretty straight forward, so first I’ll state the output:

$ python listexn-raised.py /usr/lib/python2.6/shutil.py
Looking for exception types in: /usr/lib/python2.6/shutil.py
/usr/lib/python2.6/shutil.py:OSError is an exception type
/usr/lib/python2.6/shutil.py:Error is an exception type
$

So now we know that shutil.py defines the errors Error and WindowsError and raises the exception OSError and Error. If we want to be a bit more complete, we could write another method to check every except clause to also see which exceptions shutil handles.

Here’s the code to walk over the AST, it just uses the compiler.visitor interface to create a walker which implements the visitor pattern from the Gang of Four book:

class ExceptionFinder(visitor.ASTVisitor):
    """List all exceptions raised by a module. 
    Saved as: http://gist.github.com/402869
    """

    def __init__(self, filename):
        visitor.ASTVisitor.__init__(self)
        self.filename = filename
        self.exns = set()
        return

    def __visitName(self, node):
        """Only called from within a raise statement.
        """
        self.exns.add(node.name)
        return

    def __visitCallFunc(self, node):
        """Only called from within a raise statement.
        """
        self.__visitName(node.node)
        return

    def visitRaise(self, node):
        """Visit a raise statement.
        Cheat the default dispatcher.
        """
        if isinstance(node.expr1, compiler.ast.Name):
            self.__visitName(node.expr1)
        elif isinstance(node.expr1, compiler.ast.CallFunc):
            self.__visitCallFunc(node.expr1)
        return