API

Plugins

GwDbValidator

class GwDbValidator(app, **kwargs)

Automatically adds and activate validation to eahc database model.

activate()

During activation, a receiver is created and listing for new database models. Existing database models are collected and validation gets activated.

Returns:None
deactivate()

Currently nothing happens here sigh

Returns:None

Patterns

GwValidatorsPattern

class GwValidatorsPattern(app, **kwargs)

Allows the creation of hashes for python objects (and its validation).

activate()

Must be overwritten by the plugin class itself.

deactivate()

Must be overwritten by the plugin class itself.

class ValidatorsPlugin(plugin)

Cares about the Validator handling on plugin level.

get(name)

Returns a single or a list of validator instance, which were registered by the current plugin.

Parameters:name – Name of the validator. If None, all validators of the current plugin are returned.
Returns:Single or list of Validator instances
register(name, description, algorithm=None, attributes=None)

Registers a new validator on plugin level.

Parameters:
  • name – Unique name of the validator
  • description – Helpful description of the validator
  • algorithm – A hashlib compliant function. If None, hashlib.sha256 is taken.
  • attributes – List of attributes, for which the hash must be created. If None, all contained attributes are used.
Returns:

Validator instance
unregister(name)
class ValidatorsApplication(app)

Cares about the Validator handling on application level.

get(name, plugin)

Returns a single or a list of validator instance

Parameters:
  • name – Name of the validator. If None, all validators are returned.
  • plugin – Plugin instance, which has registered the requested validator. If None, all validators are returned.
Returns:

Single or list of Validator instances
register(name, description, plugin, algorithm=None, attributes=None)

Registers a new validator on application level.

Parameters:
  • name – Unique name of the validator
  • description – Helpful description of the validator
  • algorithm – A hashlib compliant function. If None, hashlib.sha256 is taken.
  • attributes – List of attributes, for which the hash must be created. If None, all contained attributes are used.
  • plugin – Plugin instance, for which the validator gets registered.
Returns:

Validator instance
unregister(name)
class Validator(name, description, algorithm=None, attributes=None, plugin=None)

Represent the final validator, which provides functions to hash a given python object and to validate a python object against a given hash.

get_hash_object()

Returns a hash object, which can be used as input for validate functions.

Returns:An unused hash object
hash(data, hash_object=None, return_hash_object=False, strict=False)

Generates a hash of a given Python object.

Parameters:
  • data – Python object
  • return_hash_object – If true, the complete hashlib object is returned instead of a hexdigest representation as string.
  • hash_object – An existing hash object, which will be updated. Instead of creating a new one.
  • strict – If True, all configured attributes must exist in the given data, otherwise an exception is thrown.
Returns:

hash as string
validate(data, hash_string)

Validates a python object against a given hash

Parameters:
  • data – Python object
  • hash_string – hash as string, which must be compliant to the configured hash algorithm of the used validator.
Returns:

True, if object got validated by hash. Else False

GwDbValidatorsPattern

class GwDbValidatorsPattern(app, **kwargs)

Allows the validation of database model requests.

Builds automatically hashes of table rows/model instances and validates these hashes, if a request is made on these rows.

activate()

Must be overwritten by the plugin class itself.

deactivate()

Must be overwritten by the plugin class itself.

class DbValidatorsPlugin(plugin)

Cares about database validators on plugin level

get(name)
register(name, description, db_class)

Registers a new database model and starts its validation.

Parameters:
  • name – Unique name
  • description – Meaningful description
  • db_class – sqlalchemy based database model
Returns:

Instance of DbValidator
unregister(name)
class DbValidatorsApplication(app)

Cares about database validators on application level

get(name, plugin)
register(name, description, db_class, plugin)

Registers a new database model and starts its validation.

Parameters:
  • name – Unique name
  • description – Meaningful description
  • db_class – sqlalchemy based database model
  • plugin – Plugin, which registers the DbValidator
Returns:

Instance of DbValidator
unregister(name)
class DbValidator(name, description, db_class, db, hash_model, plugin=None)

Class for storing a database validator. For each registered database validator an instance of this class gets created and configured.

class ValidationError

Exception, which is thrown if a validation fails.

GwFileValidatorsPattern

class GwFileValidatorsPattern(app, **kwargs)

Allows the creation and validation of hashes for given files.

Usage:

from groundwork_validation.patterns import GwFileValidatorsPattern

class My_Plugin(GwFileValidatorsPattern):
    def __init__(self, app, **kwargs):
        self.name = "My_Plugin"
        super(My_Plugin, self).__init__(app, **kwargs)

    def activate(self):
        my_hash = self.validators.file.hash("/path/to/file.txt")
        self.validators.file.validate("/path/to/file.txt", my_hash)
activate()

Must be overwritten by the plugin class itself.

deactivate()

Must be overwritten by the plugin class itself.

class FileValidatorsPlugin(plugin)
hash(file, validator=None, hash_file=None, blocksize=65536, return_hash_object=False)

Creates a hash of a given file.

Parameters:
  • file – file path of the hashable file
  • validator – validator, which shall be used. If none is given, a default validator will be used. validator should be registered be the GwValidatorsPattern. Default is None
  • hash_file – Path to a file, which is used to store the calculated hash value. Default is None
  • blocksize – Size of each file block, which is used to update the hash. Default is 65536
  • return_hash_object – Returns the hash object instead of the hash itself. Default is False
Returns:

string, which represents the hash (hexdigest)
validate(file, hash_value=None, hash_file=None, validator=None, blocksize=65536)

Validates a file against a given hash. The given hash can be a string or a hash file, which must contain the hash on the first row.

Parameters:
  • file – file path as string
  • hash_value – hash, which is used for comparision
  • hash_file – file, which contains a hash value
  • validator – groundwork validator, which shall be used. If None is given, a default one is used.
  • blocksize – Size of each file block, which is used to update the hash.
Returns:

True, if validation is correct. Otherwise False

GwCmdValidatorsPattern

class GwCmdValidatorsPattern(app, **kwargs)

Allows the validation of output, return code and execution time of a given command.

Usage:

class My_Plugin(GwCmdValidatorsPattern):
    def __init__(self, app, **kwargs):
        self.name = "My_Plugin"
        super(My_Plugin, self).__init__(app, **kwargs)

    def activate(self):
        if self.validators.cmd.validate("dir", search="my_folder"):
            print("Command 'dir' works a expected.")
        else:
            print("Command 'dir' seems not to work correctly. We stop here")
            sys.exit(1)

    def deactivate(self):
        pass
activate()

Must be overwritten by the plugin class itself.

deactivate()

Must be overwritten by the plugin class itself.

class CmdValidatorsPlugin(plugin)
validate(command, search=None, regex=None, timeout=2, allowed_return_codes=None, decode='utf-8')

Validates the output of a given command.

The validation can be based on a simple string search or on a complex regular expression. Also the return_code can be validated. As well as the execution duration by setting a timeout.

Parameters:
  • command – string, which is used as command for a new subprocess. E.g. ‘git -v’.
  • search – string, which shall be contained in the output of the command. Default is None
  • regex – regular expression, which is tested against the command output. Default is None
  • timeout – Time ins seconds, after which the execution is stopped and the validation fails. Default is 2 seconds
  • allowed_return_codes – List of allowed return values. Default is []
  • decode – Format of the console encoding, which shall be used. Default is ‘utf-8’
Returns:

True, if validation succeeded. Else False.
class NotAllowedReturnCode
class CommandTimeoutExpired