Utility and helper modules

Utilities overview

Module: cli_util

Command line utilities.

varats.utils.cli_util.cli_yn_choice(question, default='y')[source]

Ask the user to make a y/n decision on the cli.

Return type

bool

varats.utils.cli_util.cli_list_choice(question, choices, choice_to_str, on_choice_callback, start_label=0, default=0, repeat=False)[source]

Ask the user to select an item from a list on the cli.

Parameters

  • question (str) – the question to ask the user

  • choices (List[TypeVar(ListType)]) – the choices the user has

  • choice_to_str (Callable[[TypeVar(ListType)], str]) – a function converting a choice to a string

  • on_choice_callback (Callable[[TypeVar(ListType)], None]) – action to perform when a choice has been made

  • start_label (int) – the number label of the first choice

  • default (int) – the default choice that is taken if no input is given

  • repeat (bool) – whether to ask for another choice after on_choice_callback has finished

Return type

None

varats.utils.cli_util.initialize_cli_tool()[source]

Initializes all relevant context and tools for varats cli tools.

Return type

None

varats.utils.cli_util.initialize_logger_config()[source]

Initializes the logging framework with a basic config, allowing the user to pass the warning level via an environment variable LOG_LEVEL.

Return type

None

Module: exceptions

This module contains custom exceptions.

exception varats.utils.exceptions.ProcessTerminatedError[source]

Bases: Exception

Raised if a process was terminated.

exception varats.utils.exceptions.ConfigurationLookupError[source]

Bases: Exception

Raised if a paper config could not be found.

exception varats.utils.exceptions.ConfigurationMapConfigIDMissmatch[source]

Bases: Exception

Raised if the config ID parsed from a file did not match the actual created ID, this happens when IDs are missing in the file.

Module: git_util

Utility module for handling git repos.

varats.utils.git_util.get_current_branch(repo_folder=None)[source]

Get the current branch of a repository, e.g., HEAD.

Parameters

repo_folder (Optional[Path]) – where the git repository is located

Returns: branch name

Return type

str

class varats.utils.git_util.ChurnConfig[source]

Bases: object

The churn config allows the user to change how code churn is calculated.

Churn is by default calulcated considering all files in a repository. Users can select a specific set of file extensions to only be considered in the code churn, e.g., by selecting h and c only C related files will be used to compute the code churn.

class Language(value)[source]

Bases: enum.Enum

Enum for different languages that can be used to filter code churn.

value: Set[str]
C = {'c', 'h'}
CPP = {'cpp', 'cxx', 'h', 'hpp', 'hxx'}
static create_default_config()[source]

Create a default configuration that includes all files in the code churn, e.g., enabling all languages/file extensions.

Return type

ChurnConfig

static create_c_language_config()[source]

Create a config that only allows C related files, e.g., headers and source files.

Return type

ChurnConfig

static create_c_style_languages_config()[source]

Create a config that allows all files related to C-style languages, i.e., C/CPP.

Return type

ChurnConfig

static init_as_default_if_none(config)[source]

Returns a default initialized config or the passed one.

Parameters

config (Optional[ChurnConfig]) – possibly initialized config

Return type

ChurnConfig

Returns

passed config or a default initialized one

property include_everything: bool

Checks if all files should be considered in the code churn.

Return type

bool

Returns

True, if no specific language is enabled

property enabled_languages: List[varats.utils.git_util.ChurnConfig.Language]

Returns a list of specifically enabled languages.

Return type

List[Language]

is_enabled(file_extension)[source]

Checks if a file_extension is enabled.

Parameters

file_extension (str) – extension of a file, e.g., h for foo.h

Return type

bool

Returns

True, if the extension is currently enabled in the config

is_language_enabled(language)[source]

Checks if a language is enabled.

Parameters

language (Language) – language to check

Return type

bool

Returns

True, if the language was enabled

enable_language(language)[source]

Enable language in the config.

Return type

None

disable_language(language)[source]

Disable language in the config.

Return type

None

get_extensions_repr(prefix='', suffix='')[source]

Returns a list that contains all file extensions from all enabled languages extended with the passed pre-/suffix.

Parameters

  • prefix (str) – prefix adding to the strings head

  • suffix (str) – suffix adding to the strings tail

Return type

List[str]

Returns

list of modified string file extensions

varats.utils.git_util.create_commit_lookup_helper(project_name)[source]

Creates a commit lookup function for project repositories.

Parameters

project_name (str) – name of the given benchbuild project

Return type

Callable[[str, str], Commit]

Returns

a Callable that maps a commit hash and repository name to the corresponding commit.

class varats.utils.git_util.CommitRepoPair(commit_hash, repo_name)[source]

Bases: object

Pair of a commit hash and the name of the repository it is based in.

property commit_hash: str
Return type

str

property repository_name: str
Return type

str

varats.utils.git_util.map_commits(func, cr_pair_list, commit_lookup)[source]

Maps a function over a range of commits.

Return type

Sequence[TypeVar(MappedCommitResultType)]

varats.utils.git_util.calc_code_churn_range(repo, churn_config=None, start_range=None, end_range=None)[source]

Calculates all churn values for the commits in the specified range.

[start..end]. If no range is supplied, the churn values of all commits are calculated.

Parameters

  • repo (Union[Repository, str]) – git repository

  • churn_config (Optional[ChurnConfig]) – churn config to customize churn generation

Return type

Dict[str, Tuple[int, int, int]]

Returns

dict of churn triples, where the commit hash points to (files changed, insertions, deletions)

varats.utils.git_util.calc_commit_code_churn(repo, commit, churn_config=None)[source]

Calculates churn of a specific commit.

Parameters

  • repo (Repository) – git repository

  • churn_config (Optional[ChurnConfig]) – churn config to customize churn generation

Return type

Tuple[int, int, int]

Returns

dict of churn triples, where the commit hash points to (files changed, insertions, deletions)

varats.utils.git_util.calc_code_churn(repo, commit_a, commit_b, churn_config=None)[source]

Calculates churn between two commits.

Parameters

  • repo (Repository) – git repository

  • commit_a (Commit) – base commit for diff calculation

  • commit_b (Commit) – target commit for diff calculation

  • churn_config (Optional[ChurnConfig]) – churn config to customize churn generation

Return type

Tuple[int, int, int]

Returns

dict of churn triples, where the commit hash points to (files changed, insertions, deletions)

varats.utils.git_util.calc_repo_code_churn(repo, churn_config=None)[source]

Calculates code churn for a repository.

Parameters

  • repo (Repository) – git repository

  • churn_config (Optional[ChurnConfig]) – churn config to customize churn generation

Return type

Dict[str, Tuple[int, int, int]]

Returns

dict of churn triples, where the commit hash points to (files changed, insertions, deletions)

Module: experiment_util

Utility module for BenchBuild experiments.

class varats.experiment.experiment_util.PEErrorHandler(result_folder, error_file_name, timeout_duration=None, delete_files=None)[source]

Bases: object

Error handler for process execution errors.

class varats.experiment.experiment_util.FunctionPEErrorWrapper(func, handler)[source]

Bases: object

Wrap a function call with an exception handler.

Parameters

  • func (Callable[..., Any]) – function to be executed

  • handler (PEErrorHandler) – function to handle exception

varats.experiment.experiment_util.exec_func_with_pe_error_handler(func, handler)[source]

Execute a function call with an exception handler.

Parameters

  • func (Callable[..., Any]) – function to be executed

  • handler (PEErrorHandler) – function to handle exception

Return type

None

varats.experiment.experiment_util.get_default_compile_error_wrapped(project, report_type, result_folder_template)[source]

Setup the default project compile function with an error handler.

Parameters

  • project (Project) – that will be compiled

  • report_type (Type[BaseReport]) – that should be generated

  • result_folder_template (str) – where the results will be placed

Return type

FunctionPEErrorWrapper

Returns

project compilation function, wrapped with automatic error handling

varats.experiment.experiment_util.create_default_compiler_error_handler(project, report_type, output_folder=None, binary=None)[source]

Create a default PEErrorHandler for compile errors, based on the project, report_type.

Parameters

  • project (Project) – currently under analysis

  • report_type (Type[BaseReport]) – that should be generated

  • output_folder (Optional[Path]) – where the errors will be placed

  • binary (Optional[ProjectBinaryWrapper]) – if only a specific binary is handled

Retruns: a initialized PEErrorHandler

Return type

PEErrorHandler

varats.experiment.experiment_util.create_default_analysis_failure_handler(project, report_type, output_folder=None, binary=None, timeout_duration=None)[source]

Create a default PEErrorHandler for analysis failures, based on the project, report_type.

Parameters

  • project (Project) – currently under analysis

  • report_type (Type[BaseReport]) – that should be generated

  • output_folder (Optional[Path]) – where the errors will be placed

  • binary (Optional[ProjectBinaryWrapper]) – if only a specific binary is handled

  • timeout_duration (Optional[str]) – set timeout

Retruns: a initialized PEErrorHandler

Return type

PEErrorHandler

varats.experiment.experiment_util.create_default_error_handler(project, report_type, error_type, output_folder=None, binary=None, timeout_duration=None)[source]

Create a default PEErrorHandler based on the project, report_type.

Parameters

  • project (Project) – currently under analysis

  • report_type (Type[BaseReport]) – that should be generated

  • error_type (FileStatusExtension) – a FSE describing the problem type

  • output_folder (Optional[Path]) – where the errors will be placed

  • timeout_duration (Optional[str]) – set timeout

  • binary (Optional[ProjectBinaryWrapper]) – if only a specific binary is handled

Retruns: a initialized PEErrorHandler

Return type

PEErrorHandler

varats.experiment.experiment_util.wrap_unlimit_stack_size(cmd)[source]

Wraps a command with prlimit to be executed with max stack size, i.e., setting the soft limit to the hard limit.

Parameters

cmd (Callable[..., Any]) – command that should be executed with max stack size

Returns: wrapped command

Return type

Any

class varats.experiment.experiment_util.VersionExperiment(name=NOTHING, projects=NOTHING, id=NOTHING, schema=NOTHING, container=NOTHING)[source]

Bases: benchbuild.experiment.Experiment

Base class for experiments that want to analyze different project revisions.

abstract actions_for_project(project)[source]

Get the actions a project wants to run.

Return type

List[Step]

sample(prj_cls)[source]

Adapt version sampling process if needed, otherwise fallback to default implementation.

Parameters

prj_cls (Type[Project]) – project class

Return type

List[Dict[str, Variant]]

Returns

list of sampled versions

name: str
projects: List[Type[benchbuild.project.Project]]
container: benchbuild.environments.domain.declarative.ContainerImage

Module: project_util

Utility module for BenchBuild project handling.

exception varats.project.project_util.CompilationError[source]

Bases: Exception

Exception raised if an error during the compilation was discovered.

varats.project.project_util.get_project_cls_by_name(project_name)[source]

Look up a BenchBuild project by it’s name.

Return type

Type[Project]

varats.project.project_util.get_primary_project_source(project_name)[source]
Return type

FetchableSource

varats.project.project_util.get_local_project_git_path(project_name, git_name=None)[source]

Get the path to the local download location of a git repository for a given benchbuild project.

Parameters

  • project_name (str) – name of the given benchbuild project

  • git_name (Optional[str]) – name of the git repository, i.e., the name of the repository folder. If no git_name is provided, the name of the primary source is used.

Return type

Path

Returns

Path to the local download location of the git repository.

varats.project.project_util.get_extended_commit_lookup_source(project_name, git_name)[source]

Get benchbuild FetchableSource specified by the git_name or raise a LookupError if no match was found within the given benchbuild project.

Parameters

  • project_name (str) – name of the given benchbuild project

  • git_name (str) – name of the git repository

Return type

FetchableSource

Returns

benchbuild FetchableSource of the searched git repository

varats.project.project_util.get_local_project_git(project_name, git_name=None)[source]

Get the git repository for a given benchbuild project.

Parameters

  • project_name (str) – name of the given benchbuild project

  • git_name (Optional[str]) – name of the git repository

Return type

Repository

Returns

git repository that matches the given git_name.

varats.project.project_util.get_tagged_commits(project_name)[source]

Get a list of all tagged commits along with their respective tags.

Return type

List[Tuple[str, str]]

varats.project.project_util.get_all_revisions_between(c_start, c_end, short=False)[source]

Returns a list of all revisions between two commits c_start and c_end (inclusive), where c_start comes before c_end.

It is assumed that the current working directory is the git repository.

Parameters

  • c_start (str) – first commit of the range

  • c_end (str) – last commit of the range

  • short (bool) – shorten revision hashes

Return type

List[str]

varats.project.project_util.is_git_source(source)[source]

Checks if given base source is a git source.

Parameters

source (FetchableSource) – base source to check

Return type

bool

Returns

true if the base source is a git source, false ow.

class varats.project.project_util.BinaryType(value)[source]

Bases: enum.Enum

Enum for different binary types.

value: int
executable = 1
shared_library = 2
static_library = 3
class varats.project.project_util.ProjectBinaryWrapper(binary_name, path_to_binary, binary_type)[source]

Bases: object

Wraps project binaries which get generated during compilation.

>>> ProjectBinaryWrapper("binary_name", "path/to/binary",                              BinaryType.executable)
(binary_name: path/to/binary | executable)
property name: str

Name of the binary.

Return type

str

property path: pathlib.Path

Path to the binary location.

Return type

Path

property type: varats.project.project_util.BinaryType

Specifies the type, e.g., executable, shared, or static library, of the binary.

Return type

BinaryType

varats.project.project_util.wrap_paths_to_binaries_with_name(binaries)[source]

Generates a wrapper for project binaries.

>>> wrap_paths_to_binaries_with_name([("fooer", "src/foo",                                            BinaryType.executable)])
[(fooer: src/foo | executable)]

>>> wrap_paths_to_binaries_with_name([("fooer", "src/foo",                                            BinaryType.executable),                                           ("barer", "src/bar",                                            BinaryType.shared_library)])
[(fooer: src/foo | executable), (barer: src/bar | shared_library)]
Return type

List[ProjectBinaryWrapper]

varats.project.project_util.wrap_paths_to_binaries(binaries)[source]

Generates a wrapper for project binaries, automatically infering the binary name.

>>> wrap_paths_to_binaries([("src/foo", BinaryType.executable)])
[(foo: src/foo | executable)]

>>> wrap_paths_to_binaries([("src/foo.so", BinaryType.shared_library)])
[(foo: src/foo.so | shared_library)]

>>> wrap_paths_to_binaries([("src/foo", BinaryType.static_library),                                 ("src/bar",BinaryType.executable)])
[(foo: src/foo | static_library), (bar: src/bar | executable)]
Return type

List[ProjectBinaryWrapper]

exception varats.project.project_util.BinaryNotFound[source]

Bases: varats.project.project_util.CompilationError

Exception raised if an binary that should exist was not found.

static create_error_for_binary(binary)[source]

Creates a BinaryNotFound error for a specific binary.

Parameters

binary (ProjectBinaryWrapper) – project binary that was not found

Return type

BinaryNotFound

Returns

initialzied BinaryNotFound error

varats.project.project_util.verify_binaries(project)[source]

Verifies that all binaries for a given project exist.

Return type

None

varats.project.project_util.copy_renamed_git_to_dest(src_dir, dest_dir)[source]

Renames git files that were made git_storable (e.g., .gitted) back to their original git name and stores the renamed copy at the destination path. The original files stay untouched. Renaming and copying will be skipped if the dest_dir already exists.

Parameters

  • src_dir (Path) – path to the source directory

  • dest_dir (Path) – path to the destination directory

Return type

None

class varats.project.project_util.VaraTestRepoSubmodule(remote, local, clone=True, limit=10, refspec='HEAD', shallow=True, version_filter=<function Git.<lambda>>)[source]

Bases: benchbuild.source.git.GitSubmodule

A project source for submodule repositories stored in the vara-test-repos repository.

fetch()[source]
Overrides GitSubmodule s fetch to

  1. fetch the vara-test-repos repo

  2. extract the specified submodule from the vara-test-repos repo

  3. rename files that were made git_storable (e.g., .gitted) back to their original name (e.g., .git)

Return type

LocalPath

Returns

the path where the inner repo is extracted to

class varats.project.project_util.VaraTestRepoSource(remote, local, clone=True, limit=10, refspec='HEAD', shallow=True, version_filter=<function Git.<lambda>>)[source]

Bases: benchbuild.source.git.Git

A project source for repositories stored in the vara-test-repos repository.

fetch()[source]
Overrides Git s fetch to

  1. fetch the vara-test-repos repo

  2. extract the specified repo from the vara-test-repos repo

  3. rename files that were made git_storable (e.g., .gitted) back to their original name (e.g., .git)

Return type

LocalPath

Returns

the path where the inner repo is extracted to

version(target_dir, version='HEAD')[source]

Overrides Git s version to create a new git worktree pointing to the requested version.

Return type

LocalPath

Module: filesystem_util

Utility functions for handling filesystem related tasks.

exception varats.utils.filesystem_util.FolderAlreadyPresentError(folder)[source]

Bases: Exception

Exception raised if an operation could not be performed because a folder was already present, e.g., when creating folders with a script.

Logger usage

By default, the tool suite logger shows only severity levels from WARNING up to CRITICAL on the console. The log severity level can be configured by setting the environment variable LOG_LEVEL. So, for example, to get more information we can set the severity level to info by:

LOG_LEVEL=info vara-buildsetup vara -i

How to add logging to a module

For the tool suite, we do module-level logging to make it easier to trace where log output comes from. Hence, every module that logs something needs to set the logger to the current module name like this:

LOG = logging.getLogger(__name__)

What should be logged and how?

In general, the tool suite uses print for normal output that should always go to the user. Logging is used to add additional information or highlight warning or error cases. For logging categories, we follow the default python logging HOWTO.

Module: logger_util

Utility function for logging.

varats.utils.logger_util.log_without_linesep(log_func)[source]

Wraps the logger function and strips away all trailing whitespace and newline characters, making logs more reable, e.g., for bash and command line tool output.

Return type

Callable[[str], None]

Module: tool_util

Utilities for tool handling.

varats.tools.tool_util.get_research_tool_type(name)[source]

Look up the type of a research tool by name.

Parameters

name (str) – of the research tool

Returns: the research tool type corresponding to name

Return type

Union[Type[VaRA], Type[Phasar], Type[SZZUnleashed]]

varats.tools.tool_util.get_research_tool(name, source_location=None)[source]

Look up a research tool by name.

Parameters

  • name (str) – of the research tool

  • source_location (Optional[Path]) – of the research tool, if None is provided the location saved in the config will be used

Return type

ResearchTool[Any]

Returns

the research tool with the specified name, otherwise, raises LookupError

varats.tools.tool_util.get_supported_research_tool_names()[source]

Returns a list of all supported research tools.

Return type

List[str]

varats.tools.tool_util.configuration_lookup_error_handler(func)[source]

Wrapper for drivers to catch internal Exceptions and provide a helpful message to the user.

Return type

Callable[..., None]