`objgraph`¶

Tools for drawing Python object reference graphs with graphviz.

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

Released under the MIT licence.

Statistics¶

objgraph.count(typename[, objects])¶

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

The class name can optionally be fully qualified.

Example:

>>> count('dict')
42
>>> count('mymodule.MyClass')
2

Note

The Python garbage collector does not track simple objects like int or str. See https://docs.python.org/3/library/gc.html#gc.is_tracked for more information.

Instead of looking through all objects tracked by the GC, you may specify your own collection, e.g.

>>> count('MyClass', get_leaking_objects())
3

See also: get_leaking_objects().

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, shortnames=True])¶

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.

If filter is specified, it should be a function taking one argument and returning a boolean. Objects for which filter(obj) returns False will be ignored.

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.

Changed in version 3.1.3: New parameter: filter.

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.

If filter is specified, it should be a function taking one argument and returning a boolean. Objects for which filter(obj) returns False will be ignored.

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.

Changed in version 3.1.3: New parameter: filter.

objgraph.show_most_common_types([limit=10, objects, shortnames=True, file=sys.stdout])¶

Print the table of types of most common instances.

If filter is specified, it should be a function taking one argument and returning a boolean. Objects for which filter(obj) returns False will be ignored.

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.

Changed in version 3.0: New parameter: file.

Changed in version 3.1.3: New parameter: filter.

objgraph.growth([limit=10, peak_stats={}, shortnames=True, filter=None])¶

Count the increase in peak object since last call.

Returns a list of (type_name, total_count, increase_delta), descending order by increase_delta.

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.

If filter is specified, it should be a function taking one argument and returning a boolean. Objects for which filter(obj) returns False will be ignored.

The caveats documented in typestats() apply.

Example:

>>> growth(2)
[(tuple, 12282, 10), (dict, 1922, 7)]

New in version 3.3.0.

objgraph.show_growth([limit=10, peak_stats={}, shortnames=True, file=sys.stdout, filter=None])¶

Show the increase in peak object counts since last call.

if peak_stats is None, peak object counts will recorded in func growth, and your can record the counts by yourself with set peak_stats to a dictionary.

The caveats documented in growth() apply.

Example:

>>> 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.

Changed in version 2.1: New parameter: file.

Changed in version 3.1.3: New parameter: filter.

objgraph.get_new_ids([skip_update=False, limit=10, sortby='deltas', shortnames=True, file=sys.stdout])¶

Find and display new objects allocated since last call.

Shows the increase in object counts since last call to this function and returns the memory address ids for new objects.

Returns a dictionary mapping object type names to sets of object IDs that have been created since the last time this function was called.

skip_update (bool): If True, returns the same dictionary that was returned during the previous call without updating the internal state or examining the objects currently in memory.

limit (int): The maximum number of rows that you want to print data for. Use 0 to suppress the printing. Use None to print everything.

sortby (str): This is the column that you want to sort by in descending order. Possible values are: ‘old’, ‘current’, ‘new’, ‘deltas’

shortnames (bool): If True, classes with the same name but defined in different modules will be lumped together. If False, all type names will be qualified with the module name. If None (default), get_new_ids will remember the value from previous calls, so it’s enough to prime this once. By default the primed value is True.

_state (dict): Stores old, current, and new_ids in memory. It is used by the function to store the internal state between calls. Never pass in this argument unless you know what you’re doing.

The caveats documented in growth() apply.

When one gets new_ids from get_new_ids(), one can use at_addrs() to get a list of those objects. Then one can iterate over the new objects, print out what they are, and call show_backrefs() or show_chain() to see where they are referenced.

Example:

>>> _ = get_new_ids() # store current objects in _state
>>> _ = get_new_ids() # current_ids become old_ids in _state
>>> a = [0, 1, 2] # list we don't know about
>>> b = [3, 4, 5] # list we don't know about
>>> new_ids = get_new_ids(limit=3) # we see new lists
======================================================================
Type                    Old_ids  Current_ids      New_ids Count_Deltas
======================================================================
list                        324          326           +3           +2
dict                       1125         1125           +0           +0
wrapper_descriptor         1001         1001           +0           +0
======================================================================
>>> new_lists = at_addrs(new_ids['list'])
>>> a in new_lists
True
>>> b in new_lists
True

New in version 3.4.

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.at_addrs(address_set)¶

Return a list of objects for a given set of memory addresses.

The reverse of [id(obj1), id(obj2), …]. Note that objects are returned in an arbitrary order.

When one gets new_ids from get_new_ids(), one can use this function to get a list of those objects. Then one can iterate over the new objects, print out what they are, and call show_backrefs() or show_chain() to see where they are referenced.

>>> a = [0, 1, 2]
>>> new_ids = get_new_ids()
>>> new_lists = at_addrs(new_ids['list'])
>>> a in new_lists
True

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

New in version 3.4.

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 types
>>> is_proper_module([])
False
>>> is_proper_module(types)
True
>>> is_proper_module(types.ModuleType('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_ref_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, filename or output arguments like for show_backrefs() or show_refs().

New in version 1.5.

Changed in version 1.7: New parameter: backrefs.

Changed in version 2.0: New parameter: output.

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 and output are not specified, show_backrefs will try to display the graph inline (if you’re using IPython), otherwise it’ll 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.

output if specified, the GraphViz output will be written to this file object. output and filename should not both be specified.

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.

Use extra_node_attrs (a function taking the current object as argument, returning a dict of strings) to add extra attributes to the nodes. See https://www.graphviz.org/doc/info/attrs.html for a list of possible node attributes.

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())])
>>> show_backrefs(obj, extra_node_attrs=lambda x: dict(URL=str(id(x))))

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.

Changed in version 2.0: New parameter: output.

Changed in version 3.5: New parameter: extra_node_attrs.

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 and output is not specified, show_refs will try to display the graph inline (if you’re using IPython), otherwise it’ll 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.

output if specified, the GraphViz output will be written to this file object. output and filename should not both be specified.

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.

Use extra_node_attrs (a function taking the current object as argument, returning a dict of strings) to add extra attributes to the nodes. See https://www.graphviz.org/doc/info/attrs.html for a list of possible node attributes.

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())])
>>> show_refs(obj, extra_node_attrs=lambda x: dict(URL=str(id(x))))

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.

Changed in version 2.0: New parameter: output.

Changed in version 3.5: New parameter: extra_node_attrs.

`objgraph`¶

Statistics¶

Locating and Filtering Objects¶

Traversing and Displaying Object Graphs¶

Table of Contents

Previous topic

Next topic

objgraph¶

Statistics¶

Locating and Filtering Objects¶

Traversing and Displaying Object Graphs¶

`objgraph`¶