Utility and helper modules

Utilities overview

Module: cli_util

Command line utilities.

varats.ts_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.ts_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(ListTy)]) – the choices the user has

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

  • on_choice_callback (Callable[[TypeVar(ListTy)], 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.ts_utils.cli_util.initialize_cli_tool()[source]

Initializes all relevant context and tools for varats cli tools.

Return type:

None

varats.ts_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

varats.ts_utils.cli_util.make_cli_option(*param_decls, **attrs)[source]

Create an object that represents a click command line option, i.e., the decorator object that is created by click.option().

Parameters:

  • *param_decls (str) – parameter declarations, i.e., how this option can be used

  • **attrs (Any) – attributes used to construct the option

Return type:

Callable[[Union[Callable[..., Any], Command]], Union[Callable[..., Any], Command]]

Returns:

a click CLI option that can be wrapped around a function

varats.ts_utils.cli_util.add_cli_options(command, *options)[source]

Adds click CLI options to a click command.

Parameters:

  • command (Union[Callable[..., Any], Command]) – the command

  • *options (Callable[[Union[Callable[..., Any], Command]], Union[Callable[..., Any], Command]]) – the options to add

Return type:

Union[Callable[..., Any], Command]

Returns:

the command with the added options

class varats.ts_utils.cli_util.CLIOptionConverter[source]

Bases: ABC, Generic[ConversionTy_co]

Converter for CLI option declarations.

Converters are required for CLI options that are converted to complex types by click so that they can still be properly stored in an artefact file. In general, a converter should implement a mapping from the complex type to a string value as it would be provided on the command line.

A converter can be attached to a CLI option using the function/decorator convert_value().

abstractmethod static value_to_string(value)[source]

Convert a value to its string representation.

Return type:

Union[str, List[str]]

abstractmethod static string_to_value(str_value)[source]

Construct a value from its string representation.

Return type:

Union[TypeVar(ConversionTy_co, bound= Any, covariant=True), List[TypeVar(ConversionTy_co, bound= Any, covariant=True)]]

class varats.ts_utils.cli_util.CLIOptionWithConverter(name, converter, cli_decl)[source]

Bases: Generic[ConversionTy_co]

Wrapper class that associates a converter with a CLI option declaration.

property name: str
property converter: Type[CLIOptionConverter[ConversionTy_co]]
varats.ts_utils.cli_util.convert_value(name, converter)[source]

Decorator for calls to make_cli_option() that attaches a converter.

Converters are required for CLI options that are converted to complex types by click so that they can still be properly stored in an artefact file. In general, a converter should implement a mapping from the complex type to a string value as it would be provided on the command line.

Parameters:

  • name (str) – name for the CLI option. This must be the same as the name for the click option that it wraps but with ‘-’ replaced by ‘_’.

  • converter (Type[CLIOptionConverter[TypeVar(ConversionTy_co, bound= Any, covariant=True)]]) – the converter that is attached to the option

Return type:

Callable[..., Callable[[Union[Callable[..., Any], Command]], Union[Callable[..., Any], Command]]]

Returns:

a CLI option declaration that can be used as if it was created by make_cli_option()

class varats.ts_utils.cli_util.ConfigOption(name, help_str, default, view_default=None, value=None)[source]

Bases: Generic[OptionTy]

Class representing a plot/table config option.

Values can be retrieved via the call operator.

Parameters:

  • name (str) – name of the option

  • help_str (str) – help string for this option

  • default (TypeVar(OptionTy)) – global default value for the option

  • view_default (Optional[TypeVar(OptionTy)]) – global default value when in view mode; do not pass if same value is required in both modes

  • value (Optional[TypeVar(OptionTy)]) – user-provided value of the option; do not pass if not set by user

property name: str
property default: OptionTy
property view_default: OptionTy | None
property value: OptionTy | None
with_value(value)[source]

Create a copy of this option with the given value.

Parameters:

value (TypeVar(OptionTy)) – the value for the copied option

Return type:

ConfigOption[TypeVar(OptionTy)]

Returns:

a copy of the option with the given value

to_cli_option()[source]

Create a CLI option from this option.

Return type:

Callable[[Union[Callable[..., Any], Command]], Union[Callable[..., Any], Command]]

Returns:

a CLI option for this option

value_or_default(view, default=None, view_default=None)[source]

Retrieve the value for this option.

The precedence for values is user provided value > plot-specific default > global default.

This function can also be called via the call operator.

Parameters:

  • view (bool) – whether view-mode is enabled

  • default (Optional[TypeVar(OptionTy)]) – plot-specific default value

  • view_default (Optional[TypeVar(OptionTy)]) – plot-specific default value when in view-mode

Return type:

TypeVar(OptionTy)

Returns:

the value for this option

class varats.ts_utils.cli_util.COGetter(*args, **kwargs)[source]

Bases: Protocol[OptionTy]

Getter type for options with no view default.

class varats.ts_utils.cli_util.COGetterV(*args, **kwargs)[source]

Bases: Protocol[OptionTy]

Getter type for options with view default.

varats.ts_utils.cli_util.tee(process, buffered=True)[source]

Adapted from plumbum’s TEE implementation.

Plumbum’s TEE does not allow access to the underlying popen object, which we need to properly handle keyboard interrupts. Therefore, we just copy the relevant portion of plumbum’s implementation and create the popen object by ourself.

Return type:

Tuple[int, str, str]

Module: html_util

Utility module for generating html files.

varats.ts_utils.html_util.html_page(title, content, styles)[source]

Generate a simple HTML page.

Parameters:

  • title (str) – the title of the page

  • content (str) – the content of the page

  • styles (List[str]) – a list of CSS style declarations

Return type:

str

Returns:

the HTML page as a string

Module: exceptions

This module contains custom exceptions.

exception varats.utils.exceptions.UnsupportedOperation[source]

Bases: Exception

Raised if a function is not supported by a type.

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.

exception varats.utils.exceptions.EmptyOptional[source]

Bases: Exception

Raised if an optional was converted to a value without having one.

varats.utils.exceptions.unwrap(maybe_t, conversion_reason)[source]

Unwrap an optional T to the underlying type, thowring an exception should a conversion not be possible.

Parameters:

  • maybe_t (Optional[TypeVar(T)]) – the optional that should always be a value

  • conversion_reason (str) – why maybe_t should contain a value and unwrapping should be safe

Return type:

TypeVar(T)

Returns: the ‘contained’ value inside the optional

varats.utils.exceptions.auto_unwrap(conversion_reason)[source]

Wraps a function with an automatic unwrap call, so a function that normally returns an optional is declared to always return a concrete value. Should no value be returned, an exception is raised mentioning the reason/assumtion why it was thought that the function always returns a value.

Parameters:

conversion_reason (str) – why maybe_t should contain a value and unwrapping should be save

Return type:

Callable[[Callable[..., Optional[TypeVar(T)]]], Callable[..., TypeVar(T)]]

Module: git_util

Utility module for handling git repos.

class varats.utils.git_util.CommitHash(short_commit_hash)[source]

Bases: ABC

Base class for commit hash abstractions.

property hash: str
abstractmethod static hash_length()[source]

Required length of the CommitHash.

Return type:

int

static from_pygit_commit(commit)[source]
Return type:

FullCommitHash

abstractmethod to_short_commit_hash()[source]

Return the short form of the CommitHash.

Return type:

ShortCommitHash

class varats.utils.git_util.ShortCommitHash(short_commit_hash)[source]

Bases: CommitHash

Shortened commit hash.

to_short_commit_hash()[source]

Return the short form of the CommitHash.

Return type:

ShortCommitHash

static hash_length()[source]

Required length of the CommitHash.

Return type:

int

class varats.utils.git_util.FullCommitHash(short_commit_hash)[source]

Bases: CommitHash

Full-length commit hash.

static hash_length()[source]

Required length of the CommitHash.

Return type:

int

property short_hash: str

Abbreviated commit hash.

to_short_commit_hash()[source]

Return the short form of the CommitHash.

Return type:

ShortCommitHash

startswith(short_hash)[source]
Return type:

bool

varats.utils.git_util.ShortCH

alias of ShortCommitHash

varats.utils.git_util.FullCH

alias of FullCommitHash

varats.utils.git_util.commit_hashes_sorted_lexicographically(commit_hashes)[source]
Return type:

Iterable[TypeVar(CommitHashTy, bound= CommitHash)]

varats.utils.git_util.short_commit_hashes_sorted_by_time_id(commit_hashes, commit_map)[source]
Return type:

Iterable[ShortCommitHash]

varats.utils.git_util.full_commit_hashes_sorted_by_time_id(commit_hashes, commit_map)[source]
Return type:

Iterable[FullCommitHash]

class varats.utils.git_util.RepositoryHandle(worktree_path)[source]

Bases: object

Wrapper class providing access to a git repository using either pygit2 or commandline-git.

property repo_name: str

Name of the repository, i.e., name of the worktree folder.

property worktree_path: Path

Path to the main worktree of the repository, typically the parent of the .git folder.

property repo_path: Path

Path to the git repository, i.e., the .git folder.

property pygit_repo: Repository

A pygit2 repository instance for the repository.

maybe_pygit_commit(commit_hash)[source]

Get a pygit2 commit object for a given commit hash.

Return type:

Optional[Commit]

pygit_commit(commit_hash)[source]

Get a pygit2 commit object for a given commit hash.

Raises if commit is not found.

Return type:

Commit

varats.utils.git_util.is_commit_hash(value)[source]

Checks if a string is a valid git (sha1) hash.

Parameters:

value (str) – to check

Return type:

bool

varats.utils.git_util.get_current_branch(repo)[source]

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

Parameters:

repo (RepositoryHandle) – git repository handle

Return type:

str

Returns: branch name

varats.utils.git_util.get_head_commit(repo)[source]

Get the current HEAD commit.

Parameters:

repo (RepositoryHandle) – git repository handle

Return type:

FullCommitHash

Returns: head commit hash

varats.utils.git_util.get_initial_commit(repo)[source]

Get the initial commit of a repository, i.e., the first commit made.

Parameters:

repo (RepositoryHandle) – git repository handle

Return type:

FullCommitHash

Returns: initial commit hash

varats.utils.git_util.get_submodule_commits(repo, c_head='HEAD')[source]

Get the revisions of all submodules of a repo at a given commit.

Parameters:

  • repo (RepositoryHandle) – repository to get the submodules for

  • c_head (str) – the commit to look at

Return type:

Dict[str, FullCommitHash]

Returns:

a mapping from submodule name to commit

varats.utils.git_util.get_all_revisions_between(repo, c_start, c_end, hash_type)[source]

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

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

Parameters:

  • repo (RepositoryHandle) – git repository handle

  • c_start (str) – first commit of the range

  • c_end (str) – last commit of the range

  • hash_type (Type[TypeVar(CommitHashTy, bound= CommitHash)]) – type of the commit hash to return

Return type:

List[TypeVar(CommitHashTy, bound= CommitHash)]

varats.utils.git_util.typed_revision_range(repo, rev_range, hash_type)[source]

Typed iterator for revision ranges.

Parameters:

  • repo (RepositoryHandle) – git repository handle

  • rev_range (AbstractRevisionRange) – the revision range to iterate

  • hash_type (Type[TypeVar(CommitHashTy, bound= CommitHash)]) – the commit type to use for iteration

Return type:

Iterator[TypeVar(CommitHashTy, bound= CommitHash)]

Returns:

an iterator over the typed commits in the range

varats.utils.git_util.get_commits_before_timestamp(repo, timestamp)[source]

Get all commits before a specific timestamp (given as a git date format).

Note: for imprecise timestamps (e.g., only 2020), the day and month will default to today.

Parameters:

  • repo (RepositoryHandle) – git repository handle

  • timestamp (str) – before which commits should be collected

Return type:

List[FullCommitHash]

Returns: list[last_commit_before_timestamp, …, initial_commits]

varats.utils.git_util.get_commits_after_timestamp(repo, timestamp)[source]

Get all commits after a specific timestamp (given as a git date format).

Note: for imprecise timestamps (e.g., only 2020), the day and month will default to today.

Args:

repo: git repository handle timestamp: after which commits should be collected

Returns: list[newest_commit, …, last_commit_after_timestamp]

Return type:

List[FullCommitHash]

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

Check if a commit contains source code of any language specified with the churn config.

Parameters:
Return type:

bool

Returns: True, if source code of a language, specified in the churn

config, was found in the commit

varats.utils.git_util.num_commits(repo, c_start='HEAD')[source]

Count the commits in a git repo starting from the given commit back to the initial commit.

Parameters:

  • repo (RepositoryHandle) – git repository handle

  • c_start (str) – commit to start counting at

Return type:

int

Returns:

the number of commits

varats.utils.git_util.num_authors(repo, c_start='HEAD')[source]

Count the authors in a git repo starting from the given commit back to the initial commit.

Parameters:

  • repo (RepositoryHandle) – git repository handle

  • c_start (str) – commit to start counting at

Return type:

int

Returns:

the number of authors

varats.utils.git_util.get_authors(repo, c_start='HEAD')[source]

Get the authors in a git repo starting from the given commit back to the initial commit.

Parameters:

  • repo (RepositoryHandle) – git repository handle

  • c_start (str) – commit to start counting at

Return type:

Set[str]

Returns:

the number of authors

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(*values)[source]

Bases: Enum

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

value: Set[str]
C = {'c', 'h'}
CPP = {'cc', '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.

Returns:

True, if no specific language is enabled

property enabled_languages: List[Language]

Returns a list of specifically enabled languages.

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

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: FullCommitHash
property repository_name: str
varats.utils.git_util.get_submodule_head(repo, submodule, commit)[source]

Retrieve the checked out commit for a submodule of a project.

Parameters:
Return type:

FullCommitHash

Returns:

checked out commit of the submodule

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 (RepositoryHandle) – git repository handle

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

Return type:

Dict[FullCommitHash, 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_hash, churn_config=None)[source]

Calculates churn of a specific commit.

Parameters:
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:
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 (RepositoryHandle) – git repository handle

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

Return type:

Dict[FullCommitHash, 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_loc(repo, rev_range)[source]

Calculate the LOC for a repository.

Parameters:

  • repo (RepositoryHandle) – handle for the repository to calculate the LOC for

  • rev_range (str) – the revision range to use for LOC calculation

Return type:

int

Returns:

the number of lines in source-code files

varats.utils.git_util.has_branch(repo, branch_name)[source]

Checks if a branch exists in the local repository.

Return type:

bool

varats.utils.git_util.has_remote_branch(repo, branch_name, remote)[source]

Checks if a remote branch of a repository exists.

Return type:

bool

varats.utils.git_util.branch_has_upstream(repo, branch_name, upstream='origin')[source]

Check if a branch has an upstream remote.

Return type:

bool

class varats.utils.git_util.RepositoryAtCommit(repo, revision)[source]

Bases: object

Context manager to work with a repository at a specific revision, without duplicating the repository.

Module: github_util

Utility module for working with the pygithub API.

varats.utils.github_util.get_github_instance()[source]

Creates a Github instance using a github access token if configured.

Return type:

Github

Returns:

a Github instance

varats.utils.github_util.get_cached_github_object(cached_object_key, load_function)[source]

Transparently caches a GithubObj loaded by the given function.

Parameters:

  • cached_object_key (str) – unique name to identify the GithubObj

  • load_function (Callable[[Github], TypeVar(PyGithubObj, bound= GithubObject)]) – function that loads a GithubObj

Return type:

TypeVar(PyGithubObj, bound= GithubObject)

Returns:

the fetched or cached GithubObj

varats.utils.github_util.get_cached_github_object_list(cached_object_key, load_function)[source]

Transparently caches a PaginatedList of GithubObjs loaded by the given function.

Parameters:

  • cached_object_key (str) – unique name to identify the GithubObj list

  • load_function (Callable[[Github], PaginatedList[TypeVar(PyGithubObj, bound= GithubObject)]]) – function that loads a PaginatedList of PygithubObjs

Return type:

List[TypeVar(PyGithubObj, bound= GithubObject)]

Returns:

the fetched or cached list of GithubObjs

varats.utils.github_util.get_github_repo_name_for_project(project)[source]

Finds the github repo name corresponding to a given github project.

Parameters:

project (Type[Project]) – class of said project

Return type:

Optional[str]

Returns:

the github repo name for the project or None if the given project is not a github project

Module: experiment_util

Utility module for BenchBuild experiments.

varats.experiment.experiment_util.get_varats_result_folder(project)[source]

Get the project specific path to the varats result folder.

Parameters:

project (Project) – to lookup the result folder for

Return type:

Path

Returns:

path to the project specific result folder

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(experiment_handle, project, report_type)[source]

Setup the default project compile function with an error handler.

Parameters:

  • experiment_handle (ExperimentHandle) – handle to the current experiment

  • project (Project) – that will be compiled

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

Return type:

FunctionPEErrorWrapper

Returns:

project compilation function, wrapped with automatic error handling

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

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

Parameters:

  • experiment_handle (ExperimentHandle) – handle to the current experiment

  • project (Project) – currently under analysis

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

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

Return type:

PEErrorHandler

Retruns: a initialized PEErrorHandler

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

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

Parameters:

  • experiment_handle (ExperimentHandle) – handle to the current experiment

  • project (Project) – currently under analysis

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

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

  • timeout_duration (Optional[str]) – set timeout

Return type:

PEErrorHandler

Retruns: a initialized PEErrorHandler

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

Create a default PEErrorHandler based on the project, report_type.

Parameters:

  • experiment_handle (ExperimentHandle) – handle to the current experiment

  • project (Project) – currently under analysis

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

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

  • timeout_duration (Optional[str]) – set timeout

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

Return type:

PEErrorHandler

Retruns: a initialized 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

Return type:

Any

Returns: wrapped command

class varats.experiment.experiment_util.WithUnlimitedStackSize(*extensions, **kwargs)[source]

Bases: Extension

Sets the stack size of the wrapped command to unlimited (16GB).

class varats.experiment.experiment_util.ExperimentHandle(experiment)[source]

Bases: object

Handle to an experiment that provides helper interfaces for analysis steps to utilize experiment specific data.

get_file_name(report_shorthand, project_name, binary_name, project_revision, project_uuid, extension_type, config_id=None)[source]

Generates a filename for a report file that is generated by the experiment.

Parameters:

  • report_shorthand (str) – unique shorthand for the report

  • project_name (str) – name of the project for which the report was generated

  • binary_name (str) – name of the binary for which the report was generated

  • project_revision (ShortCommitHash) – revision (commit hash)of the analyzed project

  • project_uuid (str) – benchbuild uuid for the experiment run

  • extension_type (FileStatusExtension) – to specify the status of the generated report

Return type:

ReportFilename

Returns:

name for the report file that can later be uniquly identified

report_spec()[source]

Experiment report specification.

Return type:

ReportSpecification

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

Bases: Experiment

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

REPORT_SPEC: ReportSpecification
SHORTHAND: str
classmethod shorthand()[source]

Experiment shorthand.

Return type:

str

classmethod report_spec()[source]

Experiment report specification.

Return type:

ReportSpecification

classmethod file_belongs_to_experiment(file_name)[source]

Checks if the file belongs to this experiment.

Parameters:

file_name (str) – name of the file to check

Return type:

bool

Returns:

True, if the file belongs to this experiment type

get_handle()[source]
Return type:

ExperimentHandle

abstractmethod actions_for_project(project)[source]

Get the actions a project wants to run.

Return type:

MutableSequence[Step]

classmethod 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[Revision]

Returns:

list of sampled versions

class varats.experiment.experiment_util.ZippedReportFolder(result_report_path)[source]

Bases: TemporaryDirectory[str]

Context manager for creating a folder report, i.e., a report file which is actually a folder containing multiple files and other folders.

Example usage: An experiment step can, with this context manager, simply create a folder into which all kinds of data is dropped into. After the completion of the step (leaving the context manager), all files dropped into the folder will be compressed and stored as a single report.

exception varats.experiment.experiment_util.WrongStepCall[source]

Bases: Exception

Throw if the common step method was called.

class varats.experiment.experiment_util.OutputFolderStep(project)[source]

Bases: ProjectStep

Special step class that needs an output folder to write to.

abstractmethod call_with_output_folder(tmp_dir)[source]

Actual call implementation that gets a path to tmp_folder.

Return type:

StepResult

class varats.experiment.experiment_util.ZippedExperimentSteps(output_filepath, actions)[source]

Bases: MultiStep[ZippedStepTy]

Runs multiple actions, providing them a shared tmp folder that afterwards is zipped into an archive.

NAME: ClassVar[str] = 'ZippedSteps'
DESCRIPTION: ClassVar[str] = 'Run multiple actions with a shared tmp folder'
varats.experiment.experiment_util.create_new_success_result_filepath(exp_handle, report_type, project, binary, config_id=None)[source]

Create a result filepath for a successfull report of the executed experiment/project combination.

Parameters:

  • exp_handle (ExperimentHandle) – handle to the current experiment

  • report_type (Type[BaseReport]) – type of the report

  • project (VProject) – current project

  • binary (ProjectBinaryWrapper) – current binary

  • config_id (Optional[int]) – optional id to specify the used configuration

Return type:

ReportFilepath

Returns: formatted success filepath

varats.experiment.experiment_util.create_new_failed_result_filepath(exp_handle, report_type, project, binary, config_id=None)[source]

Create a result filepath for a failed report of the executed experiment/project combination.

Parameters:

  • exp_handle (ExperimentHandle) – handle to the current experiment

  • report_type (Type[BaseReport]) – type of the report

  • project (VProject) – current project

  • binary (ProjectBinaryWrapper) – current binary

  • config_id (Optional[int]) – optional id to specify the used configuration

Return type:

ReportFilepath

Returns: formatted fail filepath

varats.experiment.experiment_util.get_config_patch_steps(project)[source]

Get a list of actions that apply all configuration patches to the project.

Parameters:

project (VProject) – the project to be configured

Return type:

MutableSequence[Step]

Returns:

the actions that configure the project

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 its name.

Return type:

Type[Project]

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

Get all loaded vara projects.

Return type:

Generator[Type[Project], None, None]

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

FetchableSource

varats.project.project_util.get_local_project_repo(project_name, git_name=None)[source]
Return type:

RepositoryHandle

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

Get the all git repositories for a given benchbuild project.

Parameters:

project_name (str) – name of the given benchbuild project

Return type:

Dict[str, RepositoryHandle]

Returns:

dict with the repository handles for the project’s git sources

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.create_project_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[[CommitRepoPair], Commit]

Returns:

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

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.num_project_commits(project_name, revision)[source]

Calculate the number of commits of a project including submodules.

Parameters:

  • project_name (str) – name of the project to calculate commits for

  • revision (FullCommitHash) – revision to calculate commits at

Return type:

int

Returns:

the number of commits in the project

varats.project.project_util.num_project_authors(project_name, revision)[source]

Calculate the number of authors of a project including submodules.

Parameters:

  • project_name (str) – name of the project to calculate authors for

  • revision (FullCommitHash) – revision to authors commits at

Return type:

int

Returns:

the number of authors in the project

varats.project.project_util.calc_project_loc(project_name, revision)[source]

Calculate the LOC for a project including submodules at the given revision.

Parameters:

  • project_name (str) – name of the project to calculate LOC for

  • revision (FullCommitHash) – revision to calculate LOC at

Return type:

int

Returns:

the LOC in the project

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(*values)[source]

Bases: Enum

Enum for different binary types.

value: int
EXECUTABLE = 1
SHARED_LIBRARY = 2
STATIC_LIBRARY = 3
property is_library: bool
class varats.project.project_util.ProjectBinaryWrapper(binary_name, path_to_binary, binary_type, entry_point=None, valid_exit_codes=None)[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.

property path: Path

Path to the binary location.

property type: BinaryType

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

property entry_point: Path | None

Entry point to an executable “thing” that executes the wrapped binary, if possible.

property valid_exit_codes: List[int]

Specifies which exit codes indicate a successful execution of the binary.

exception varats.project.project_util.BinaryNotFound[source]

Bases: CompilationError

Exception raised if a 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

class varats.project.project_util.RevisionBinaryMap(repo)[source]

Bases: Container[str]

A special map that specifies for which revision ranges a binaries is valid.

specify_binary(location, binary_type, **kwargs)[source]

Add a binary to the map.

Parameters:

  • location (str) – where the binary can be found, relative to the project-source root

  • binary_type (BinaryType) – the type of binary that is produced

  • override_binary_name – overrides the used binary name

  • override_entry_point – overrides the executable entry point

  • only_valid_in – additionally specifies a validity range that specifies in which revision range this binary is produced

Return type:

RevisionBinaryMap

Returns:

self for builder-style usage

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

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.

varats.utils.filesystem_util.lock_file(lock_path, lock_mode=2)[source]
Return type:

Generator[None, None, None]

Module: cmake_util

CMake utilities.

varats.tools.research_tools.cmake_util.is_cmake_var_set(var_name)[source]

Check if a specific cmake variable is set to ON.

Parameters:

var_name (str) – of the cmake variable

Return type:

bool

Returns: true, if the cmake variable is set

varats.tools.research_tools.cmake_util.set_cmake_var(var_name, value, post_out=<function <lambda>>)[source]

Sets a cmake variable in the current cmake config.

Parameters:

  • var_name (str) – of the cmake variable

  • value (str) – to set

  • post_out (Callable[[str], None]) – callback to write console output to

Return type:

None

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

Return type:

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

Returns: the research tool type corresponding to name

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]