Installation and Documentation¶

pipinstallobjgraph ordownload it from PyPI.

Documentation lives athttps://mg.pov.lt/objgraph.

Quick start¶

Try this in a Python shell:

>>>x=[]>>>y=[x,[x],dict(x=x)]>>>importobjgraph>>>objgraph.show_refs([y],filename='sample-graph.png')Graph written to ....dot (... nodes)Image generated as sample-graph.png

(If you’ve installedxdot, omit the filename argument to get theinteractive viewer.)

You should see a graph like this:

If you prefer to handle your own file output, you can provide a file object totheoutput parameter ofshow_refs andshow_backrefs instead of afilename. The contents of this file will contain the graph source in DOT format.

Backreferences¶

Now try

>>>objgraph.show_backrefs([x],filename='sample-backref-graph.png')...Graph written to ....dot (8 nodes)Image generated as sample-backref-graph.png

and you’ll see

Memory leak example¶

The original purpose ofobjgraph was to help me find memory leaks.The idea was to pick an object in memory that shouldn’t be there and thensee what references are keeping it alive.

To get a quick overview of the objects in memory, use the imaginatively-namedshow_most_common_types():

>>>objgraph.show_most_common_types()tuple                      5224function                   1329wrapper_descriptor         967dict                       790builtin_function_or_method 658method_descriptor          340weakref                    322list                       168member_descriptor          167type                       163

But that’s looking for a small needle in a large haystack. Can we limitour haystack to objects that were created recently? Perhaps.

Let’s define a function that “leaks” memory

>>>classMyBigFatObject(object):...pass...>>>defcomputate_something(_cache={}):..._cache[42]=dict(foo=MyBigFatObject(),...bar=MyBigFatObject())...# a very explicit and easy-to-find "leak" but oh well...x=MyBigFatObject()# this one doesn't leak

We take a snapshot of all the objects counts that are alive beforewe call our function

>>>objgraph.show_growth(limit=3)tuple                  5228     +5228function               1330     +1330wrapper_descriptor      967      +967

and see what changes after we call it

>>>computate_something()>>>objgraph.show_growth()MyBigFatObject        2        +2dict                797        +1

It’s easy to seeMyBigFatObject instances that appeared and werenot freed. I can pick one of them at random and trace the reference chainback to one of the garbage collector’s roots.

For simplicity’s sake let’s assume all of the roots are modules.objgraphprovides a function,is_proper_module(), to check this. Ifyou’ve any examples where that isn’t true, I’d love to hear about them(although seeReference counting bugs).

>>>importrandom>>>objgraph.show_chain(...objgraph.find_backref_chain(...random.choice(objgraph.by_type('MyBigFatObject')),...objgraph.is_proper_module),...filename='chain.png')Graph written to ...dot (13 nodes)Image generated as chain.png

It is perhaps surprising to findlinecache at the end of that chain(apparentlydoctest monkey-patches it), but the important things –computate_something and its cache dictionary – are in there.

There are other tools, perhaps better suited for memory leak hunting:heapy,Dozer.

Reference counting bugs¶

Bugs in C-level reference counting may leave objects in memory that do nothave any other objects pointing at them. You can find these by callingget_leaking_objects(), but you’ll have to filter out legitimate GCroots from them, and there are alot of those:

>>>roots=objgraph.get_leaking_objects()>>>len(roots)4621

>>>objgraph.show_most_common_types(objects=roots)...tuple          4333dict           171list           74instancemethod 4listiterator   2MemoryError    1Sub            1RuntimeError   1Param          1Add            1

>>>objgraph.show_refs(roots[:3],refcounts=True,filename='roots.png')...Graph written to ...dot (19 nodes)Image generated as roots.png

API Documentation¶

More examples, that also double as tests¶

History¶

I’ve developed a set of functions that eventually became objgraph when Iwas hunting for memory leaks in a Python program. The whole story – withillustrated examples – is in this series of blog posts:

• Hunting memory leaks in Python

• Python object graphs

• Object graphs with graphviz

And here’s the change log

Support and Development¶

The source code can be found in this Git repository:https://github.com/mgedmin/objgraph.

To check it out, usegitclonehttps://github.com/mgedmin/objgraph.

Report bugs athttps://github.com/mgedmin/objgraph/issues.

For more information, seeHacking on objgraph.