Code Documentation

Provides a framework for creating quality assurance audits on digital files to ensure their integrity and reporting on any deficiencies. For example, one might use this framework to manage the validation of files created by a script to ensure they follow a specific format by parsing it and running the auditor on the resulting data structure.

At the core, this framework is similar to unittest or other testing frameworks. However, one key difference is that the auditor is robust to failures; unless a failure is defined to be a blocker, the audit will continue and all deficiencies will be reported.

class qassure.framework.AuditReport

Manages the audit report, which is a list of tuples. Wraps the list but changes append() to work better for this purpose.

append(severity, message, source)

Appends a report to the report list

Parameters

• severity (qassure.framework.Severity) – The severity to report the error as

• message (str) – The message related to the error

• source (str) – The source of the error

class qassure.framework.Auditor

Manages the audit process. This class is never instantiated directly; instead, sub-classes should be implemented by passing in the data to be audited in the constructor and implementing the audit() method with the tests:

from qassure import Auditor, Severity

class AuditDateFormatDict(Auditor):
    ''' Checks if the value is a dict with a date and format key '''

    def __init__(self, test_value):
        self.test_value = test_value

    def audit(self):
        # Make sure test_value is a dict. This a BLOCKER because we can't check the keys of non-dicts.
        self.inspect(self.test_value, Severity.BLOCKER).is_instance(dict)

        # Make sure the dict has a date key
        self.inspect(self.test_value).does_contain("date")

        # Make sure the dict has a format key
        self.inspect(self.test_value).does_contain("format")

# Will have one BLOCKER message, because it is not a dict
auditor = AuditDateFormatDict("not a dict")

# Will have two ERROR messages, because it is a dict but has the wrong keys
auditor = AuditDateFormatDict({"foo": 0, "bar": 1})

# Passes
auditor = AuditDateFormatDict({"date": None, "format": None})

add_report_item(severity: qassure.framework.Severity, message: str, last_frame: Optional[traceback.FrameSummary] = None)

Adds an item to the report. Mostly intended to be used from qassure.framework.ValueInspector to report

on deficiencies.

Parameters

• severity (qassure.framework.Severity) – The severity to log as

• message (str) – The message to log

• last_frame (traceback.FrameSummary) – Optional. If provided, it should be the most relevant frame to tracing where the error was raised

abstract audit()

Subclasses should implement this with their own testing methods.

claim(value, severity: qassure.framework.Severity = Severity.ERROR, object_name=None)

Retrieves a ValueInspector object that can be used to make claims about a value:

:param value: The value to make claims about
:type value: any
:param severity: The severity of failing those claims
:type severity: qassure.framework.Severity
:param object_name: A name to use for the object in error message. If not provided, one will attempt to be loaded from the stack trace.
:return: A class to use for making claims about the value.
:rtype: qassure.framework.ClaimInspector

get_report() → qassure.framework.AuditReport

Runs the audit if it hasn’t been run and returns the report

Returns

The audit report

Return type

qassure.framework.AuditReport

passed(max_level=Severity.WARNING)

Runs the audit if it hasn’t been run and returns whether any deficiencies exceed the given severity.

Parameters

max_level (qassure.framework.Severity) – The maximum severity level that can be encountered.

Returns

Whether any errors with severity greater than max_level were encountered.

Return type

bool

run_audit()

Runs the audit if it hasn’t already been run.

The main purpose of this approach is to allow claims to raise qassure.framework.BlockingDeficiencyError when appropriate so that the audit ends gracefully.

exception qassure.framework.BlockingDeficiencyError

Error to raise when something is blocking further auditing

class qassure.framework.ClaimInspector(agent: qassure.framework.Auditor, error_level: qassure.framework.Severity, value: Any, object_name=None)

Responsible for making claims about a value

Parameters

• agent (qassure.framework.Auditor) – The agent managing the report

• error_level (qassure.framework.Severity) – The severity of any deficiencies.

• value (any) – The value to inspect

• object_name (str) – A useful value to show in error messages, defaults to [provided value]

contains(value, msg=None)

Checks that the value contains another value

Parameters

• value (any) – The value to check is in self.value

• msg (str) – The message to set if the claim is false, or None to use the default

if_is_type(cls: type)

Only continue checking claims if the value is an instance of the given type.

Parameters

cls (type) – The type to check against

if_not_none()

Only continue checking claims if the value is not None

is_callable(msg=None)

Checks if the value is callable, using callable()

Parameters

msg (str) – The message to set if the claim is false, or None to use the default

is_equal_to(value, msg=None)

Checks if the value is None.

Parameters

• value (any) – The value to check against

• msg (str) – The message to set if the claim is false, or None to use the default

is_none(msg=None)

Checks if the value is None.

Parameters

msg (str) – The message to set if the claim is false, or None to use the default

is_not_none(msg=None)

Checks if the value is not None.

Parameters

msg (str) – The message to set if the claim is false, or None to use the default

is_truthy(msg=None)

Checks if the value is truthy

Parameters

msg (str) – The message to set if the claim is false, or None to use the default

is_type(cls: type, msg=None)

Checks if the value is an instance of a type, using isinstance().

Parameters

• cls (type) – The type to check against

• msg (str) – The message to set if the claim is false, or None to use the default

raises(exception_type: type, *args, msg=None, **kwargs)

Checks that calling the value with the given args and kwargs raises the given exception.

Parameters

• exception_type – The type of exception that should be raised.

• msg (str) – The message to set if the claim is false, or None to use the default

class qassure.framework.NoOpInspector

For use with the if_*() methods, this is a version of qassure.framework.ClaimInspector that doesn’t report any errors ever. Returned if an if_*() method is not true.

class qassure.framework.Severity(value)

The severity of a deficiency

BLOCKER = 50

The audit cannot proceed because of this error.

CRITICAL = 40

A deficiency that has a serious impact on the end-user and must be resolved

ERROR = 30

A deficiency that impacts the end-user and should be resolved

INFO = 10

This severity is for sharing messages that do not require resolution

WARNING = 20

A deficiency that is less than ideal, but will not significantly impact the end-user