Metadata-Version: 2.0
Name: hunter
Version: 0.6.0
Summary: Hunter is a flexible code tracing toolkit.
Home-page: https://github.com/ionelmc/python-hunter
Author: Ionel Cristian Mărieș
Author-email: contact@ionelmc.ro
License: BSD
Keywords: trace,tracer,settrace,debugger,debugging,code,source
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Debuggers
Requires-Dist: colorama
Requires-Dist: fields
Requires-Dist: six

======
Hunter
======

.. list-table::
    :stub-columns: 1

    * - docs
      - |docs|
    * - tests
      - | |travis| |appveyor| |requires|
        | |coveralls| |codecov|
        | |landscape| |scrutinizer| |codacy| |codeclimate|
    * - package
      - |version| |downloads| |wheel| |supported-versions| |supported-implementations|

.. |docs| image:: https://readthedocs.org/projects/python-hunter/badge/?style=flat
    :target: https://readthedocs.org/projects/python-hunter
    :alt: Documentation Status

.. |travis| image:: https://travis-ci.org/ionelmc/python-hunter.svg?branch=master
    :alt: Travis-CI Build Status
    :target: https://travis-ci.org/ionelmc/python-hunter

.. |appveyor| image:: https://ci.appveyor.com/api/projects/status/github/ionelmc/python-hunter?branch=master&svg=true
    :alt: AppVeyor Build Status
    :target: https://ci.appveyor.com/project/ionelmc/python-hunter

.. |requires| image:: https://requires.io/github/ionelmc/python-hunter/requirements.svg?branch=master
    :alt: Requirements Status
    :target: https://requires.io/github/ionelmc/python-hunter/requirements/?branch=master

.. |coveralls| image:: https://coveralls.io/repos/ionelmc/python-hunter/badge.svg?branch=master&service=github
    :alt: Coverage Status
    :target: https://coveralls.io/r/ionelmc/python-hunter

.. |codecov| image:: https://codecov.io/github/ionelmc/python-hunter/coverage.svg?branch=master
    :alt: Coverage Status
    :target: https://codecov.io/github/ionelmc/python-hunter

.. |landscape| image:: https://landscape.io/github/ionelmc/python-hunter/master/landscape.svg?style=flat
    :target: https://landscape.io/github/ionelmc/python-hunter/master
    :alt: Code Quality Status

.. |codacy| image:: https://img.shields.io/codacy/REPLACE_WITH_PROJECT_ID.svg?style=flat
    :target: https://www.codacy.com/app/ionelmc/python-hunter
    :alt: Codacy Code Quality Status

.. |codeclimate| image:: https://codeclimate.com/github/ionelmc/python-hunter/badges/gpa.svg
   :target: https://codeclimate.com/github/ionelmc/python-hunter
   :alt: CodeClimate Quality Status
.. |version| image:: https://img.shields.io/pypi/v/hunter.svg?style=flat
    :alt: PyPI Package latest release
    :target: https://pypi.python.org/pypi/hunter

.. |downloads| image:: https://img.shields.io/pypi/dm/hunter.svg?style=flat
    :alt: PyPI Package monthly downloads
    :target: https://pypi.python.org/pypi/hunter

.. |wheel| image:: https://img.shields.io/pypi/wheel/hunter.svg?style=flat
    :alt: PyPI Wheel
    :target: https://pypi.python.org/pypi/hunter

.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/hunter.svg?style=flat
    :alt: Supported versions
    :target: https://pypi.python.org/pypi/hunter

.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/hunter.svg?style=flat
    :alt: Supported implementations
    :target: https://pypi.python.org/pypi/hunter

.. |scrutinizer| image:: https://img.shields.io/scrutinizer/g/ionelmc/python-hunter/master.svg?style=flat
    :alt: Scrutinizer Status
    :target: https://scrutinizer-ci.com/g/ionelmc/python-hunter/

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 
<env-var-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:

.. sourcecode:: python

    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:

.. image:: https://raw.githubusercontent.com/ionelmc/python-hunter/master/docs/simple-trace.png

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

.. sourcecode:: python

    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:

.. image:: https://raw.githubusercontent.com/ionelmc/python-hunter/master/docs/vars-trace.png

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.

.. _env-var-activation:

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.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 <https://github.com/ionelmc/python-hunter/issues/16>`_.
* Fixed handling in VarsPrinter: properly print eval errors and don't try to show anything if there's an AttributeError.
  Closes `#18 <https://github.com/ionelmc/python-hunter/issues/18>`_.
* Added a ``stdlib`` boolean flag (for filtering purposes).
  Closes `#15 <https://github.com/ionelmc/python-hunter/issues/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, ``setup.py 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 <https://github.com/ionelmc/python-hunter/pull/12>`_).
* Test suite fixes for Windows (contributed by Claudiu Popa in `#11 <https://github.com/ionelmc/python-hunter/pull/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 <https://github.com/ionelmc/python-hunter/issues/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.


