Output fingerprinting

Modules with fingerprint generators:

fingerprints
fingerprints.base

Writing a custom fingerprinting function

Writing a custom fingerprint implementation for a particular kind of output is pretty straightforward. Start by creating a function with the following interface:

def fp_my_fingerprint(fname, fpinfo, tags):
  pass

The variable fname will contain the filename/path of the output for which a fingerprint shall be created. fpinfo is an empty dictionary to which the content of the fingerprint needs to be added. A test runner will add this dictionary to the fingerprints section of the respective output file in the SPEC. The name of the fingerprinting function itself will be used as key for this fingerprint element in that section. Any fp_-prefix, as in the example above, will be stripped from the name. Finally, tags is a sequence of Output tags that categorize a file and can be used to adjust the content of a fingerprint accordingly.

Any fingerprinting function must add a __version__ tag to the fingerprint. The version must be incremented whenever the fingerprint implementation changes, to make longitudinal comparisons of test results more accurate.

There is no need to return any value – all content needs to be added to the fpinfo dictionary.

A complete implementation of a fingerprinting function that stores the size of an input file could look like this:

>>> import os
>>> def fp_file_size(fname, fpinfo, tags):
...   fpinfo['__version__'] = 0
...   fpinfo['size'] = os.path.getsize(fname)
>>> #
>>> # test it
>>> #
>>> from testkraut.fingerprints import proc_fingerprint
>>> fingerprints = {}
>>> proc_fingerprint(fp_file_size, fingerprints, 'COPYING')
>>> 'file_size' in fingerprints
True
>>> 'size' in fingerprints['file_size']
True

There is no need to catch exceptions inside fingerprinting functions. The test runner will catch any exception and everything that has been stored in the fingerprint content dictionary up to when the exception occurred will be preserved. The exception itself will be logged in a __exception__ field.

To enable the new fingerprinting function, add it to any appropriate tag in the fingerprints section of the configuration file:

[fingerprints]
want size = myownpackage.somemodule.fp_file_size

With this configuration this fingerprint will be generated for any output that is tagged want size. It is required that the function is “importable” from the specified location.