Quick Start

Installation

The best way to install ExceptionControl is to install it via pip:

Installation of ExceptionControl from a linux prompt
$ python3 -m pip install ExceptionControl

It can also be cloned from Gitlab and installed locally:

Cloning ExceptionControl from Gitlab
$ git clone https://gitlab.com/semantik-software/code/python/ExceptionControl.git
$ cd ExceptionControl
$ python3 -m pip install .

Running the Examples

Once installed, you can go to the Examples directory and run the examples:

$ cd examples
$ python3 ExceptionControl-Example-00.py
...

Using ExceptionControl

The first step is to include the ExceptionControl class:

1#!/usr/bin/env python3
2from exceptioncontrol import ExceptionControl
3

Examples

These examples demonstrate how we might use ExceptionControl to add events to our code that can optionally raise warnings or events based on the parameter exception_control_level for a given class.

Basic ExceptionControl Examples

Example 0: Simple Start

This is the ‘hello world’ example of ExceptionControl and shows a simple class construction with a method that has an exception_control_event. In this case it’s a WARNING event which should just print out a warning message.

Here is the code for this example:

 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()

When run the output looks like:

 1!! ================================================================================
 2!! EXCEPTION SKIPPED
 3!! Event Type : WARNING
 4!! Exception  : TypeError
 5!! Message    : An error occurred
 6!!
 7!! Call Stack:
 8!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-00.py", line 19, in <module>
 9!!     data.some_method()
10!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-00.py", line 10, in some_method
11!!     self.exception_control_event("WARNING", TypeError, "An error occurred")
12!!
13!! Increase `exception_control_level` to 5 to raise this exception.
14!! ================================================================================

Here we see the general format of a warning message. Warning messages have the following characteristics:

  • Warning message lines are prefixed with a double-exclamation point !! which is useful for searching for them in log files as well as calling attention to the lines which is what you want to do when flagging a warning.

  • It notes that an exception is skipped (i.e. not raised). Also handy as a search key.

  • The Event Type is noted, which is the level of this event (WARNING, MINOR, MAJOR, etc.)

  • The Exceptin type is shown. In this case we used a TypeError. This is the kind of exception that is raised if exceptin_control_level is set to a value that would raise this exception.

  • The message is printed out.

  • A stack trace is also printed showing the location of the event within the code.

  • A note is added indicating the value exception_control_level would need to be to cause this event to raise the associated exception.

Example 1: Kitchen Sink

For this example we create a slightly more expansive test class that creates a stub method for each of the different event levels.

 1class MyClass(ExceptionControl):
 2
 3    def method_with_silent_event(self):
 4        # do stuff
 5        print("Trigger a `SILENT` event:")
 6        self.exception_control_event("SILENT", TypeError, "Something happened!")
 7        return
 8
 9    def method_with_warning_event(self):
10        # do stuff
11        print("Trigger a `WARNING` event:")
12        self.exception_control_event("WARNING", TypeError, "A TypeError occurred!")
13        return
14
15    def method_with_minor_event(self):
16        # do stuff
17        print("Trigger a `MINOR` event:")
18        self.exception_control_event("MINOR", ValueError, "Something minor happened!")
19        return
20
21    def method_with_serious_event(self):
22        # do stuff
23        print("Trigger a `SERIOUS` event:")
24        self.exception_control_event("SERIOUS", ValueError, "Something serious happened!")
25        return
26
27    def method_with_critical_event(self):
28        # do stuff
29        print("Trigger a `CRITICAL` event:")
30        self.exception_control_event("CRITICAL", Exception, "A critical error occurred!")
31        return
32
33    def method_with_catastrophic_event(self):
34        # do stuff
35        print("Trigger a `CATASTROPHIC` event:")
36        self.exception_control_event("CATASTROPHIC", Exception, "Catastrophe!")
37        return

We can then test this using the following function:

 1def main():
 2
 3    # Create an instance of our test class
 4    data = MyClass()
 5
 6    # A SILENT event should show no messages.
 7    data.method_with_silent_event()
 8    print("")
 9
10    # A WARNING event prints a message but does not interrupt execution
11    data.method_with_warning_event()
12    print("")
13
14    # A MINOR event raises an exception if exception_control_level
15    # is 4 (default) or higher.
16    try:
17        data.method_with_minor_event()
18    except ValueError as err:
19        print("*** CAUGHT EXCEPTION ***")
20        print(">>> `MINOR` event triggered a ValueError exception")
21        print(f">>> message: {err}")
22    print("")
23
24    # Change exception_control_level to 3 will cause MINOR events to
25    # print a warning message without raising the exception.
26    print("Set exception_control_level = 3")
27    data.exception_control_level = 3
28    data.method_with_minor_event()
29    print("")
30
31    # A SERIOUS event raises an exception when exception_control_level
32    # is 3 or higher.
33    try:
34        data.method_with_serious_event()
35    except ValueError as err:
36        print("*** CAUGHT EXCEPTION ***")
37        print(">>> `SERIOUS` event triggered a ValueError exception")
38        print(f">>> message: {err}")
39    print("")
40
41    # Changing exception_control_level to 2 will suppress a SERIOUS
42    # event from being raised in favour of printing a warning message.
43    print("Set exception_control_level = 2")
44    data.exception_control_level = 2
45    data.method_with_serious_event()
46    print("")
47
48    # A CRITICAL event raises an exception when exception_control_level
49    # is 2 or higher.
50    try:
51        data.method_with_critical_event()
52    except Exception as err:
53        print("*** CAUGHT EXCEPTION ***")
54        print(">>> `CRITICAL` event triggered an Exception")
55        print(f">>> message: {err}")
56    print("")
57
58    # Changing exception_control_level to 1 will suppress a CRITICAL
59    # event from being raised in favour of printing a warning message.
60    print("Set exception_control_level = 1")
61    data.exception_control_level = 1
62    data.method_with_critical_event()
63    print("")
64
65    # Set exception_control_level to 0 to suppress all exceptions
66    # and warning messages.
67    print("Set exception_control_level = 0")
68    data.exception_control_level = 0
69
70    data.method_with_silent_event()
71    data.method_with_warning_event()
72    data.method_with_minor_event()
73    data.method_with_serious_event()
74    data.method_with_critical_event()
75
76    # CATASTROPHIC events will *always* raise the exception regardless
77    # of exception_control_level.
78    try:
79        data.method_with_catastrophic_event()
80    except Exception as err:
81        print("*** CAUGHT EXCEPTION ***")
82        print(">>> `CATASTROPHIC` event triggered an Exception")
83        print(f">>> message: {err}")
84    print("")

The output of this example is here:

  1Trigger a `SILENT` event:
  2
  3Trigger a `WARNING` event:
  4!! ================================================================================
  5!! EXCEPTION SKIPPED
  6!! Event Type : WARNING
  7!! Exception  : TypeError
  8!! Message    : A TypeError occurred!
  9!!
 10!! Call Stack:
 11!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 137, in <module>
 12!!     main()
 13!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 59, in main
 14!!     data.method_with_warning_event()
 15!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 20, in method_with_warning_event
 16!!     self.exception_control_event("WARNING", TypeError, "A TypeError occurred!")
 17!!
 18!! Increase `exception_control_level` to 5 to raise this exception.
 19!! ================================================================================
 20
 21Trigger a `MINOR` event:
 22*** CAUGHT EXCEPTION ***
 23>>> `MINOR` event triggered a ValueError exception
 24>>> message: Something minor happened!
 25
 26Set exception_control_level = 3
 27Trigger a `MINOR` event:
 28!! ================================================================================
 29!! EXCEPTION SKIPPED
 30!! Event Type : MINOR
 31!! Exception  : ValueError
 32!! Message    : Something minor happened!
 33!!
 34!! Call Stack:
 35!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 137, in <module>
 36!!     main()
 37!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 76, in main
 38!!     data.method_with_minor_event()
 39!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 26, in method_with_minor_event
 40!!     self.exception_control_event("MINOR", ValueError, "Something minor happened!")
 41!!
 42!! Increase `exception_control_level` to 4 to raise this exception.
 43!! ================================================================================
 44
 45Trigger a `SERIOUS` event:
 46*** CAUGHT EXCEPTION ***
 47>>> `SERIOUS` event triggered a ValueError exception
 48>>> message: Something serious happened!
 49
 50Set exception_control_level = 2
 51Trigger a `SERIOUS` event:
 52!! ================================================================================
 53!! EXCEPTION SKIPPED
 54!! Event Type : SERIOUS
 55!! Exception  : ValueError
 56!! Message    : Something serious happened!
 57!!
 58!! Call Stack:
 59!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 137, in <module>
 60!!     main()
 61!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 93, in main
 62!!     data.method_with_serious_event()
 63!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 32, in method_with_serious_event
 64!!     self.exception_control_event("SERIOUS", ValueError, "Something serious happened!")
 65!!
 66!! Increase `exception_control_level` to 3 to raise this exception.
 67!! ================================================================================
 68
 69Trigger a `CRITICAL` event:
 70*** CAUGHT EXCEPTION ***
 71>>> `CRITICAL` event triggered an Exception
 72>>> message: A critical error occurred!
 73
 74Set exception_control_level = 1
 75Trigger a `CRITICAL` event:
 76!! ================================================================================
 77!! EXCEPTION SKIPPED
 78!! Event Type : CRITICAL
 79!! Exception  : Exception
 80!! Message    : A critical error occurred!
 81!!
 82!! Call Stack:
 83!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 137, in <module>
 84!!     main()
 85!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 110, in main
 86!!     data.method_with_critical_event()
 87!! File "/builds/semantik-software/code/python/ExceptionControl/examples/ExceptionControl-Example-01.py", line 38, in method_with_critical_event
 88!!     self.exception_control_event("CRITICAL", Exception, "A critical error occurred!")
 89!!
 90!! Increase `exception_control_level` to 2 to raise this exception.
 91!! ================================================================================
 92
 93Set exception_control_level = 0
 94Trigger a `SILENT` event:
 95Trigger a `WARNING` event:
 96Trigger a `MINOR` event:
 97Trigger a `SERIOUS` event:
 98Trigger a `CRITICAL` event:
 99Trigger a `CATASTROPHIC` event:
100*** CAUGHT EXCEPTION ***
101>>> `CATASTROPHIC` event triggered an Exception
102>>> message: Catastrophe!
103
104Done.