Skip to main content

Hunter is a flexible code tracing toolkit.

Project description


Documentation Status


Travis-CI Build Status AppVeyor Build Status Requirements Status
Coverage Status Coverage Status
Code Quality Status Scrutinizer Status Codacy Code Quality Status CodeClimate Quality Status


PyPI Package latest release PyPI Package monthly downloads PyPI Wheel Supported versions Supported implementations

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


pip install hunter



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

import hunter

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

Would result in:

python2.7/    call      def join(a, *p):
python2.7/    line          path = a
python2.7/    line          for b in p:
python2.7/    line              if b.startswith('/'):
python2.7/    line              elif path == '' or path.endswith('/'):
python2.7/    line                  path += '/' + b
python2.7/    line          for b in p:
python2.7/    line          return path
python2.7/    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/    call      def join(a, *p):
python2.7/    line          path = a
                             vars      path => 'a'
python2.7/    line          for b in p:
                             vars      path => 'a'
python2.7/    line              if b.startswith('/'):
                             vars      path => 'a'
python2.7/    line              elif path == '' or path.endswith('/'):
                             vars      path => 'a'
python2.7/    line                  path += '/' + b
                             vars      path => 'a/b'
python2.7/    line          for b in p:
                             vars      path => 'a/b'
python2.7/    line          return path
                             vars      path => 'a/b'
python2.7/    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

On Windows you’d do something like:

set PYTHONHUNTER=module='os.path'

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 *

That also means that it will do activation even if the env var is empty, eg: PYTHONHUNTER="".


To run the all tests run:



0.6.0 (2015-10-10)

  • Added a clear_env_var option on the tracer (disables tracing in subprocess).

  • Added force_colors option on VarsPrinter and CodePrinter.

  • Allowed setting the stream to a file name (option on VarsPrinter and CodePrinter).

  • Bumped up the filename alignment to 40 cols.

  • If not merging then self is not kept as a previous tracer anymore. Closes #16.

  • Fixed handling in VarsPrinter: properly print eval errors and don’t try to show anything if there’s an AttributeError. Closes #18.

  • Added a stdlib boolean flag (for filtering purposes). Closes #15.

  • Fixed broken frames that have “None” for filename or module (so they can still be treated as strings).

  • Corrected output files in the install_lib command so that pip can uninstall the pth file. This only works when it’s installed with pip (sadly, install/develop and pip install -e will still leave pth garbage on pip uninstall hunter).

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 install (the “egg installs”) and develop/pip install -e (the “egg links”).

0.1.0 (2015-03-22)

  • First release on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hunter-0.6.0.tar.gz (36.1 kB view hashes)

Uploaded Source

Built Distribution

hunter-0.6.0-py2-none-any.whl (15.4 kB view hashes)

Uploaded Python 2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page