Introduction - Hunter 3.9.1.dev50 documentation (original) (raw)

View this page

Edit this page

Toggle table of contents sidebar

Installation¶

To install hunter run:

The trace function¶

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

• Keyword arguments like module, function or action (see hunter.Event for all the possible filters).
• Callbacks that take an event argument:
  • Builtin predicates like: hunter.predicates.Query, hunter.When, hunter.And or hunter.Or.
  • Actions like: hunter.actions.CodePrinter, hunter.actions.Debugger or hunter.actions.VarsPrinter
  • Any function. Or a disgusting lambda.

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 toWhen(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¶

Added 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.

Added in version 2.0.0: You can also use these convenience aliases: sw (startswith), ew (endswith), rx (regex) andhas (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( )

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.