Introduction¶
The trace
function¶
The hunter.trace
function can take 2 types of arguments:
- Keyword arguments like
module
,function
oraction
. This is for convenience. - Callbacks that take an
event
argument:- Builtin predicates like:
hunter.Query
,hunter.When
,hunter.And
orhunter.Or
. - Actions like:
hunter.CodePrinter
,hunter.Debugger
orhunter.VarsPrinter
- Any function. Or a disgusting lambda.
- Builtin predicates like:
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 toQuery(module='foobar')
.Q(module='foobar', action=Debugger)
is converted toWhen(Query(module='foobar'), Debugger)
.Q(module='foobar', actions=[CodePrinter, VarsPrinter('name')])
is converted toWhen(Query(module='foobar'), CodePrinter, VarsPrinter('name'))
.Q(Q(module='foo'), Q(module='bar'))
is converted toAnd(Q(module='foo'), Q(module='bar'))
.Q(your_own_callback, module='foo')
is converted toAnd(your_own_callback, Q(module='foo'))
.
Note that the default junction hunter.Q
uses is hunter.And
.
Composing¶
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 toOr(Query(module='foo'), Query(module='bar'))
Query(module='foo') & Query(module='bar')
is converted toAnd(Query(module='foo'), Query(module='bar'))
~Query(module='foo')
is converted toNot(Query(module='foo'))
Operators¶
New in version 1.0.0.
You can add startswith
, endswith
, in
, contains
, regex
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
.
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 meansrepr
will match!Query(module_regex='(re|sre.*)$')
will match any events fromre
or anything that starts withsre
.
Note
If you want to filter out stdlib stuff you’re better off with using Query(stdlib=False)
.
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=""
.