vinegar.utils.version

Utility functions for calculating version strings.

Version strings provide a simple tool for finding out whether a specific resource has changed.

Internally, they are calculated using the Murmur 3 hash function (if the mmh3 module is available) or the MD5 hash function. Both these hash functions are designed in a way that accidental collisions are very unlikely.

Due to the nature of hash functions, a collision can never be avoided with absolute certainty, so version strings should only be used when the risk associated with using an outdated resource is acceptable.

vinegar.utils.version.aggregate_version(versions: Iterable[str]) → str

Calculate an aggregate version from several version strings.

The aggregate version string is created by calculated a hash over the input version numbers. The hash function is chosen so that accidental collisions are very unlikely.

Parameters:

versions – iterable object that provides str objects that represent the input version strings.

Returns:

aggregate version string based on the input versions.

vinegar.utils.version.version_for_file_path(file_path: str | PurePath) → str

Return a version string for a file.

The returned version string is calculated based on the file path and the file’s ctime and mtime (if the file exists).

By principle, this function cannot detect when the file content changes without changing the ctime or mtime. This might happen, if the ctime and mtime are deliberately reset to their old values or if the file is changed in rapid succession and the time precision of the underlying file-system is not sufficient to detect that.

Parameters:

file_path – string or PurePath instance that represents the path to the file.

Returns:

version string based on the file’s ctime and mtime.

vinegar.utils.version.version_for_str(data: str) → str

Returns a version string for a string.

Effectively, this function simply calculates a hash on the string. This has the effect that different strings should (typically) result in different version strings, unless a hash collision occurs.

Parameters:

data – string to be hashed.

Returns:

hash-based version string.