Tracing

trace(c)

Execute the tracer upon a callable marked with this decorator. Serialises the accumulated trace data after the callable has finished to the location given by the config file. Uncaught exceptions are logged next to these pickled DataFrames. Supports performance benchmarking when specified in the config file.

The implementation makes sure to preserve all arguments to the decorated callable, so that features like py.test's monkeypatching, fixtures etc. are all still supported.

Parameters:

Name	Type	Description	Default
c	Callable[..., RetType]	Any given callable, with any amount of arguments, and any sort of return	required

TracerBase

Bases: abc.ABC

Base class for all Tracers. If more tracers need to be implemented, this class should be inherited from and the abstract method is to be implemented

__init__(proj_path, stdlib_path, venv_path)

Construct instance with provided paths.

Parameters:

Name	Type	Description	Default
proj_path	pathlib.Path	Path to project's directory that shall be traced	required
stdlib_path	pathlib.Path	Path to standard library's directory of the Python binary used to run the project's tests	required
venv_path	pathlib.Path	Path to project's virtual environment's directory used to run the project's tests	required

start_trace()

Starts the trace by calling sys.settrace and backing-up the previous one. All Python code run after this will now be traced.

Parameters:

Name	Type	Description	Default
self	TracerBase	An instance of a deriving class	required

active_trace()

Wrapper around the start_trace and stop_trace methods for with statements. Python code run after this will no longer be traced.

Parameters:

Name	Type	Description	Default
self	TracerBase	An instance of a deriving class	required

stop_trace()

Stops the trace and reinstates the previously set trace function. Also deduplicates the accumulated trace data.

Parameters:

Name	Type	Description	Default
self	TracerBase	An instance of a deriving class	required

NoOperationTracer

Bases: TracerBase

Tracer that does nothing except be invoked whenever a tracing-related event is emitted. Used to provide benchmarking, i.e. to measure the overhead by the "real" Tracer

Tracer

Bases: TracerBase

Tracer that is invoked everytime a tracing-related event is emitted. Traces and stores information about each instance in a DataFrame using BatchTraceUpdate

__init__(proj_path, stdlib_path, venv_path, apply_opts=True)

Construct instance with provided paths. Additionally accepts an extra argument that indicates whether optimisations should be enabled

Parameters:

Name	Type	Description	Default
proj_path	pathlib.Path	Path to project's directory that shall be traced	required
stdlib_path	pathlib.Path	Path to standard library's directory of the Python binary used to run the project's tests	required
venv_path	pathlib.Path	Path to project's virtual environment's directory used to run the project's tests	required
apply_opts	bool	When set to True, tries to optimise loop execution by turning off tracing if enough iterations have passed since any types have changed	True

TraceUpdate dataclass

A simple dataclass holding the contents of a singular update

Parameters:

Name	Type	Description	Default
file_name	pathlib.Path	The file name in which the variables are declared	required
class_module	str | None	Module of the class the variable is in	required
class_name	str | None	Name of the class the variable is in	required
function_name	str | None	The function which declares the variable	required
line_number	int	The line number	required
category	TraceDataCategory	The data category of the row	required
names2types	dict[str, tuple[str | None, str]]	A dictionary containing the variable name, the type's module and the type's name	required

BatchTraceUpdate dataclass

A builder-pattern style interface for each relevant category, allowing updates to be chained as each event requires. After all updates have been handled, a DataFrame can be produced that is to added to the otherwise accumulated trace data.

The constructor accepts values that are used by default to create instances of TraceUpdate, unless overwritten by an argument in one of the builder methods.

TRACE_MAP is defined as dict[str, tuple[str | None, str]], which is a map of identifiers to (module name, type name). The module_name is None if the type is builtin, such as int, str, float etc.

Parameters:

Name	Type	Description	Default
file_name	pathlib.Path	The file name in which the variables are declared	required
class_module	str | None	Module of the class the variable is in	required
class_name	str | None	Name of the class the variable is in	required
function_name	str	The function which declares the variable	required
line_number	int	The line number	required

local_variables(line_number, names2types)

Create an update consisting of local variables

Parameters:

Name	Type	Description	Default
line_number	int	Because the line number that a variable is written on is not the same as the one it is put on the stack, this must be manually specified	required
names2types	TRACE_MAP	Names of local variables mapped to the module and type names of their types	required

Returns:

Type	Description
BatchTraceUpdate	A reference to newly updated batch

global_variables(names2types)

Create an update consisting of global variables. Because they are stateful, their line number is always 0, and can only be differentiated by their name and the file they occur in

Parameters:

Name	Type	Description	Default
names2types	TRACE_MAP	Names of global variables mapped to the module and type names of their types	required

Returns:

Type	Description
BatchTraceUpdate	A reference to newly updated batch

returns(names2types)

Create an update consisting of return types from functions. Their line number is always 0, so that unifiers can group them together appropriately later.

Parameters:

Name	Type	Description	Default
names2types	TRACE_MAP	Names of functions mapped to the module and type name of their return types	required

Returns:

Type	Description
BatchTraceUpdate	A reference to newly updated batch

parameters(names2types)

Create an update consisting of parameters for a callable.

Parameters:

Name	Type	Description	Default
names2types	TRACE_MAP	Names of the parameters to a callable mapped to the module and type names of their types	required

Returns:

Type	Description
BatchTraceUpdate	A reference to newly updated batch

members(names2types)

Create an update consisting of attributes of a class. Because they are stateful, their line number is always 0, and can only be differentiated by the file they occur in, their identifier and the class they occur in

Parameters:

Name	Type	Description	Default
names2types	TRACE_MAP	Names of the members of a class mapped to the module and type names of their types	required

Returns:

Type	Description
BatchTraceUpdate	A reference to newly updated batch

to_frame()

Consume this batch of updates in order to produce a DataFrame.

Parameters:

Name	Type	Description	Default
self	BatchTraceUpdate	Nothing else :)	required

Returns:

Type	Description
pd.DataFrame	A DataFrame encompassing the entire batch