hunter 0.5.1

Hunter is a flexible code tracing toolkit.

Hunter is a flexible code tracing toolkit, not for measuring coverage, but for debugging, logging, inspection and other nefarious purposes. It has a simple Python API and a convenient terminal API (see Environment variable activation).

API is considered unstable until 1.0 is released.

• Free software: BSD license

Installation

pip install hunter

Documentation

https://python-hunter.readthedocs.org/

Overview

The default action is to just print the code being executed. Example:

import hunter
hunter.trace(module='posixpath')

import os
os.path.join('a', 'b')

Would result in:

python2.7/posixpath.py:60    call      def join(a, *p):
python2.7/posixpath.py:64    line          path = a
python2.7/posixpath.py:65    line          for b in p:
python2.7/posixpath.py:66    line              if b.startswith('/'):
python2.7/posixpath.py:68    line              elif path == '' or path.endswith('/'):
python2.7/posixpath.py:71    line                  path += '/' + b
python2.7/posixpath.py:65    line          for b in p:
python2.7/posixpath.py:72    line          return path
python2.7/posixpath.py:72    return        return path
                             ...       return value: 'a/b'

• or in a terminal:

You can have custom actions, like a variable printer - example:

import hunter
hunter.trace(hunter.Q(module='posixpath', action=hunter.VarsPrinter('path')))

import os
os.path.join('a', 'b')

Would result in:

python2.7/posixpath.py:60    call      def join(a, *p):
python2.7/posixpath.py:64    line          path = a
                             vars      path => 'a'
python2.7/posixpath.py:65    line          for b in p:
                             vars      path => 'a'
python2.7/posixpath.py:66    line              if b.startswith('/'):
                             vars      path => 'a'
python2.7/posixpath.py:68    line              elif path == '' or path.endswith('/'):
                             vars      path => 'a'
python2.7/posixpath.py:71    line                  path += '/' + b
                             vars      path => 'a/b'
python2.7/posixpath.py:65    line          for b in p:
                             vars      path => 'a/b'
python2.7/posixpath.py:72    line          return path
                             vars      path => 'a/b'
python2.7/posixpath.py:72    return        return path
                             ...       return value: 'a/b'

• or in a terminal:

You can give it a tree-like configuration where you can optionally configure specific actions for parts of the tree (like dumping variables or a pdb set_trace):

TODO: More examples.

Environment variable activation

For your convenience environment variable activation is available. Just run your app like this:

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

Development

To run the all tests run:

tox

Changelog

0.5.1 (2015-04-15)

• Fixed Event.globals to actually be the dict of global vars (it was just the locals).

0.5.0 (2015-04-06)

• Fixed And and Or “single argument unwrapping”.

• Implemented predicate compression. Example: Or(Or(a, b), c) is converted to Or(a, b, c).

• Renamed the Event.source to Event.fullsource.

• Added Event.source that doesn’t do any fancy sourcecode tokenization.

• Fixed Event.fullsource return value for situations where the tokenizer would fail.

• Made the print function available in the PYTHONHUNTER env var payload.

• Added a __repr__ for Event.

0.4.0 (2015-03-29)

• Disabled colors for Jython (contributed by Claudiu Popa in #12).

• Test suite fixes for Windows (contributed by Claudiu Popa in #11).

• Added an introduction section in the docs.

• Implemented a prettier fallback for when no sources are available for that frame.

• Implemented fixups in cases where you use action classes as a predicates.

0.3.1 (2015-03-29)

• Forgot to merge some commits …

0.3.0 (2015-03-29)

• Added handling for internal repr failures.

• Fixed issues with displaying code that has non-ascii characters.

• Implemented better display for call frames so that when a function has decorators the function definition is shown (instead of just the first decorator). See: #8.

0.2.1 (2015-03-28)

• Added missing color entry for exception events.

• Added Event.line property. It returns the source code for the line being run.

0.2.0 (2015-03-27)

• Added color support (and colorama as dependency).

• Added support for expressions in VarsPrinter.

• Breaking changes:

  • Renamed F to Q. And Q is now just a convenience wrapper for Query.

  • Renamed the PYTHON_HUNTER env variable to PYTHONHUNTER.

  • Changed When to take positional arguments.

  • Changed output to show 2 path components (still not configurable).

  • Changed VarsPrinter to take positional arguments for the names.

• Improved error reporting for env variable activation (PYTHONHUNTER).

• Fixed env var activator (the .pth file) installation with setup.py install (the “egg installs”) and setup.py develop/pip install -e (the “egg links”).

0.1.0 (2015-03-22)

• First release on PyPI.