ExceptionControl

Table of Contents:

TL;DR

The ExceptionControl class is designed to be a helper class that is inherited into a class to give it a convenient interface to implement conditional exception handling options.

Overview

The ExceptionControl class is designed to be a helper class that is inherited into a class to give it a convenient interface to implement conditional exception handling options. The purpose of this is to give developers additional flexibility in how events can be handled and tune the overall behaviour via parameters while adding minimal additional control code.

In many codes one may wish their code to take a fail fast approach to handling issues such as unexpected input or other errors. While this method often works well to rapidly identify problems by causing an application to exit, there are times when maybe just a warning is sufficient.

ExceptionControl allows us to classify an event based on its severity using a threshold setting that can be changed. This gives us two degrees of control over the handling of an event. First, by assigning the level of severity of the event itself we can direct what happens when the event is triggered. Second, we can set thresholds that direct the behaviour of the handler when an event is triggered.

Event Types

There are six types of events we can create:

  1. WARNING: The loest severity. These are mostly informative, they may not indicate an error but we may wish to make note of something that isn’t quite right.

  2. SILENT: Shares the same severity as “WARNING” but these events will never print a warning message out. They will trigger the exception if exception_control_level is set to 5, which is the same level that will trigger WARNING events to raise their exceptions. These are useful if you wish to keep output relatively clean but still want the event to be there.

  3. MINOR: More severe than WARNING events, usually indicating an actual error probably happened but not a major one. This might be something that needs to be noted but doesn’t always warrant halting execution.

  4. SERIOUS: Second highest level of severity. Indicates something serious happened which we definitely want to handle explicitly. The likelihood that this kind of event should halt execution and/or throw an exception rather than just print out a message is high.

  5. CRITICAL: The highest severity that can be turned off via exception_control_level. This would generally indicate something went seriously wrong and we should definitely be raising the associated exception with the event.

  6. CATASTROPHIC: This kind of event is the highest level of severity and will always raise the associated exception. Catastrophic events can not be opted out of.

Exception Control Level

The ExceptionControl class adds a property to classes that inherit from it called exception_control_level. This property determines how an event is handled and what we should do based on the level of severity for any given event. Allowed values are 0 to 5 with 0 setting the most permissive rules and 5 being least permissive. The levels are as follows:

  1. No Exceptions: Events do not print out anything nor do they raise an exception. Useful for daemons.

  2. Warnings Only: A warning message is printed out for all events but no exceptions are raised.

  3. Raise Critical Events: CRITICAL events will cause their associated exception to be raised. Lower severity events will print out a warning message.

  4. Raise Serious and Critical Events: CRITICAL and SERIOUS events will raise their associated exception. Lower severity events will print out their associated warning message.

  5. Raise Minor, Serious and Critical Events: CRITICAL, SERIOUS, and MINOR events will raise their associated exceptions. Lower severity events (MINOR, WARNING and SILENT) events will print out their message to the console if applicable. This is the default value of exception_control_level.

  6. Always Raise: All events trigger their associated exception, including WARNING and SILENT events.

The default behaviour is to set exception_control_level to 4 which raises all CRITICAL, SERIOUS and MINOR events while issuing the warning for MINOR and WARNING events. Note that CATASTROPHIC events can not be suppressed.

Controlling Verbosity

Any event that issues a warning by either being a WARNING type or one that issues a warning based on the exception_control_level setting can be shortened by setting the exception_control_compact_warnings property to True.

We can also silence events issuing only warnings by setting the exception_control_silent_warnings property to True.

Quick Example

A short example of a class using ExceptionControl:

 1#!/usr/bin/env python3
 2from exceptioncontrol import ExceptionControl
 3
 4
 5
 6class MyClass(ExceptionControl):
 7
 8    def some_method(self):
 9        # do some work
10        self.exception_control_event("WARNING", TypeError, "An error occurred")
11        return
12
13
14
15# create an instance of the class
16data = MyClass()
17
18# call the method that contains an exception_control_event.
19data.some_method()

This simple example shows how we can add an exceptioon_control_event into a class method which would be triggered a warning or error message as the code operates.

See the Quick Start guide for a more comprehensive starting tutorial and the Examples for additional use case examples.

Test Coverage

Coverage Report