Utility functions

utility_functions ¶

Module containing utility functions to support re-use in python scripts.

PropagatingThread ¶

Class to support running commands from the shell in a python environment.

Don't use directly.

PropagatingThread copied from sample here:

reader ¶

reader(
    filepath,
    outstream,
    stream,
    logging_level=logging.INFO,
    encodingErrors="strict",
)

Helper functions for running commands from the shell in python environment.

Don't use directly

process output stream and write to log. part of the threading pattern.

GetHostInfo ¶

GetHostInfo() -> namedtuple

Returns a namedtuple containing information about host machine.

Returns:

Type	Description
`namedTuple[Host(os, arch, bit)]`	Host(os=OS Type, arch=System Architecture, bit=Highest Order Bit)

timing ¶

timing(f: Callable) -> Callable

This is a mixing to do timing on a function.

Example

    @timing
    def function_i_want_to_time():

RunCmd ¶

RunCmd(
    cmd: str,
    parameters: str,
    capture: bool = True,
    workingdir: str = None,
    outfile: Optional[str] = None,
    outstream: Optional[str] = None,
    environ: Optional[dict] = None,
    logging_level: int = logging.INFO,
    raise_exception_on_nonzero: bool = False,
    encodingErrors: str = "strict",
    close_fds: bool = True,
) -> int

Run a shell command and print the output to the log file.

This is the public function that should be used to run commands from the shell in python environment

Attributes:

Name	Type	Description
`cmd`		command being run, either quoted or not quoted
`parameters`		parameters string taken as is
`capture`	`obj`	boolean to determine if caller wants the output captured in any format.
`workingdir`	`obj`	path to set to the working directory before running the command.
`outfile`	`obj`	capture output to file of given path.
`outstream`	`obj`	capture output to a stream.
`environ`	`obj`	shell environment variables dictionary that replaces the one inherited from the current process.
`logging_level`	`obj`	log level to log output at. Default is INFO
`raise_exception_on_nonzero`	`obj`	Setting to true causes exception to be raised if the cmd return code is not zero.
`encodingErrors`	`obj`	may be given to set the desired error handling for encoding errors decoding cmd output. Default is 'strict'.
`close_fds`	`obj`	If True, file descriptors are closed before the command is run. Default is True.

Returns:

Type	Description
`int`	returncode of called cmd

RunPythonScript ¶

RunPythonScript(
    pythonfile: str,
    params: str,
    capture: bool = True,
    workingdir: Optional[str] = None,
    outfile: Optional[str] = None,
    outstream: Optional[str] = None,
    environ: Optional[dict] = None,
    logging_level: int = logging.INFO,
    raise_exception_on_nonzero: bool = False,
) -> int

Run a python script and print the output to the log file.

This is the public function that should be used to execute python scripts from the shell in python environment. The python script will be located using the path as if it was an executable.

Parameters:

Name	Type	Description	Default
`pythonfile`	`str`	python file to execute	required
`params`	`str`	parameters string taken as is	required
`capture`	`bool`	if caller wants the output captured in any format.	`True`
`workingdir`	`Optional[str]`	path to set to the working directory before running the command.	`None`
`outfile`	`Optional[str]`	capture output to file of given path.	`None`
`outstream`	`Optional[str]`	capture output to a stream.	`None`
`environ`	`Optional[dict]`	shell environment variables dictionary that replaces the one inherited from the current process.	`None`
`logging_level`	`int`	log level to log output at. Default is INFO	`INFO`
`raise_exception_on_nonzero`	`bool`	causes exception to be raised if the cmd return code is not zero.	`False`

Returns:

Type	Description
`int`	returncode of called cmd

DetachedSignWithSignTool ¶

DetachedSignWithSignTool(
    SignToolPath: str,
    ToSignFilePath: str,
    SignatureOutputFile: str,
    PfxFilePath: str,
    PfxPass: Optional[str] = None,
    Oid: str = "1.2.840.113549.1.7.2",
    Eku: Optional[str] = None,
) -> int

Locally Sign input file using Windows SDK signtool.

This will use a local Pfx file. WARNING: This should not be used for production signing as that process should follow stronger security practices (HSM / smart cards / etc)

Signing is in format specified by UEFI authentacted variables

CatalogSignWithSignTool ¶

CatalogSignWithSignTool(
    SignToolPath: str,
    ToSignFilePath: str,
    PfxFilePath: str,
    PfxPass: Optional[str] = None,
) -> int

Locally sign input file using Windows SDK signtool.

This will use a local Pfx file.

This should not be used for production signing as that process should follow

stronger security practices (HSM / smart cards / etc)

Signing is catalog format which is an attached signature

version_compare ¶

version_compare(version1: str, version2: str) -> bool

Compare two versions.

import_module_by_file_name ¶

import_module_by_file_name(module_file_path: str) -> Any

Standard method of importing a Python file. Expecting absolute path.

locate_class_in_module ¶

locate_class_in_module(
    Module: Any, DesiredClass: Any
) -> Any

Given a module and a class, this function will return the subclass of DesiredClass found in Module.

It gives preference to classes that are defined in the module itself. This means that if you have an import that subclasses DesiredClass, it will be picked unless there is a class defined in the module that subclasses DesiredClass.

In this hypothetical class hierarchy, GrandChildClass would be picked -------------- ------------ ----------------- |DesiredClass| -> |ChildClass| -> |GrandChildClass| -------------- ------------ -----------------

RemoveTree ¶

RemoveTree(
    dir_path: str, ignore_errors: bool = False
) -> None

Helper for removing a directory.

On error try to change file attributes. Also adds retry logic.

Parameters:

Name	Type	Description	Default
`dir_path`	`str`	Path to directory to remove.	required
`ignore_errors`	`bool`	ignore errors during removal	`False`

PrintByteList ¶

PrintByteList(
    ByteList: bytearray,
    IncludeAscii: bool = True,
    IncludeOffset: bool = True,
    IncludeHexSep: bool = True,
    OffsetStart: int = 0,
    **kwargs: Any
) -> None

Print a byte array as hex and optionally output ascii as well as offset within the buffer.

hexdump ¶

hexdump(
    byte_list: bytearray,
    offset_start: int = 0,
    outfs: BytesIO = sys.stdout,
    **kwargs: Any
) -> None

Print a byte array as hex and optionally output ascii as well as offset within the buffer.

Parameters:

Name	Type	Description	Default
`byte_list`	`bytearray`	byte array to print	required
`offset_start`	`int`	offset to print to the side of the hexdump	`0`
`outfs`	`BytesIO`	output file stream to print to	`stdout`
`kwargs`	`Any`	keyword arguments expanded below.	`{}`

Other Parameters:

Name	Type	Description
`include_ascii`	`bool`	Option (Default: True) to include ascii
`include_offset`	`bool`	Option (Default: True) to include the offset
`include_hex_sep`	`bool`	Option (Default: True) to include the hex seperator

Returns:

Type	Description
`None`	None

export_c_type_array ¶

export_c_type_array(
    buffer_fs: BytesIO,
    variable_name: str,
    out_fs: StringIO,
    **kwargs: Any
) -> None

Converts a given binary file to a UEFI typed C style array.

Parameters:

Name	Type	Description	Default
`buffer_fs`	`BytesIO`	buffer file stream to turn into a C style array	required
`variable_name`	`str`	variable name to use for the C style array	required
`out_fs`	`StringIO`	output filestream to write to	required
`kwargs`	`Any`	keyword arguments expanded below.	`{}`

Other Parameters:

Name	Type	Description
`data_type`	`str`	The datatype of the array (Default: UINT8)
`length_data_type`	`str`	The datatype of the length field (Default: UINTN)
`is_array`	`bool`	if true includes '[]' (Default: True)
`bytes_per_row`	`int`	number of bytes to include per row (Default: 16)
`indent`	`str`	the characters to use for indention (Default: ' ' (2 spaces))
`length_variable_name`	`str`	name to use for the length variable
`include_ascii`	`bool`	includes a ascii comment to side of hex
`include_length`	`bool`	includes length in the decleration of array (ex. "UINT8 TestVariable[13] = {")

Return

None

Raises:

Type	Description
`ValueError`	Binary file length was 0