fab.util#

Various utility functions live here - until we give them a proper place to live!

Functions

`by_type`(iterable, cls)	Find all the elements of an iterable which are of a given type.
`common_arg_parser`()	A helper function returning an argument parser with common, useful arguments controlling command line tools.
`file_checksum`(fpath)	Return a checksum of the given file.
`file_walk`(path[, ignore_folders])	Return every file in path and its sub-folders.
`get_fab_workspace`()	Read the Fab workspace from the FAB_WORKSPACE environment variable, defaulting to ~/fab-workspace.
`get_prebuild_file_groups`(prebuild_files)	Group prebuild filenames by originating artefact.
`input_to_output_fpath`(config, input_path)	Convert a path in the project's source folder to the equivalent path in the output folder.
`log_or_dot`(logger, msg)	Util function which prints a fullstop without a newline, except in debug logging where it logs a message.
`log_or_dot_finish`(logger)	Util function which completes the row of fullstops from `log_or_dot()`, by printing a newline when not in debug logging.
`string_checksum`(s)	Return a checksum of the given string.
`suffix_filter`(fpaths, suffixes)	Pull out all the paths with a given suffix from an iterable.

Classes

`CompiledFile`(input_fpath, output_fpath)	A Fortran or C file which has been compiled.
`HashedFile`(fpath, file_hash)	Create new instance of HashedFile(fpath, file_hash)
`Timer`()	A simple timing context manager.
`TimerLogger`(label[, res])	A labelled timing context manager which logs the label and the time taken.

fab.util.log_or_dot(logger, msg)#: Util function which prints a fullstop without a newline, except in debug logging where it logs a message.

fab.util.log_or_dot_finish(logger)#: Util function which completes the row of fullstops from log_or_dot(), by printing a newline when not in debug logging.

class fab.util.HashedFile(fpath, file_hash)#

Create new instance of HashedFile(fpath, file_hash)

file_hash#: Alias for field number 1

fpath#: Alias for field number 0

fab.util.file_checksum(fpath)#

Return a checksum of the given file.

This function is deterministic, returning the same result across Python invocations.

We use crc32 for now because it’s deterministic, unlike out-the-box hash. We could seed hash with a non-random or look into hashlib, if/when we want to improve this.

fab.util.string_checksum(s)#

Return a checksum of the given string.

This function is deterministic, returning the same result across Python invocations.

We use crc32 for now because it’s deterministic, unlike out-the-box hash. We could seed hash with a non-random or look into hashlib, if/when we want to improve this.

fab.util.file_walk(path, ignore_folders=None)#

Return every file in path and its sub-folders.

Parameters:

path (Union[str, Path]) – Folder to iterate.
ignore_folders (Optional[List[Path]]) – Pass in any folder if you don’t want to traverse into. Please see explanation and intended use, below. (default: None)

Return type:

Iterator[Path]

Note

The prebuild folder can contain multiple versions of a single, generated fortran file, created by multiple runs of the build config. The prebuild folder stores these copies for when they’re next needed, when they are copied out and reused. We usually won’t want to include this folder when searching for source code to analyse. To meet these needs, this function will not traverse into the given folders, if provided.

class fab.util.Timer#: A simple timing context manager.

class fab.util.TimerLogger(label, res=0.001)#: A labelled timing context manager which logs the label and the time taken.

class fab.util.CompiledFile(input_fpath, output_fpath)#

A Fortran or C file which has been compiled.

Parameters:

input_fpath – The file that was compiled.
output_fpath – The object file that was created.

fab.util.input_to_output_fpath(config, input_path)#

Convert a path in the project’s source folder to the equivalent path in the output folder.

Allows the given path to already be in the output folder.

Parameters:

config – The config object, which defines the source and output folders.
input_path (Path) – The path to transform from input to output folders.

Note: This function can also handle paths which are not in the project workspace at all. This can happen when pointing the FindFiles step elsewhere, for example. In that case, the entire path will be made relative to the source folder instead of its anchor.

fab.util.suffix_filter(fpaths, suffixes)#

Pull out all the paths with a given suffix from an iterable.

Parameters:

fpaths (Iterable[Path]) – Iterable of paths.
suffixes (Iterable[str]) – Iterable of suffixes we want.

fab.util.by_type(iterable, cls)#

Find all the elements of an iterable which are of a given type.

Parameters:

iterable – The iterable to search.
cls – The type of the elements we want.

fab.util.get_fab_workspace()#

Read the Fab workspace from the FAB_WORKSPACE environment variable, defaulting to ~/fab-workspace.

Return type:: Path

fab.util.get_prebuild_file_groups(prebuild_files)#

Group prebuild filenames by originating artefact.

Prebuild filenames have the form <stem>.<hash>.<suffix>. This function creates a dict with wildcard key <stem>.*.<suffix> with each entry mapping to a set of all matching prebuild files.

Given the input files my_mod.123.o and my_mod.456.o, returns a dict {‘my_mod.*.o’: {‘my_mod.123.o’, ‘my_mod.456.o’}}

Return type:: Dict[str, Set]

fab.util.common_arg_parser()#

A helper function returning an argument parser with common, useful arguments controlling command line tools.

More arguments can be added. The caller must call parse_args on the returned parser.

Return type:: ArgumentParser