undr.utilities

Data loading and number formatting functions.

Overview

Functions

duration_to_string	Generates a human-readable representation of a duration.
hash	Consumes an iterable and calculates a hash.
hash_file	Calculates a file’s hash.
least_multiple_over_chunk_size	Calculates the maximum number of bytes in a chunk that can be divided into full words.
load_schema	Reads and parses a JSON schema bundled with UNDR.
new_hash	Creates a new byte hasher.
path_with_suffix	Appends a suffix to a path and returns a new path.
posix_path_with_suffix	Appends a suffix to a POSIX path and returns a new path.
size_to_string	Generates a human-readable representation of a size.
speed_to_string	Generates a human-readable representation of a speed.

Module Contents

undr.utilities.duration_to_string(duration: float) → str

Generates a human-readable representation of a duration.

Parameters:

duration (float) – Positive time delta in seconds.

Returns:

Human-redable representation.

Return type:

str

undr.utilities.hash(chunks: Iterable[bytes]) → hashlib._Hash

Consumes an iterable and calculates a hash.

Since this function consumes the hash, users should use new_hash() and call hashlib._Hash.update() manually if they plan to do something else with the bytes.

Parameters:

chunks (Iterable[bytes]) – A bytes iterable.

Returns:

SHA3-224 (FIPS 202) hasher. Use hashlib._Hash.digest() or hashlib._Hash.hexdigest() to read the hash value.

Return type:

hashlib._Hash

undr.utilities.hash_file(path: pathlib.Path, chunk_size: int)

Calculates a file’s hash.

Parameters:

• path (pathlib.Path) – Path of the file to hash.

• chunk_size (int) – Chunk size in bytes, used to read the file.

Returns:

_description_

Return type:

_type_

undr.utilities.least_multiple_over_chunk_size(word_size: int) → int

Calculates the maximum number of bytes in a chunk that can be divided into full words.

For instance, for a chunks size of 100 bytes and a word size of 32 bytes, this function would return 96.

Parameters:

word_size (int) – The word size in bytes. The chunk size is not a parameter since UNDR always uses undr.constants.CHUNK_SIZE.

Returns:

Maximum number of bytes in a chunk that can be divided into full words. This number is guaranteed to be a multiple of word_size. It may be zero.

Return type:

int

undr.utilities.load_schema(name: str) → jsonschema_rs.JSONSchema

Reads and parses a JSON schema bundled with UNDR.

Parameters:

name (str) – Name of the schema.

Returns:

JSON schema validator.

Return type:

jsonschema_rs.JSONSchema

undr.utilities.new_hash() → hashlib._Hash

Creates a new byte hasher.

Returns:

SHA3-224 (FIPS 202) hasher.

Return type:

hashlib._Hash

undr.utilities.path_with_suffix(path: pathlib.Path, suffix: str) → pathlib.Path

Appends a suffix to a path and returns a new path.

Parameters:

• path (pathlib.Path) – Input path, not modified by this function.

• suffix (str) – The string to append to the path’s last component.

Returns:

New path with the given suffix.

Return type:

pathlib.Path

undr.utilities.posix_path_with_suffix(path: pathlib.PurePosixPath, suffix: str) → pathlib.PurePosixPath

Appends a suffix to a POSIX path and returns a new path.

Similar to path_with_suffix() for POSIX paths.

Parameters:

• path (pathlib.PurePosixPath) – Input path, not modified by this function.

• suffix (str) – The string to append to the path’s last component.

Returns:

New path with the given suffix.

Return type:

pathlib.PurePosixPath

undr.utilities.size_to_string(size: int) → str

Generates a human-readable representation of a size.

Parameters:

size (float) – Resource size in bytes.

Returns:

Human-redable representation.

Return type:

str

undr.utilities.speed_to_string(speed: int) → str

Generates a human-readable representation of a speed.

Parameters:

speed (int) – Download or process speed in bytes per second.

Returns:

Human-redable representation.

Return type:

str