Introduction

Installation

To install hunter run:

pip install hunter

The trace function

The hunter.trace function can take 2 types of arguments:

• Keyword arguments like module, function or action. This is for convenience.
• Callbacks that take an event argument:
  • Builtin predicates like: hunter.Query, hunter.When, hunter.And or hunter.Or.
  • Actions like: hunter.CodePrinter, hunter.Debugger or hunter.VarsPrinter

Note that hunter.trace will use hunter.Q when you pass multiple positional arguments or keyword arguments.

The Q function

The hunter.Q function provides a convenience API for you:

• Q(module='foobar') is converted to Query(module='foobar').
• Q(module='foobar', action=Debugger) is converted to When(Query(module='foobar'), Debugger).
• Q(module='foobar', actions=[CodePrinter, VarsPrinter('name')]) is converted to When(Query(module='foobar'), CodePrinter, VarsPrinter('name')).
• Q(Q(module='foo'), Q(module='bar')) is converted to Or(Q(module='foo'), Q(module='bar')).
• Q(your_own_callback, module='foo') is converted to Or(your_own_callback, Q(module='foo')).

Note that the default junction hunter.Q uses is hunter.Or.

The builtin predicates and actions

All the builtin predicates (hunter.Query, hunter.When, hunter.And and hunter.Or) support the | and & operators:

• Query(module='foo') | Query(module='bar') is converted to Or(Query(module='foo'), Query(module='bar'))
• Query(module='foo') & Query(module='bar') is converted to And(Query(module='foo'), Query(module='bar'))

Activation

You can activate Hunter in two ways.

via code

import hunter
hunter.trace(
    ...
)

via environment variable

Set the PYTHONHUNTER environment variable. Eg:

PYTHONHUNTER="module='os.path'" python yourapp.py

On Windows you’d do something like:

set PYTHONHUNTER=module='os.path'
python yourapp.py

The activation works with a clever .pth file that checks for that env var presence and before your app runs does something like this:

from hunter import *
trace(
    <whatever-you-had-in-the-PYTHONHUNTER-env-var>
)

That also means that it will do activation even if the env var is empty, eg: PYTHONHUNTER="".