ErrorHandler documentation

Installation Instructions

If you want to experiment with errorhandler, the easiest way to install it is to do the following in a virtualenv:

pip install errorhandler

If your package uses setuptools and you decide to use errorhandler, then you should add it as a requirement by adding an install_requires parameter in your call to setup as follows:

setup(
    # other stuff here
    install_requires=['errorhandler'],
    )

Using ErrorHandler

This is a handler for the python standard logging framework that can be used to tell whether messages have been logged at or above a certain level.

This can be useful when wanting to ensure that no errors have been logged before committing data back to a database.

Basic usage

First, you set up the error handler:

>>> from logging import getLogger
>>> from errorhandler import ErrorHandler
>>> logger = getLogger()
>>> e = ErrorHandler()

The handler starts off being un-fired:

>>> e.fired
False

Then you do whatever else you need to do, which may involve logging:

>>> logger.info('some information')
>>> e.fired
False

However, if any logging occurs at an error level or above:

>>> logger.error('an error')

Then the error handler becomes fired:

>>> e.fired
True

You can use this as a condition to only perform certain actions when no errors have been logged:

>>> if e.fired:
...   print("Not updating files as errors have occurred")
Not updating files as errors have occurred

Resetting

If your code does work in batches, you may wish to reset the error handler at the start of each batch:

>>> e.fired
True
>>> e.reset()
>>> e.fired
False

Registering for a particular logger

The error handler can be set to only trigger on a certain logger and its children:

>>> from logging import getLogger
>>> e = ErrorHandler(logger='b')

Using these three loggers as an example:

>>> a = getLogger()
>>> b = getLogger('b')
>>> c = getLogger('b.c')

Logging to a won’t trigger the handler:

>>> a.critical('message')
>>> e.fired
False

Logging to b will trigger the handler:

>>> b.critical('message')
>>> e.fired
True
>>> e.reset()
>>> e.fired
False

Logging to c will also trigger the handler:

>>> c.critical('message')
>>> e.fired
True

Using a different log level

The logging level at which the ErrorHandler is fired can also be configured:

>>> from logging import INFO
>>> e = ErrorHandler(INFO)

Debugging messages still don’t trigger:

>>> logger.debug('debugging')
>>> e.fired
False

But now informational messages do:

>>> logger.info('some information')
>>> e.fired
True

Installing and removing the handler

By default, the ErrorHandler is installed when it is created, but this doesn’t have to be the case:

>>> e = ErrorHandler(install=False)
>>> logger.error('an error')
>>> e.fired
False

When you create an ErrorHandler like this, you have to install it before log messages will cause it to become fired:

>>> e.install()
>>> logger.error('an error')
>>> e.fired
True

However, it’s always good practice to remove the handler when you’re done, like this:

>>> e.remove()

API Reference

class errorhandler.ErrorHandler(level=logging.ERROR, logger='', install=True)

This constructs an ErrorHandler.

Parameters:
  • level – This specifies the logging level at which the error handler will fire. Any message logged at or above this level will trigger the error handler.
  • logger – This specifies the logger on which the error handler will be installed. The default is the root logger.
  • install – If True, the handler is automatically installed. If False, the handler has to be manually installed by calling its install() method
install()

Installs this ErrorHandler object in the logger specified during instantiation.

reset()

Resets this ErrorHandler object.

Development

This package is developed using continuous integration which can be found here:

https://travis-ci.org/Simplistix/errorhandler

The latest development version of the documentation can be found here:

http://errorhandler.readthedocs.org/en/latest/

If you wish to contribute to this project, then you should fork the repository found here:

https://github.com/Simplistix/errorhandler

Once that has been done and you have a checkout, you can follow these instructions to perform various development tasks:

Setting up a virtualenv

The recommended way to set up a development environment is to turn your checkout into a virtualenv and then install the package in editable form as follows:

$ virtualenv .
$ bin/pip install -U -e .[test,build]

Running the tests

Once you’ve set up a virtualenv, the tests can be run as follows:

$ bin/nosetests

Building the documentation

The Sphinx documentation is built by doing the following from the directory containing setup.py:

$ source bin/activate
$ cd docs
$ make html

To check that the description that will be used on PyPI renders properly, do the following:

$ python setup.py --long-description | rst2html.py > desc.html

The resulting desc.html should be checked by opening in a browser.

Making a release

To make a release, just update versions.txt, update the change log, tag it and push to https://github.com/Simplistix/errorhandler and Travis CI should take care of the rest.

Once Travis CI is done, make sure to go to https://readthedocs.org/projects/testfixtures/versions/ and make sure the new release is marked as an Active Version.

Changes

2.0.1 (6 Jun 2016)

  • Package as a universal wheel.

2.0.0 (6 Jun 2016)

  • Support for Python 3
  • Documentation on Read The Docs
  • Continuous testing using Travis CI
  • Code coverage reporting through Coveralls

1.1.0 (7 Nov 2009)

  • Switched to Sphinx documentation

1.0.0 (3 Dec 2008)

  • Initial Release

License

Copyright (c) 2008-2015 Simplistix Ltd, 2016 Chris Withers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Indices and tables