Hunter

Warnings

• breaking The default action for `hunter.trace()` changed in Hunter 2.0. Before 2.0, `CodePrinter` was the default; `CallPrinter` is now generally used or explicitly set for detailed output.
  Fix: Explicitly specify `action=hunter.CallPrinter` or `action=hunter.CodePrinter` for desired output behavior.
• gotcha Hunter does not provide a direct negation operator for filters. To negate a filter, you must negate a `Query` object, e.g., `~Q(module='re')`.
  Fix: Use the Python `~` operator with a `hunter.Q` object for negation (e.g., `hunter.trace(~hunter.Q(module='my_module'))`).
• gotcha Hunter is designed for live code tracing and does not inherently store execution data. It is not suitable for 'post-mortem' debugging if the problem cannot be reproduced while Hunter is active.
  Fix: Ensure you can reproduce the scenario while Hunter is actively tracing, or integrate it into your test suite for automated tracing during execution.
• gotcha The library does not offer specialized filters for broader concepts like 'packages', or for granular details like 'function arguments' or 'return values' directly. Filtering is primarily done at the module level or requires custom filter functions.
  Fix: Filter by `module` with operators, or implement a custom filter function (a callable that receives an `Event` object) for more specific tracing needs.
• deprecated Support for Python 2.7 was officially dropped in version 3.4.0. Users attempting to use Hunter with Python 2.x environments will encounter installation or runtime issues.
  Fix: Upgrade to Python 3.9 or higher (as per current `requires_python`) or use an older `hunter` version compatible with Python 2.x (e.g., `<3.4.0`).

Install

• pip install hunter Install stable version

Imports

• hunter

  import hunter

• CallPrinter

  from hunter import CallPrinter

  Commonly accessed as hunter.CallPrinter after importing hunter directly.
• Q

  from hunter import Q

  Used for building complex filters. Commonly accessed as hunter.Q after importing hunter directly.

Quickstart

This example demonstrates how to activate Hunter to trace calls within the 'os.path' module using the `CallPrinter` action, both explicitly and via a context manager for localized tracing. Remember to call `hunter.stop()` when tracing is no longer needed to avoid overhead.

import hunter
import os

def my_function():
    return os.path.join('a', 'b')

# Activate tracing for the 'os.path' module with CallPrinter action
hunter.trace(module='os.path', action=hunter.CallPrinter)

print(f"Result: {my_function()}")

# Deactivate tracing
hunter.stop()

# You can also use it with a context manager (preferred for local scope)
with hunter.trace(module='os.path', action=hunter.CallPrinter):
    print(f"Result from context: {os.path.join('x', 'y')}")