BlameReport

Module for BlameReport, a collection of blame interactions.

class varats.data.reports.blame_report.BlameTaintData(commit, region_id=None, function_name=None)

Bases: object

Data that is carried by a blame taint.

static create_taint_data(raw_taint_data)

Create a BlameTaintData instance from from the corresponding yaml document section.

Return type:

BlameTaintData

property region_id: int | None

property function_name: str | None

property commit: CommitRepoPair

class varats.data.reports.blame_report.BlameInstInteractions(base_taint, interacting_taints, amount)

Bases: object

An interaction between a base region/taint, attached to an instruction, and other regions/taints.

For the blame analysis, these taints stem from data flows into the instruction.

static create_blame_inst_interactions(raw_inst_entry)

Creates a BlameInstInteractions entry from the corresponding yaml document section.

Return type:

BlameInstInteractions

property base_taint: BlameTaintData

Base taint of the analyzed instruction.

property interacting_taints: List[BlameTaintData]

List of taints that interact with the base.

property amount: int

Number of same interactions found in this function.

class varats.data.reports.blame_report.BlameResultFunctionEntry(name, demangled_name, file_name, blame_insts, num_instructions, callees, commits)

Bases: object

Collection of all interactions for a specific function.

static create_blame_result_function_entry(name, raw_function_entry)

Creates a BlameResultFunctionEntry from the corresponding yaml document section.

Return type:

BlameResultFunctionEntry

property name: str

Name of the function.

The name is mangled for C++ code, either with the itanium or windows mangling schema.

property demangled_name: str

Demangled name of the function.

property file_name: str | None

Name of file containing the function if available.

property num_instructions: int

Number of instructions in this function.

property interactions: List[BlameInstInteractions]

List of found instruction blame-interactions.

property callees: List[str]

List of functions called by this function.

property commits: List[CommitRepoPair]

List of commits that modified this function.

class varats.data.reports.blame_report.BlameReportMetaData(num_functions, num_instructions, num_phasar_empty_tracked_vars, num_phasar_total_tracked_vars, bta_wall_time)

Bases: object

Provides extra meta-data about llvm::Module, which was analyzed to generate this BlameReport.

property num_functions: int

Number of functions in the analyzed llvm::Module.

property num_instructions: int

Number of instructions processed in the analyzed llvm::Module.

property num_empty_tracked_vars: int | None

Number of variables tracked by phasar that had an empty taint set.

property num_total_tracked_vars: int | None

Number of variables tracked by phasar.

property bta_wall_time: float | None

Wall time of the blame taint analysis.

static create_blame_report_meta_data(raw_document)

Creates BlameReportMetaData from the corresponding yaml document.

Return type:

BlameReportMetaData

class varats.data.reports.blame_report.BlameTaintScope(*values)

Bases: Enum

The scope that was used for computing commit interactions.

REGION = 0

COMMIT_IN_FUNCTION = 1

COMMIT = 2

static from_string(value)

Return type:

BlameTaintScope

class varats.data.reports.blame_report.BlameReport(path)

Bases: BaseReport

Full blame report containing all blame interactions.

get_blame_result_function_entry(mangled_function_name)

Get the result entry for a specific function.

Parameters:

mangled_function_name (str) – mangled name of the function to look up

Return type:

Optional[BlameResultFunctionEntry]

property blame_taint_scope: BlameTaintScope

property function_entries: ValuesView[BlameResultFunctionEntry]

Iterate over all function entries.

property head_commit: ShortCommitHash

The current HEAD commit under which this CommitReport was created.

property meta_data: BlameReportMetaData

Access the meta data that was gathered with the BlameReport.

FILE_TYPE: str = 'yaml'

SHORTHAND: str = 'BR'

class varats.data.reports.blame_report.BlameReportDiff(base_report, prev_report)

Bases: object

Diff class that contains all interactions that changed between two report revisions.

property blame_taint_scope: BlameTaintScope

property base_head_commit: ShortCommitHash

property prev_head_commit: ShortCommitHash

property function_entries: ValuesView[BlameResultFunctionEntry]

Iterate over all function entries in the diff.

get_blame_result_function_entry(mangled_function_name)

Get the result entry for a specific function in the diff.

Parameters:

mangled_function_name (str) – mangled name of the function to look up

Return type:

BlameResultFunctionEntry

has_function(mangled_function_name)

Return type:

bool

varats.data.reports.blame_report.count_interactions(report)

Counts the number of interactions.

Parameters:

report (Union[BlameReport, BlameReportDiff]) – the blame report or diff

Return type:

int

Returns:

the number of interactions in this report or diff

varats.data.reports.blame_report.count_interacting_commits(report)

Counts the number of unique interacting commits.

Parameters:

report (Union[BlameReport, BlameReportDiff]) – the blame report or diff

Return type:

int

Returns:

the number unique interacting commits in this report or diff

varats.data.reports.blame_report.count_interacting_authors(report, commit_lookup)

Counts the number of unique interacting authors.

Parameters:

• report (Union[BlameReport, BlameReportDiff]) – the blame report or diff

• commit_lookup (Callable[[CommitRepoPair], Commit]) – function to look up commits

Return type:

int

Returns:

the number unique interacting authors in this report or diff

varats.data.reports.blame_report.generate_degree_tuples(report)

Generates a list of tuples (degree, amount) where degree is the interaction degree of a blame interaction, e.g., the number of incoming interactions, and amount is the number of times an interaction with this degree was found in the report.

Parameters:

report (Union[BlameReport, BlameReportDiff]) – the blame report

Return type:

List[Tuple[int, int]]

Returns:

list of tuples (degree, amount)

varats.data.reports.blame_report.gen_base_to_inter_commit_repo_pair_mapping(report)

Maps the base CommitRepoPair of a blame interaction to each distinct interacting CommitRepoPair, which maps to the amount of the interaction.

Parameters:

report (Union[BlameReport, BlameReportDiff]) – blame report

Return type:

Dict[BlameTaintData, Dict[BlameTaintData, int]]

Returns:

A mapping from base CommitRepoPairs to a mapping of the corresponding interacting CommitRepoPairs to their amount.

varats.data.reports.blame_report.generate_lib_dependent_degrees(report)

Parameters:

report (Union[BlameReport, BlameReportDiff]) – blame report

Return type:

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

Returns:

Map of tuples (degree, amount) categorised by their corresponding library name to their corresponding base library name.

varats.data.reports.blame_report.generate_author_degree_tuples(report, commit_lookup)

Generates a list of tuples (author_degree, amount) where author_degree is the number of unique authors for all blame interaction, e.g., the number of unique authors of incoming interactions, and amount is the number of times an interaction with this degree was found in the report.

Parameters:

• report (Union[BlameReport, BlameReportDiff]) – the blame report

• commit_lookup (Callable[[CommitRepoPair], Commit]) – function to look up commits

Return type:

List[Tuple[int, int]]

Returns:

list of tuples (author_degree, amount)

varats.data.reports.blame_report.generate_time_delta_distribution_tuples(report, commit_lookup, bucket_size, aggregate_function)

Generates a list of tuples that represent the distribution of time delta interactions. The first value in the tuple represents the degree of the time delta, bucketed according to bucket_size. The second value is the time delta, aggregated over all interacting commits by the passed aggregate_function.

Parameters:

• report (Union[BlameReport, BlameReportDiff]) – to analyze

• commit_lookup (Callable[[CommitRepoPair], Commit]) – function to look up commits

• bucket_size (int) – size of a time bucket in days

• aggregate_function (Callable[[Sequence[Union[int, float]]], Union[int, float]]) – to aggregate the delta values of all interacting commits

Return type:

List[Tuple[int, int]]

Returns:

list of (degree, amount) tuples

varats.data.reports.blame_report.generate_avg_time_distribution_tuples(report, commit_lookup, bucket_size)

Generates a list of tuples that represent the distribution of average time delta interactions. The first value in the tuple represents the degree of the time delta, bucketed according to bucket_size. The second value is the time delta, averaged over all interacting commits.

Parameters:

• report (Union[BlameReport, BlameReportDiff]) – to analyze

• commit_lookup (Callable[[CommitRepoPair], Commit]) – function to look up commits

• bucket_size (int) – size of a time bucket in days

Return type:

List[Tuple[int, int]]

Returns:

list of (degree, avg_time) tuples

varats.data.reports.blame_report.generate_max_time_distribution_tuples(report, commit_lookup, bucket_size)

Generates a list of tuples that represent the distribution of maximal time delta interactions. The first value in the tuple represents the degree of the time delta, bucketed according to bucket_size. The second value is the max time delta, i.e., the maximal time distance between the base commit and one of the all interacting commits.

Parameters:

• report (Union[BlameReport, BlameReportDiff]) – to analyze

• commit_lookup (Callable[[CommitRepoPair], Commit]) – function to look up commits

• bucket_size (int) – size of a time bucket in days

Return type:

List[Tuple[int, int]]

Returns:

list of (degree, max_time) tuples

varats.data.reports.blame_report.generate_in_head_interactions(report)

Generate a list of interactions where the base_hash of the interaction is the same as the HEAD of the report.

Parameters:

report (BlameReport) – BlameReport to get the interactions from

Return type:

List[BlameInstInteractions]

varats.data.reports.blame_report.generate_out_head_interactions(report)

Generate a list of interactions where one of the interacting hashes is the same as the HEAD of the report.

Parameters:

report (BlameReport) – BlameReport to get the interactions from

Return type:

List[BlameInstInteractions]

varats.data.reports.blame_report.get_interacting_commits_for_commit(report, commit)

Get all commits a given commits interacts with separated by incoming and outgoing interactions.

Parameters:

• report (BlameReport) – BlameReport to get the interactions from

• commit (CommitRepoPair) – commit to get the interacting commits for

Return type:

Tuple[Set[CommitRepoPair], Set[CommitRepoPair]]

Returns:

two sets for the interacting commits seperated by incoming and outgoing interactions