hunter

library3.9.0pypypi✓ verified 22d ago

Hunter is a flexible code tracing toolkit for debugging, logging, and inspection, not for code coverage. It offers a simple Python API, a convenient terminal API, and a CLI tool. The library is currently at version 3.9.0 and is actively maintained with a regular release cadence.

testing observability

pip install hunter

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · HUNTER

hunter

testingpythonv3.9.0

Install

1.8s avg

Import

—

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.9.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 22.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.000s · 23MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

hunter

✓ import hunter

CallPrinter

✓ from hunter import CallPrinter

Commonly accessed as hunter.CallPrinter after importing hunter directly.

✓ from hunter import Q

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

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')}")

hunter --version

Debug

Known issues

breakingThe 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.

affects: <2.0

gotchaHunter 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'))`).

affects: All versions

gotchaHunter 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.

affects: All versions

gotchaThe 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.

affects: All versions

deprecatedSupport 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`).

affects: >=3.4.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hunter'

The 'hunter' library has not been installed in your Python environment, or the environment where it's installed is not currently active.

fix

Install the library using pip: `pip install hunter`

TypeError: 'str' object is not callable

This error occurs when a string literal or a non-callable object is passed to a `hunter.trace()` argument (like `actions` or filter predicates) that expects a callable (e.g., a function, a class instance with `__call__`, or a `hunter.actions` object).

fix

Ensure that arguments passed to `hunter.trace()` that are meant to be actions or filters are callable objects. For instance, use `hunter.actions.CallPrinter()` instead of a string like `'CallPrinter'`, or pass a function reference instead of its name as a string.

AttributeError: module 'hunter' has no attribute 'trace'

This error typically indicates a typo in the attribute name (e.g., `trace` vs `Trace`), an incorrect import statement, or a version conflict where the `trace` function might not be directly exposed under the `hunter` module's top level in an older or different version of the library.

fix

Verify the spelling of `trace` and ensure you are importing the `hunter` library correctly. The standard usage is `import hunter` followed by `hunter.trace(...)`. If you intend to import `trace` directly, use `from hunter import trace`.

Upgrade

Version history

3.9.0latest on PyPI · released Aug 22, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ionelmc/python-hunter ↗

packagehttps://pypi.org/project/hunter/ ↗

docshttps://python-hunter.readthedocs.io/ ↗

changeloghttps://python-hunter.readthedocs.io/en/latest/changelog.html ↗