Reference

Functions

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

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: False.
• action – Action to run if all the predicates return True. Default: CodePrinter.
• actions – Actions to run (in case you want more than 1).

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.

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, code, filename, frame, fullsource, function, globals, kind, lineno, locals, module, source, stdlib, tracer.

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

Note

This will be the default action in hunter 2.0.

__call__(event, sep='/', join=<function join>)

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)

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, sep='/', join=<function join>)

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.

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.

Objects

class hunter.event.Event(frame, kind, arg, tracer)

Event wrapper for frame, kind, arg (the arguments the settrace function gets). This objects is passed to your custom functions or predicates.

Provides few convenience properties.

Warning

Users do not instantiate this directly.

code

A code object (not a string).

filename

A string with absolute path to file.

fullsource

A string with the sourcecode for the current statement (from linecache - failures are ignored).

May include multiple lines if it’s a class/function definition (will include decorators).

function

A string with function name.

globals

A dict with global variables.

lineno

An integer with line number in file.

locals

A dict with local variables.

module

A string with module name (eg – "foo.bar").

source

A string with the sourcecode for the current line (from linecache - failures are ignored).

Fast but sometimes incomplete.

stdlib

A boolean flag. True if frame is in stdlib.

thread

Current thread object.

threadid

Current thread ident. If current thread is main thread then it returns None.

threadname

Current thread name.