objgraph

Tools for drawing Python object reference graphs with graphviz.

You can find documentation online at http://mg.pov.lt/objgraph/

Copyright (c) 2008-2014 Marius Gedminas <marius@pov.lt> Copyright (c) 2010 Stefano Rivera <stefano@rivera.za.net>

Released under the MIT licence.

Statistics

objgraph.count(typename[, objects])

Count objects tracked by the garbage collector with a given class name.

Example:

>>> count('dict')
42
>>> count('MyClass', get_leaking_objects())
3
>>> count('mymodule.MyClass')
2

Note that the GC does not track simple objects like int or str.

Changed in version 1.7: New parameter: objects.

Changed in version 1.8: Accepts fully-qualified type names (i.e. ‘package.module.ClassName’) as well as short type names (i.e. ‘ClassName’).

objgraph.typestats([objects])

Count the number of instances for each type tracked by the GC.

Note that the GC does not track simple objects like int or str.

Note that classes with the same name but defined in different modules will be lumped together if shortnames is True.

Example:

>>> typestats()
{'list': 12041, 'tuple': 10245, ...}
>>> typestats(get_leaking_objects())
{'MemoryError': 1, 'tuple': 2795, 'RuntimeError': 1, 'list': 47, ...}

New in version 1.1.

Changed in version 1.7: New parameter: objects.

Changed in version 1.8: New parameter: shortnames.

objgraph.most_common_types([limit=10, objects, shortnames=True])

Count the names of types with the most instances.

Returns a list of (type_name, count), sorted most-frequent-first.

Limits the return value to at most limit items. You may set limit to None to avoid that.

The caveats documented in typestats() apply.

Example:

>>> most_common_types(limit=2)
[('list', 12041), ('tuple', 10245)]

New in version 1.4.

Changed in version 1.7: New parameter: objects.

Changed in version 1.8: New parameter: shortnames.

objgraph.show_most_common_types([limit=10, objects, shortnames=True])

Print the table of types of most common instances.

The caveats documented in typestats() apply.

Example:

>>> show_most_common_types(limit=5)
tuple                      8959
function                   2442
wrapper_descriptor         1048
dict                       953
builtin_function_or_method 800

New in version 1.1.

Changed in version 1.7: New parameter: objects.

Changed in version 1.8: New parameter: shortnames.

objgraph.show_growth([limit=10, peak_stats={}, shortnames=True])

Show the increase in peak object counts since last call.

Limits the output to limit largest deltas. You may set limit to None to see all of them.

Uses and updates peak_stats, a dictionary from type names to previously seen peak object counts. Usually you don’t need to pay attention to this argument.

The caveats documented in typestats() apply.

Example:

>>> objgraph.show_growth()
wrapper_descriptor       970       +14
tuple                  12282       +10
dict                    1922        +7
...

New in version 1.5.

Changed in version 1.8: New parameter: shortnames.

Locating and Filtering Objects

objgraph.get_leaking_objects([objects])

Return objects that do not have any referents.

These could indicate reference-counting bugs in C code. Or they could be legitimate.

Note that the GC does not track simple objects like int or str.

New in version 1.7.

objgraph.by_type(typename[, objects])

Return objects tracked by the garbage collector with a given class name.

Example:

>>> by_type('MyClass')
[<mymodule.MyClass object at 0x...>]

Note that the GC does not track simple objects like int or str.

Changed in version 1.7: New parameter: objects.

Changed in version 1.8: Accepts fully-qualified type names (i.e. ‘package.module.ClassName’) as well as short type names (i.e. ‘ClassName’).

objgraph.at(addr)

Return an object at a given memory address.

The reverse of id(obj):

>>> at(id(obj)) is obj
True

Note that this function does not work on objects that are not tracked by the GC (e.g. ints or strings).

objgraph.is_proper_module(obj)

Returns True if obj can be treated like a garbage collector root.

That is, if obj is a module that is in sys.modules.

>>> import imp
>>> is_proper_module([])
False
>>> is_proper_module(imp)
True
>>> is_proper_module(imp.new_module('foo'))
False

New in version 1.8.

Traversing and Displaying Object Graphs

objgraph.find_ref_chain(obj, predicate[, max_depth=20, extra_ignore=()])

Find a shortest chain of references leading from obj.

The end of the chain will be some object that matches your predicate.

predicate is a function taking one argument and returning a boolean.

max_depth limits the search depth.

extra_ignore can be a list of object IDs to exclude those objects from your search.

Example:

>>> find_chain(obj, lambda x: isinstance(x, MyClass))
[obj, ..., <MyClass object at ...>]

Returns [obj] if such a chain could not be found.

New in version 1.7.

objgraph.find_backref_chain(obj, predicate[, max_depth=20, extra_ignore=()])

Find a shortest chain of references leading to obj.

The start of the chain will be some object that matches your predicate.

predicate is a function taking one argument and returning a boolean.

max_depth limits the search depth.

extra_ignore can be a list of object IDs to exclude those objects from your search.

Example:

>>> find_backref_chain(obj, is_proper_module)
[<module ...>, ..., obj]

Returns [obj] if such a chain could not be found.

Changed in version 1.5: Returns obj instead of None when a chain could not be found.

objgraph.show_chain(chain[, ..., highlight=None, filename=None, extra_info=None, refcounts=False, shortnames=True])

Show a chain (or several chains) of object references.

Useful in combination with find_ref_chain() or find_backref_chain(), e.g.

>>> show_chain(find_backref_chain(obj, is_proper_module))

You can specify if you want that chain traced backwards or forwards by passing a backrefs keyword argument, e.g.

>>> show_chain(find_ref_chain(obj, is_proper_module),
...            backrefs=False)

Ideally this shouldn’t matter, but for some objects gc.get_referrers() and gc.get_referents() are not perfectly symmetrical.

You can specify highlight, extra_info, refcounts, shortnames or filename arguments like for show_backrefs() or show_refs().

New in version 1.5.

Changed in version 1.7: New parameter: backrefs.

objgraph.show_backrefs(objs[, max_depth=3, extra_ignore=(), filter=None, too_many=10, highlight=None, filename=None, extra_info=None, refcounts=False, shortnames=True])

Generate an object reference graph ending at objs.

The graph will show you what objects refer to objs, directly and indirectly.

objs can be a single object, or it can be a list of objects. If unsure, wrap the single object in a new list.

filename if specified, can be the name of a .dot or a image file, whose extension indicates the desired output format; note that output to a specific format is entirely handled by GraphViz: if the desired format is not supported, you just get the .dot file. If filename is not specified, show_backrefs will try to produce a .dot file and spawn a viewer (xdot). If xdot is not available, show_backrefs will convert the .dot file to a .png and print its name.

Use max_depth and too_many to limit the depth and breadth of the graph.

Use filter (a predicate) and extra_ignore (a list of object IDs) to remove undesired objects from the graph.

Use highlight (a predicate) to highlight certain graph nodes in blue.

Use extra_info (a function taking one argument and returning a string) to report extra information for objects.

Specify refcounts=True if you want to see reference counts. These will mostly match the number of arrows pointing to an object, but can be different for various reasons.

Specify shortnames=False if you want to see fully-qualified type names (‘package.module.ClassName’). By default you get to see only the class name part.

Examples:

>>> show_backrefs(obj)
>>> show_backrefs([obj1, obj2])
>>> show_backrefs(obj, max_depth=5)
>>> show_backrefs(obj, filter=lambda x: not inspect.isclass(x))
>>> show_backrefs(obj, highlight=inspect.isclass)
>>> show_backrefs(obj, extra_ignore=[id(locals())])

Changed in version 1.3: New parameters: filename, extra_info.

Changed in version 1.5: New parameter: refcounts.

Changed in version 1.8: New parameter: shortnames.

objgraph.show_refs(objs[, max_depth=3, extra_ignore=(), filter=None, too_many=10, highlight=None, filename=None, extra_info=None, refcounts=False, shortnames=True])

Generate an object reference graph starting at objs.

The graph will show you what objects are reachable from objs, directly and indirectly.

objs can be a single object, or it can be a list of objects. If unsure, wrap the single object in a new list.

filename if specified, can be the name of a .dot or a image file, whose extension indicates the desired output format; note that output to a specific format is entirely handled by GraphViz: if the desired format is not supported, you just get the .dot file. If filename is not specified, show_refs will try to produce a .dot file and spawn a viewer (xdot). If xdot is not available, show_refs will convert the .dot file to a .png and print its name.

Use max_depth and too_many to limit the depth and breadth of the graph.

Use filter (a predicate) and extra_ignore (a list of object IDs) to remove undesired objects from the graph.

Use highlight (a predicate) to highlight certain graph nodes in blue.

Use extra_info (a function returning a string) to report extra information for objects.

Specify refcounts=True if you want to see reference counts.

Examples:

>>> show_refs(obj)
>>> show_refs([obj1, obj2])
>>> show_refs(obj, max_depth=5)
>>> show_refs(obj, filter=lambda x: not inspect.isclass(x))
>>> show_refs(obj, highlight=inspect.isclass)
>>> show_refs(obj, extra_ignore=[id(locals())])

New in version 1.1.

Changed in version 1.3: New parameters: filename, extra_info.

Changed in version 1.5: Follows references from module objects instead of stopping. New parameter: refcounts.

Changed in version 1.8: New parameter: shortnames.

Table Of Contents

Previous topic

Python Object Graphs

Next topic

Too many references