pympler.garbagegraph

Garbage occurs if objects refer too each other in a circular fashion. Such reference cycles cannot be freed automatically and must be collected by the garbage collector. While it is sometimes hard to avoid creating reference cycles, preventing such cycles saves garbage collection time and limits the lifetime of objects. Moreover, some objects cannot be collected by the garbage collector.

Reference cycles can be visualized with the help of graphviz.

Classes

class pympler.garbagegraph.GarbageGraph(reduce=False, collectable=True)

The GarbageGraph is a ReferenceGraph that illustrates the objects building reference cycles. The garbage collector is switched to debug mode (all identified garbage is stored in gc.garbage) and the garbage collector is invoked. The collected objects are then illustrated in a directed graph.

Large graphs can be reduced to the actual cycles by passing reduce=True to the constructor.

It is recommended to disable the garbage collector when using the GarbageGraph.

>>> from pympler.garbagegraph import GarbageGraph, start_debug_garbage
>>> start_debug_garbage()
>>> l = []
>>> l.append(l)
>>> del l
>>> gb = GarbageGraph()
>>> gb.render('garbage.eps')
True

__init__(reduce=False, collectable=True)

Initialize the GarbageGraph with the objects identified by the garbage collector. If collectable is true, every reference cycle is recorded. Otherwise only uncollectable objects are reported.

render(filename, cmd='dot', format='ps', unflatten=False)

Render the graph to filename using graphviz. The graphviz invocation command may be overridden by specifying cmd. The format may be any specifier recognized by the graph renderer (‘-Txxx’ command). The graph can be preprocessed by the unflatten tool if the unflatten parameter is True. If there are no objects to illustrate, the method does not invoke graphviz and returns False. If the renderer returns successfully (return code 0), True is returned.

An OSError is raised if the graphviz tool cannot be found.

split()

Split the graph into sub-graphs. Only connected objects belong to the same graph. split yields copies of the Graph object. Shallow copies are used that only replicate the meta-information, but share the same object list self.objects.

>>> from pympler.refgraph import ReferenceGraph
>>> a = 42
>>> b = 'spam'
>>> c = {a: b}
>>> t = (1,2,3)
>>> rg = ReferenceGraph([a,b,c,t])
>>> for subgraph in rg.split():
...   print (subgraph.index)
0
1

write_graph(filename)

Write raw graph data which can be post-processed using graphviz.

print_stats(stream=None)

Log annotated garbage objects to console or file.

Parameters:stream – open file, uses sys.stdout if not given

Functions

pympler.garbagegraph.start_debug_garbage()

Turn off garbage collector to analyze collectable reference cycles.

pympler.garbagegraph.end_debug_garbage()

Turn garbage collection on and disable debug output.