objgraph
¶
Tools for drawing Python object reference graphs with graphviz.
You can find documentation online at http://mg.pov.lt/objgraph/
Copyright (c) 2008-2016 Marius Gedminas <marius@pov.lt> and contributors
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.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 setlimit
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, file=sys.stdout])¶ 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
.Changed in version 3.0: New parameter:
file
.
-
objgraph.
show_growth
([limit=10, peak_stats={}, shortnames=True, file=sys.stdout])¶ Show the increase in peak object counts since last call.
Limits the output to
limit
largest deltas. You may setlimit
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:
>>> 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
.
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
ifobj
can be treated like a garbage collector root.That is, if
obj
is a module that is insys.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 ofNone
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()
orfind_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()
andgc.get_referents()
are not perfectly symmetrical.You can specify
highlight
,extra_info
,refcounts
,shortnames
,filename
oroutput
arguments like forshow_backrefs()
orshow_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. Iffilename
andoutput
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
andfilename
should not both be specified.Use
max_depth
andtoo_many
to limit the depth and breadth of the graph.Use
filter
(a predicate) andextra_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
.Changed in version 2.0: New parameter:
output
.
-
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. Iffilename
andoutput
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
andfilename
should not both be specified.Use
max_depth
andtoo_many
to limit the depth and breadth of the graph.Use
filter
(a predicate) andextra_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
.Changed in version 2.0: New parameter:
output
.