firecrown.fctools.tracer

Method tracing facility.

This module provides a facility to capture and record tracing data, using the sys.settrace method. It causes a tab-separated value file to be written, with one record (line) for each captured event.

The columns in the file are:

entry:

a sequential entry number, for each event

event:

the event type (call, return, exception)

level:

the call nesting level

function:

the function name

value:

for a ‘call’ entry, the names of the arguments; for a ‘return’ entry, the return value

extra:

for a ‘call’ entry, the type self, if that is the first argument; for a ‘return’ entry, the type of the return value

N.B.: This tracer should be used only for debugging and development purposes.

It interferes with the pytest test coverage measurement process.

Attributes

app

Classes

TracerState

Encapsulates tracing state to avoid global variables.

Functions

settrace([filename])	Start the tracer, with log being written to a new file with the given name.
untrace(tracer)	Turn off tracing, and close the specified trace file.
main([target, output, module])	Trace execution of a Python script or module.

Module Contents

class firecrown.fctools.tracer.TracerState(filename='trace.tsv')

Encapsulates tracing state to avoid global variables.

Parameters:

filename (str)

tracefile

level = 0

entry = 0

trace_call(fr, ev, arg)

Callback used by settrace.

Parameters:

• fr – the frame object

• ev – the event type

• arg – the argument

close()

Close the trace file.

Return type:

None

firecrown.fctools.tracer.settrace(filename='trace.tsv')

Start the tracer, with log being written to a new file with the given name.

Parameters:

filename (str) – the name of the new file to be created

Returns:

TracerState instance managing the trace

Return type:

TracerState

firecrown.fctools.tracer.untrace(tracer)

Turn off tracing, and close the specified trace file.

Parameters:

tracer (TracerState) – TracerState instance, as returned by settrace.

Return type:

None

Note

Coverage tracking doesn’t work for this function due to sys.settrace() interaction between coverage.py and the tracer. Tests verify functionality without coverage enabled.

Parameters:

tracer (TracerState) – TracerState instance, as returned by settrace.

Return type:

None

firecrown.fctools.tracer.app

firecrown.fctools.tracer.main(target=typer.Argument(..., help='Python script file or module name to trace'), output=typer.Option('trace.tsv', '--output', '-o', help='Output trace file'), module=typer.Option(False, '--module', '-m', help='Run target as a module (like python -m module)'))

Trace execution of a Python script or module.

This tool enables method tracing for Python code, recording function calls, returns, and exceptions to a TSV file for analysis.

Parameters:

• target (str)

• output (str)

• module (bool)