calltree

Support to build a simple call-tree for Python code.

This uses Python’s built-in introspection to determine which functions/methods a given function/method appears to invoke. The process is performed recursively in order to form a tree of possible calls. The algorithm is deliberately limited.

  • Only reachability is of interest, no attempt to represent any levels of recursion is implemented. THIS IS NOT REALLY TRUE!
  • Conditional code is not handled at all!

Module Members

FunctionInfoCache
RunTracer
Step
TracedFunction

Classes

class calltree.FunctionInfoCache

An in-memory cache used to store information about ‘interesting’ functions.

getFuncInfo(obj)

Get information about a an object, if it is a function.

If the object is not a function None is returned. If the function is cached then the information is retrieved from the cache. Otherwise a new TracedFunction is created and added to the cache.

Return Value

If the obj argument is not a function then None. Otherwise a TracedFunction instance.

Arguments

obj
The object to inspect.
getFuncInfoByName(module, name)

Get information about a function with a given name.

Like getFuncInfo(), this will use cached information if possible.

Return Value

If the name does not identify a function then None. Otherwise a TracedFunction instance.

Arguments

module
This should typically be a Python module instance, but it can be anything that ‘looks’ like a module.
name
The name of the function.
getFunctionFromCode(func_code)

Get function info for a code object.

getMethodInfoByName(klass, name)

Get information about a method with a given name.

This is analagous to getFuncInfoByName(), but for methods in a class.

class calltree.TracedFunction

Mapping of a test function (direct or indirect) to useful information.

calltree.func

The function in question.

calltree.startLine

The number of the line where the function’s definition begins.

calltree.inlined

True if the function has been decorated marked with cs_inline.

calltree.invocations

Ordered points of interests that are function/method invocations.

calltree.steps

Ordered points of interest that are test steps.

calltree.getStep(lNum)

Get the step above the code for a given line number.

Return Value

If the line of code is preceded by a step comment then the Step instnce. Otherwise None is returned.

Arguments

lNum
The line number of the code.
calltree.init(func, cache)

Find all test steps and function invocations for this function.

This is not intended to be used outside this module. It exists because a TracedFunction needs to be created before the function details can be added.

calltree.walkSteps(level=0)

Generator: Walk all the steps for this function and those it invokes.

This yields tuples of level, func, (lnum, step). The lnum is the line number within the source file. The step is a Step instance. The level is the level of step nesting and is zero based.

class calltree.Step(lines)

Information about a step in a test.

This is used to store the lines that describe a test step, as extraced from a comment in a function or method.

class calltree.RunTracer(funcCache, stepCB)

Context manager that uses sys.settrace to identify steps as they occur.

This can be used when tests execute in order to provide a running commentary of the tests’s progress.

Arguments

funcCache
Should be a FunctionInfoCache or equivalent object.
stepCB
A function to be called as each step is detected. It is invoked as stepCB(level, nStr, step). The level is a number indicating how deeply nested the current step is. The nStr indicates the step’s number. It is a dotted number, which has level + 1 parts. The step is a Step instance.
trace(frame, event, arg)

Standard trace functions.

TODO:Add detail.