# `objgraph`

Tools for drawing Python object reference graphs with graphviz.

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

Copyright (c) 2008-2023 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.

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

  Added 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)]

  Added 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

  Added 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)]

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

  Added 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

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

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

  Added 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

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

  Added 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()`.

  Added 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))))

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