Introduction

Installation

To install hunter run:

pip install hunter

The trace function

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

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 And(Q(module='foo'), Q(module='bar')).
  • Q(your_own_callback, module='foo') is converted to And(your_own_callback, Q(module='foo')).

Note that the default junction hunter.Q() uses is hunter.predicates.And.

Composing

All the builtin predicates (hunter.predicates.Query, hunter.predicates.When, hunter.predicates.And, hunter.predicates.Not and hunter.predicates.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'))
  • ~Query(module='foo') is converted to Not(Query(module='foo'))

Operators

New in version 1.0.0: You can add startswith, endswith, in, contains, regex, lt, lte, gt, gte to your keyword arguments, just like in Django. Double underscores are not necessary, but in case you got twitchy fingers it’ll just work - filename__startswith is the same as filename_startswith.

New in version 2.0.0: You can also use these convenience aliases: sw (startswith), ew (endswith), rx (regex) and has (contains).

Examples:

  • Query(module_in=['re', 'sre', 'sre_parse']) will match events from any of those modules.
  • ~Query(module_in=['re', 'sre', 'sre_parse']) will match events from any modules except those.
  • Query(module_startswith=['re', 'sre', 'sre_parse']) will match any events from modules that starts with either of those. That means repr will match!
  • Query(module_regex='(re|sre.*)$') will match any events from re or anything that starts with sre.

Note

If you want to filter out stdlib stuff you’re better off with using Query(stdlib=False).

Activation

You can activate Hunter in three ways.

from code

import hunter
hunter.trace(
    ...
)

with an 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="".

with a CLI tool

If you got an already running process you can attach to it with hunter-trace. See Remote tracing for details.