exception-notifier

Notify uncaught exceptions in your Python code.

This module works with Python 2.7, 3.2, 3.3 and PyPy.

Installation

Exception Notifier is available at PYPI, you can install it using pip:

pip install exception-notifier

Or you can clone the repo and run:

python setup.py install

Usage

Override default exception hook

The simplest usage:

import exception_notifier as en
en.enable()

After this, all uncaught execptions will be mailed to your local account (provided you have a local mail server). enable can be customized with the same arguments with mail_exception as showed below.

If you want to restore to the default hook, use:

en.disable()

Handling individual function

Use the mail_exception function to return an decorator for your function. Then every uncaught exception in your function will be mailed to you.

    from exception_notifier import mail_exception

    exception_notifier_conf = {
        'sender': 'tux@localhost',
        'receivers': ['tux@localhost'],
        'mail_server': 'localhost',
    }

    @mail_exception(**exception_notifier_conf)
    def fancy_function():
        ...

You may better wrap your whole module in a starting script. Thus not only functions, but every line in your module will be protected by exception-notifier. Your module fancy_module may look like this:

    def func1():
        ...
    def func2():
        ...
    def main():
        func1()
        func2()

Your wrapper scripts may look like this:

    from exception_notifier import mail_exception

    exception_notifier_conf = {
        'sender': 'tux@localhost',
        'receivers': ['tux@localhost'],
        'mail_server': 'localhost',
    }


    @mail_exception(**exception_notifier_conf)
    def main():
        import fancy_module
        fancy_module.main()

    if __name__ == '__main__':
            main()

This way you will be notified if any line in your module raises an uncaught exception.

Use custom callback

If you want to use custom callback function instead of the default behavior of sending email, you can use the callback argument like below:

@mail_exception(callback=f, args=(1, 2),
        kwargs={'x': 3}, **exception_notifier_conf)

If the argument both is True, then not only the mail is sent, but the callback function is executed also.

In the callback function, you probably want to deal with the exception information, then sys.exc_info() is conveniently at your service.

Bugs

mail_exception will make the exception non-fatal, i.e., the program will continue to run after the notifier returns. Future version may add an argument for speclify whether the program should terminate after the notifier returns.

For enable, the program terminates after the notifier returns. This is because that we are overriding the system exception hook. Furthermore, there is no way to get the return value of callback in Python code, so the return of it is meaningless, even if you can return some value explicitly in it.

The coverage reported by Coveralls is inaccurate, because Travis cannot run code sending email. Run tests/test_coverage.sh to get a full coverage. However, code of system exception hook is not counted by python-coverage in either case.