Reference

Functions

hunter.trace(*predicates, clear_env_var=False, action=CodePrinter, actions=[], **kwargs)

Starts tracing. Can be used as a context manager (with slightly incorrect semantics - it starts tracing before __enter__ is called).

Parameters:

*predicates (callables) – Runs actions if all of the given predicates match.

Keyword Arguments:  

• clear_env_var – Disables tracing in subprocess. Default: False.
• threading_support –

  Enable tracing new threads. Default: None.

  Modes:

  • None - automatic (enabled but actions only prefix with thread name if more than 1 thread)
  • False - completely disabled
  • True - enabled (actions always prefix with thread name)

  You can also use: threads_support, thread_support, threadingsupport, threadssupport, threadsupport, threading, threads or thread.

• action – Action to run if all the predicates return True. Default: CodePrinter.
• actions – Actions to run (in case you want more than 1).
• **kwargs – for convenience you can also pass anything that you’d pass to hunter.Q

hunter.stop()

Stop tracing. Restores previous tracer (if there was any).

hunter.Q(*predicates, **query)

Handles situations where hunter.Query objects (or other callables) are passed in as positional arguments. Conveniently converts that to an hunter.And predicate.

hunter.wrap(function_to_trace=None, **trace_options)

Functions decorated with this will be traced.

Use local=True to only trace local code, eg:

@hunter.wrap(local=True)
def my_function():
    ...

Keyword arguments are allowed, eg:

@hunter.wrap(action=hunter.CallPrinter)
def my_function():
    ...

Or, filters:

@hunter.wrap(module='foobar')
def my_function():
    ...

Predicates

class hunter.Query

A query class.

See hunter.Event for fields that can be filtered on.

__and__

Convenience API so you can do Q() & Q(). It converts that to And(Q(), Q()).

__call__

Handles event. Returns True if all criteria matched.

__eq__

x.__eq__(y) <==> x==y

__ge__

x.__ge__(y) <==> x>=y

__gt__

x.__gt__(y) <==> x>y

__hash__

__init__

Args –

query: criteria to match on.

Accepted arguments: arg, calls, code, depth, filename, frame, fullsource, function, globals, kind, lineno, locals, module, source, stdlib, threadid, threadname.

__invert__

x.__invert__() <==> ~x

__le__

x.__le__(y) <==> x<=y

__lt__

x.__lt__(y) <==> x<y

__ne__

x.__ne__(y) <==> x!=y

__new__(S, ...) → a new object with type S, a subtype of T

__or__

Convenience API so you can do Q() | Q(). It converts that to Or(Q(), Q()).

__rand__

x.__rand__(y) <==> y&x

__repr__

__ror__

x.__ror__(y) <==> y|x

__str__

class hunter.When

Runs actions when condition(event) is True.

Actions take a single event argument.

__and__

x.__and__(y) <==> x&y

__call__

Handles the event.

__eq__

x.__eq__(y) <==> x==y

__ge__

x.__ge__(y) <==> x>=y

__gt__

x.__gt__(y) <==> x>y

__hash__

__init__

x.__init__(…) initializes x; see help(type(x)) for signature

__invert__

x.__invert__() <==> ~x

__le__

x.__le__(y) <==> x<=y

__lt__

x.__lt__(y) <==> x<y

__ne__

x.__ne__(y) <==> x!=y

__new__(S, ...) → a new object with type S, a subtype of T

__or__

x.__or__(y) <==> x|y

__rand__

x.__rand__(y) <==> y&x

__repr__

__ror__

x.__ror__(y) <==> y|x

__str__

hunter.And(*predicates, **kwargs)

And predicate. Returns False at the first sub-predicate that returns False.

hunter.Or(*predicates, **kwargs)

Or predicate. Returns True at the first sub-predicate that returns True.

Actions

class hunter.CallPrinter(stream=sys.stderr, filename_alignment=40, force_colors=False, repr_limit=512)

An action that just prints the code being executed, but unlike hunter.CodePrinter it indents based on callstack depth and it also shows repr() of function arguments.

Parameters:

• stream (file-like) – Stream to write to. Default: sys.stderr.
• filename_alignment (int) – Default size for the filename column (files are right-aligned). Default: 40.
• force_colors (bool) – Force coloring. Default: False.
• repr_limit (bool) – Limit length of repr() output. Default: 512.

New in version 1.2.0.

__call__(event)

Handle event and print filename, line number and source code. If event.kind is a return or exception also prints values.

__init__(**options)

x.__init__(…) initializes x; see help(type(x)) for signature

class hunter.CodePrinter(stream=sys.stderr, filename_alignment=40, force_colors=False, repr_limit=512)

An action that just prints the code being executed.

Parameters:

• stream (file-like) – Stream to write to. Default: sys.stderr.
• filename_alignment (int) – Default size for the filename column (files are right-aligned). Default: 40.
• force_colors (bool) – Force coloring. Default: False.
• repr_limit (bool) – Limit length of repr() output. Default: 512.

__call__(event)

Handle event and print filename, line number and source code. If event.kind is a return or exception also prints values.

class hunter.Debugger(klass=pdb.Pdb, **kwargs)

An action that starts pdb.

__call__(event)

Runs a pdb.set_trace at the matching frame.

__eq__(other)

x.__eq__(y) <==> x==y

__init__()

x.__init__(…) initializes x; see help(type(x)) for signature

__repr__() <==> repr(x)

__str__() <==> str(x)

class hunter.VarsPrinter(name, [name, [name, [..., ]]]globals=False, stream=sys.stderr, filename_alignment=40, force_colors=False, repr_limit=512)

An action that prints local variables and optionally global variables visible from the current executing frame.

Parameters:

• *names (strings) – Names to evaluate. Expressions can be used (will only try to evaluate if all the variables are present on the frame.
• globals (bool) – Allow access to globals. Default: False (only looks at locals).
• stream (file-like) – Stream to write to. Default: sys.stderr.
• filename_alignment (int) – Default size for the filename column (files are right-aligned). Default: 40.
• force_colors (bool) – Force coloring. Default: False.
• repr_limit (bool) – Limit length of repr() output. Default: 512.

__call__(event)

Handle event and print the specified variables.

__init__(*names, **options)

x.__init__(…) initializes x; see help(type(x)) for signature

Objects

class hunter.Event

A wrapper object for Frame objects. Instances of this are passed to your custom functions or predicates.

Provides few convenience properties.

Parameters:

• frame (Frame)
• kind (str)
• arg
• tracer (hunter.Tracer)

class hunter.Tracer

Tracer object.

__call__

The settrace function.

Note

This always returns self (drills down) - as opposed to only drilling down when predicate(event) is True because it might match further inside.

__enter__()

Does nothing. Users are expected to call hunter.Tracer.trace().

Returns: self

__exit__()

Wrapper around hunter.Tracer.stop(). Does nothing with the arguments.

stop()

Stop tracing. Reinstalls the hunter.Tracer.previous tracer.

trace()

Starts tracing with the given callable.

Parameters:predicate (callable that accepts a single hunter.Event argument) Returns:self