Skip to content

introduction.rst

Latest commit

 

History

History
122 lines (80 loc) · 4.11 KB

introduction.rst

File metadata and controls

122 lines (80 loc) · 4.11 KB

Introduction

Installation

To install hunter run:

pip install hunter

The trace function

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

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

The Q function

The :func:`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 :func:`hunter.Q` uses is :class:`hunter.predicates.And`.

Composing

All the builtin predicates (:class:`hunter.predicates.Query`, :class:`hunter.predicates.When`, :class:`hunter.predicates.And`, :class:`hunter.predicates.Not` and :class:`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

.. versionadded:: 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``.


.. versionadded:: 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 :doc:`remote` for details.