fingerprint

Fingerprints handling.

Fingerprints objects provides a synthetic view of a set of elements. The purpose is to allow users to build fingerprints based on that set of elements, and then use fingerprint comparison as fast method for determining whether the same set of elements might have changed since the last time those elements were checked.

One possible usage for fingerprints is determine whether something we built is still up to date, or should be rebuilt. For that, what we would do at the end of a successful build is we create a fingerprint using elements such as the sources we used to perform the build, the dependencies for our build, the version of the compiler, etc etc. Later on, when asking ourselves whether we need to re-build or not, we would compute a new fingerprint using the same elements, but updated to the current situation, and compare it with the one we previously computed. If different, we should rebuild.

Module Contents

Classes

Fingerprint

Fingerprint class.

Attributes

logger
FINGERPRINT_VERSION

fingerprint.logger

fingerprint.FINGERPRINT_VERSION = '1.2'

class fingerprint.Fingerprint

Fingerprint class.

Variables:

elements – a dictionary containing the checksum/id for each element part of the fingerprint. The key a string identifying the element.

add(name: str, value: str) → None

Add a fingerprint element.

Parameters:

• name – name of the new element

• value – associated value (should be a string)

Raise:

E3Error

add_dir(path: str) → None

Add a file tree to the fingerprint.

Parameters:

path – a path to a directory

add_file(filename: str) → None

Add a file element to the fingerprint.

Parameters:

filename – a path

Adding a filename element to a fingerprint is equivalent to do add an element for which key is the basename of the file and value is is the sha256 of the content

__eq__(other: object) → bool

Implement == operator for two fingerprints.

Parameters:

other – object to compare with

Two fingerprints are considered equals if both arguments are fingerprints and all elements of the fingerprint are equal

__ne__(other: object) → bool

Implement != operator for two fingerprints.

See __eq__ functions.

compare_to(other: object) → dict[str, set[str]] | None

Compare two fingerprints and return the differences.

Returns:

a dictionary that list the differences or None if the two Fingerprint are equals. The returned dictionary contains three items. ‘updated’ list the elements that are in both fingerprints but that are different, ‘obsolete’ list the elements that are only in self, and ‘new’ the elements that are only in other

Raises:

AssertError – if other is not a Fingerprint

__str__() → str

Return a string representation of the fingerprint.

checksum() → str

Return the fingerprint’s checksum.

At the moment, the fingerprint uses the SHA256 hashing algorithm to compute the checksum.

The function ensures that if two fingerprints are equal then the returned checksum for each of the fingerprint is equal.

save_to_file(filename: str) → None

Save the fingerprint to the given file.

Parameters:

filename – The name of the file where to save the fingerprint.

classmethod load_from_file(filename: str) → Fingerprint | None

Return the fingerprint saved in the given file.

Return None in the following situations:

• The file does not contain a fingerprint we recognize;

• The fingerprint has a version number we do not support.

• If the fingerprint file does not exist

Parameters:

filename – The name of the file where to load the fingerprint from.