hunter

Functions

hunter.trace	Starts tracing.
hunter.stop	Stop tracing.
hunter.Q	Handles situations where hunter.Query objects (or other callables) are passed in as positional arguments.

Predicates

hunter.Query	A query class.
hunter.When	Runs actions when condition(event) is True.
hunter.And	And predicate. Exits at the first sub-predicate that returns False.
hunter.Or	Or predicate. Exits at first sub-predicate that returns True.

Actions

hunter.CodePrinter	An action that just prints the code being executed.
hunter.Debugger	An action that starts pdb.
hunter.VarsPrinter	An action that prints local variables and optionally global variables visible from the current executing frame.

Objects

hunter.Event

Event wrapper for frame, kind, arg (the arguments the settrace function gets).

hunter.trace(*predicates, **options)

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

Parameters:

• predicates (hunter.Q instances) – Runs actions if any of the given predicates match.
• options – Keyword arguments that are passed to hunter.Q, for convenience.

hunter.stop()

Stop tracing. Restores previous tracer (if any).

class hunter.Q

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

class hunter.Query(**query)

A query class.

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

__and__(other)

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

__call__(event)

Handles event. Returns True if all criteria matched.

__init__(**query)

Parameters:query –

criteria to match on.

Accepted arguments: arg, code, filename, frame, fullsource, function, globals, kind, lineno, locals, module, source, stdlib, tracer.

__or__(other)

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

class hunter.When(condition, *actions)

Runs actions when condition(event) is True.

Actions take a single event argument.

__call__(event)

Handles the event.

class hunter.And(*predicates)

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

__call__(event)

Handles the event.

class hunter.Or(*predicates)

Or predicate. Exits at first sub-predicate that returns True.

__call__(event)

Handles the event.

class hunter.CodePrinter(stream=<open file '<stderr>', mode 'w'>, force_colors=False, filename_alignment=40)

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.

__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=<class pdb.Pdb>, **kwargs)

An action that starts pdb.

__call__(event)

Runs a pdb.set_trace at the matching frame.

class hunter.VarsPrinter(*names, **options)

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.
• stream (file-like) – Stream to write to. Default: sys.stderr.
• filename_alignment (int) – Default size for the filaneme column (files are right-aligned). Default: 40.
• globals (bool) – Allow access to globals. Default: False (only looks at locals).

__call__(event)

Handle event and print the specified variables.

static _iter_symbols(code)

Iterate all the variable names in the given expression.

Example:

• self.foobar yields self
• self[foobar] yields self` and foobar

_safe_eval(code, event)

Try to evaluate the given code on the given frame. If failure occurs, returns some ugly string with exception.

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

Event wrapper for frame, kind, arg (the arguments the settrace function gets).

Provides few convenience properties.

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.