Class CycleFinder

Class for finding cycles in Python data structures.

See Cyclops module docstring for details.

Create a cycle finder with empty root set.

t, t_refs_func, t_tag_func -> chase type t.

See module docstring for details.

Remove all internal references to external objects.

Empties the root set.
Does not change the set of types this CycleFinder chases.
Does not change the cycle filter in effect.

t -> remove type t from the set of chased types.

See module docstring for details.

purge_dead_roots=0 -> look for cycles, return true if found.

Identify all cycles among objects reachable from the root set.
Return true iff at least one cycle is found.

This should be called before any of the show_XXX methods.
Note that it's OK to add more objects to the root set and
call it again, or to change the set of chased types, etc.
find_cycles starts over from scratch each time it's called.

If optional arg purge_dead_roots is true (default false),
before searching for cycles the root set is purged of all
objects that the preceding run of find_cycles determined had a
true refcount of 0 (that is, the root set objects that are
still alive only because they appear in the root set).
Purging these allows their finalizers to get invoked, which
may allow a cascade of other objects (including cycles) to go
away too.

See also method install_cycle_filter.

Return the set of chased types, as a list.

Return the root set, as a list of (rc, cyclic?, obj) tuples.

Should be called after find_cycles.  For each object in the
root set, returns a triple consisting of
refcount
    number of outstanding references less those due to
    CycleFinder internals; see show_obj docstring for more
    details; this will be None if find_cycles hasn't been
    run, or not since the last clear()
cyclic?
    true (1) iff obj is known to be in a cycle
obj
    the object

filter_func=None -> a way to ignore "expected" cycles.

See module docstring for details.  This is a callback function
invoked whenever find_cycles() finds a cycle; the cycle is
ignored unless the callback returns true.

obj -> add object obj to the root set.

func, args=(), kwargs={} -> add objects to root set by magic.

Function func is invoked with arguments args and keyword
arguments kwargs.  For the duration of the call, each class
instance initialized by an __init__ call is automatically
added to the root set.  The result of invoking func is
returned.

compare=None -> print unique arc types in cycles.

See module docstring for details.  Briefly, each arc in a
cycle is categorized by the type of the source node, the kind
of arc (how we got from the source to the destination), and
the type of the destination node.  Each line of output
consists of those three pieces of info preceded by the count
of arcs of that kind.  By default, the rows are sorted first
by column 2 (source node type), then by columns 3 and 4.

compare=typename_address_cmp -> print all objects in cycles.

Prints to stdout.  Each distinct object find_cycles found in a
cycle is displayed.  The set of objects found in cycles is
first sorted by the optional "compare" function.  By default,
objects are sorted using their type name as the primary key
and their storage address (id) as the secondary key; among
objects of instance type, sorts by the instances' class names;
among objects of class type, sorts by the classes' names.

Print all cycles to stdout.

obj -> print short description of obj to sdtout.

This is of the form

<address> rc:<refcount> <typename>
    repr: <shortrepr>

where
<address>
    hex address of obj
<refcount>
    If find_cycles() has been run and obj is in the root set
    or was found in a cycle, this is the number of references
    outstanding less the number held internally by
    CycleFinder.  In most cases, this is what the true
    refcount would be had you not used CycleFinder at all.
    You can screw that up, e.g. by installing a cycle filter
    that holds on to references to one or more cycle elements.
    If find_cycles() has not been run, or has but obj wasn't
    found in a cycle and isn't in the root set, <refcount> is
    "?".
<typename>
    type(obj), as a string.  If obj.__class__ exists, also
    prints the class name.
<shortrepr>
    repr(obj), but using a variant of the std module repr.py
    that limits the number of characters displayed.

compare=typename_address_cmp -> print SCCs.

Prints to stdout.  Shows the objects in cycles partitioned into
strongly connected components (that is, the largest groupings
possible such that each object in an SCC is reachable from every
other object in that SCC).  Within each SCC, objects are sorted
as for show_cycleobjs.

Print statistics for the last run of find_cycles.