Reference

Functions

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

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()[source]

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

hunter.Q(*predicates, **query)[source]

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)[source]

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)[source]

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

hunter.Or(*predicates, **kwargs)[source]

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)[source]

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)[source]

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

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

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)[source]

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)[source]

An action that starts pdb.

__call__(event)[source]

Runs a pdb.set_trace at the matching frame.

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

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)[source]

Handle event and print the specified variables.

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