Introduction¶
The trace
function¶
The hunter.trace
function can take 2 types of arguments:
- Keyword arguments like
module
,function
oraction
(seehunter.Event
for all the possible filters). - Callbacks that take an
event
argument:- Builtin predicates like:
hunter.predicates.Query
,hunter.When
,hunter.And
orhunter.Or
. - Actions like:
hunter.actions.CodePrinter
,hunter.actions.Debugger
orhunter.actions.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.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 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
, 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 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 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.