Class Reference

Please see the Quick Start guide for some examples to get started using the ExceptionControl package.

Class Guide

class exceptioncontrol.ExceptionControl.ExceptionControl[source]

Bases: object

The ExceptionControl class is intended as a helper class that would be inherited as a superclass to some other class to give it the capability to implement conditional exception handling options.

This allows developers to create conditional exceptions in their class which can do nothing, print a warning, or raise an exception based on the severity of the issue and the threshold level setting, which is set via a property.

There are six ‘types’ of events that can be created:

  • WARNING: The lowest severity. These are mostly informative, they might not indicate an error but we might want them to make note of something that isn’t quite right.

  • SILENT: Shares the same severity level as “WARNING” but these events will never print a warning out. They will trigger the exception if the 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.

  • MINOR: This is more severe than a WARNING type and indicates that an actual error probably happened but not a major one. This might be somethig that needs to be noted but doesn’t always warrant halting execution.

  • SERIOUS: Second highest level of severity. This indicates something serious happened. We would definitely want to handle this and call out that a problem happened. The likelihood that this kind of event should halt execution and/or throw an exception rather than print out a message is high.

  • CRITICAL: The highest severity of event that might not be raised depending on the value of exception_control_level. This would generally indicate something went seriously wrong and we should definitely raise the exception and halt execution.

  • CATASTROPHIC: This kind of event is the highest level of severity and will always raise the associated exception. These cannot be opted out of.

When events are raised, we will set them to the appropriate type and the behaviour can be determined based on the exception_control_level property on the class. This property determines how an event is handled. The values allowed for this are 0 through 5, where:

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

  2. Warnings Only: A warning message is printed out for all events. No exceptions get raised.

  3. Raise critical events: CRITICAL events will cause the exception to be raised. Lower severity events will print out a warning message.

  4. Raise serious or critical events: CRITICAL and SERIOUS events will raise the associated exception. Lower severity events will print out a warning message.

  5. Raise minor, serious and critical events: CRITICAL, SERIOUS and MINOR events will raise their associated exception. Lower severity events will print out a warning message. This is the DEFAULT value.

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

The default behavior is to set exception_control_level to 4 which will raise CRITICAL, SERIOUS, and MINOR events’ associated exceptions and will issue a warning for MINOR and WARNING events. Note that CATASTROPHIC events can not be suppressed. Also that any event that issues only a warning can be shortened via the exception_control_compact_warnings flag or silenced by setting the exception_control_silent_warnings flag.

property exception_control_compact_warnings: bool

A flag that toggles compact warnings.

This boolean property toggles the use of compact warnings.

Returns:

True will set warnings to be compact in nature

and print out just a short warning rather than the full warning.

Return type:

bool

exception_control_event(event_type, exception_type, message=None)[source]

An event that conditinally raises an exception.

Triggers an event that will be handled based on the rules given by the current exception_control_level value and the severity class of this event.

Parameters:

  • event_type (str) – Sets the type of exception this is. Valid entries are [“SILENT”,” WARNING”, “MINOR”, “SERIOUS”, “CRITICAL”, “CATASTROPHIC”].

  • exception_type (object) – An Exception type that would be raised if the exception_control_level threshold is high enough to make this exception get raised. This must be an Exception (or a derivitive) type.

  • message (str) – If the exception gets triggered, what message should we pass along when it gets raised?

property exception_control_level

Get the value of the exception_control_level property.

The parameter must be convertable to an integer and must be between 0 and 5. Values below 0 will be set to 0 and values greater than 5 will be set to 5.

The default value is set to 4 (CRITICAL, SERIOUS, and MINOR events will raise an exception; WARNING events will only warn).

Returns:

The exception_control_level value.

Return type:

int

property exception_control_silent_warnings: bool

A flag that toggles silencing of warnings.

This boolean property toggles whether or not exception_control_event should silence events that don’t raise their associated exception.

Returns:

True to cause events that don’t raise their exception

to suppress their associated exception message. False if we do not wish to suppress warning messages.

Return type:

bool