buildgrid.utils module

class buildgrid.utils.BrowserURL(base_url: str, instance_name: str | None = None)

Bases: object

for_message(message_type: str, message_digest: Digest) → bool

Completes browser URL initialization for a protobuf message.

generate() → str | bytes | None

Generates a browser URL string.

class buildgrid.utils.HashableDigest(hash: str, size_bytes: int)

Bases: object

hash: str

size_bytes: int

to_digest() → Digest

buildgrid.utils.get_hash_type() → int

Returns the hash type.

buildgrid.utils.create_digest(bytes_to_digest: bytes) → Digest

Computes the Digest of a piece of data.

The Digest of a data is a function of its hash and size.

Parameters:

bytes_to_digest (bytes) – byte data to digest.

Returns:

The Digest for the given byte data.

Return type:

Digest

buildgrid.utils.create_digest_from_file(file_obj: BinaryIO) → Digest

Computed the Digest of a file-like object.

The Digest contains a hash of the file’s contents and the size of those contents. This function only reads the content in chunks for hashing, so is safe to use on large files.

Parameters:

file_obj (BinaryIO) – A file-like object of some kind.

Returns:

The Digest for the given file object.

Return type:

Digest

buildgrid.utils.parse_digest(digest_string: str) → Digest | None

Creates a Digest from a digest string.

A digest string should alway be: {hash}/{size_bytes}.

Parameters:

digest_string (str) – the digest string.

Returns:

The Digest read from the string or None if

digest_string is not a valid digest string.

Return type:

Digest

buildgrid.utils.validate_digest_data(digest: Digest, data: bytes) → bool

Validate that the given digest corresponds to the given data.

buildgrid.utils.read_file(file_path: str) → bytes

Loads raw file content in memory.

Parameters:

file_path (str) – path to the target file.

Returns:

Raw file’s content until EOF.

Return type:

bytes

Raises:

OSError – If file_path does not exist or is not readable.

buildgrid.utils.read_and_rewind(read_head: IO) → AnyStr | None

Reads from an IO object and returns the data found there after rewinding the object to the beginning.

Parameters:

read_head (IO) – readable IO head

Returns:

readable content from read_head.

Return type:

AnyStr

buildgrid.utils.merkle_tree_maker(directory_path: str) → Iterator[Tuple[FileNode | DirectoryNode, BinaryIO, str]]

Walks a local folder tree, generating FileNode and DirectoryNode.

Parameters:

directory_path (str) – absolute or relative path to a local directory.

Yields:

Message, bytes, str – a tutple of either a FileNode or DirectoryNode message, the corresponding blob and the corresponding node path.

buildgrid.utils.convert_values_to_sorted_lists(dictionary: Mapping[str, str | Sequence[str] | Set[str]]) → Dict[str, List[str]]

Given a dictionary, do the following:

1. Turn strings into singleton lists

2. Turn all other sequence types into sorted lists with list()

This returns the converted dictionary and does not change the dictionary that was passed in.

buildgrid.utils.hash_from_dict(dictionary: Mapping[str, List[str]]) → str

Get the hash represntation of a dictionary

buildgrid.utils.get_unique_objects_by_attribute(objects: Sequence[T], attribute: str) → Iterable[T]

Return a list of unique objects based on a hashable attribute or chained attributes.

Note that this does not provide any sanitization, and any problematic elements will only raise exceptions when iterated on.

buildgrid.utils.retry_delay(retry_attempt: int, delay_base: int = 1) → float

buildgrid.utils.flatten_capabilities(capabilities: Mapping[str, Set[str] | List[str]]) → List[Tuple[str, str]]

Flatten a capabilities dictionary.

This method takes a capabilities dictionary and flattens it into a list of key/value tuples describing all the platform properties that the capabilities map to. To do this, it assumes that all of the dictionary’s values are iterable.

For example,

{'OSFamily': {'Linux'}, 'ISA': {'x86-32', 'x86-64'}}

becomes

[('OSFamily', 'Linux'), ('ISA', 'x86-32'), ('ISA', 'x86-64')]

Parameters:

capabilities (dict) – The capabilities dictionary to flatten.

Returns:

list containing the flattened dictionary key-value tuples.