output.Output — Base class for all output modules

Every output module subclasses pycallgraph.output.Output and implements done() to write the collected trace out in its own format.

class pycallgraph.output.Output(**kwargs)

Base class for all outputters.

done()

Called when the trace is complete and ready to be saved.

normalize_path(path)

Expand both ~ and environment variables in path.

A path may legitimately use both forms (~/graphs/$RUN.json), so each expansion is applied in turn rather than choosing between them.

sanity_check()

Basic checks for certain libraries or external applications. Raise or warn if there is a problem.

set_config(config)

Move the output options from a Config onto this output.

Only attributes the output already declares (typically its constructor defaults, set from the command line as output options) are copied. This used to copy every attribute of the config unless the output had a callable of the same name, which put the argparse parser, the selected output-type name and unrelated config state onto the output.

should_update()

Return True if the update method should be called periodically.

start()

Initialise variables after initial configuration.

update()

Called periodically during a trace, but only when should_update is set to True.

Concrete outputs

These are the outputs registered by default and selectable from the command line. See Outputs in the guide for what each one produces.

class pycallgraph.output.GraphvizOutput(**kwargs)

done()

Called when the trace is complete and ready to be saved.

generate()

Returns a string with the contents of a DOT file for Graphviz to parse.

sanity_check()

Basic checks for certain libraries or external applications. Raise or warn if there is a problem.

class pycallgraph.output.GephiOutput(**kwargs)

done()

Called when the trace is complete and ready to be saved.

static escape(value)

Quote and escape a GDF field value.

GDF is comma-separated, so any value containing a comma, a double quote or a newline must be quoted, and embedded double quotes are doubled. Values that need no quoting are returned unchanged so the common case stays readable.

generate()

Returns a string with the contents of a GDF file.

class pycallgraph.output.JSONOutput(**kwargs)

done()

Called when the trace is complete and ready to be saved.

generate()

Return the JSON document as a pretty-printed string.

schema_version = 1

Bumped whenever the document shape changes incompatibly.

class pycallgraph.output.PickleOutput(**kwargs)

done()

Called when the trace is complete and ready to be saved.

Writing your own output

Subclass pycallgraph.output.Output, implement done(), and pass an instance to pycallgraph.PyCallGraph (or to the trace decorator):

from pycallgraph import PyCallGraph
from pycallgraph.output import Output


class LengthOutput(Output):
    '''Print how many functions were traced.'''

    def __init__(self, **kwargs):
        self.output_file = None
        Output.__init__(self, **kwargs)

    def done(self):
        self.verbose('traced {0} functions'.format(
            len(self.processor.call_dict)))


with PyCallGraph(output=LengthOutput()):
    my_main_function()

Useful attributes available in done():

• self.processor – the TraceProcessor that holds the collected statistics.

• self.output_file – set it (usually from a --output-file argument) and call normalize_path() before opening it, so ~ and environment variables are expanded.

Register a class in pycallgraph.output.outputters if it should also be selectable from the command line. Implement add_arguments to declare its own options.