{"id":13468587,"url":"https://github.com/ionelmc/python-hunter","last_synced_at":"2025-05-15T00:07:50.229Z","repository":{"id":28819972,"uuid":"32343292","full_name":"ionelmc/python-hunter","owner":"ionelmc","description":"Hunter is a flexible code tracing toolkit. ","archived":false,"fork":false,"pushed_at":"2024-07-17T17:56:32.000Z","size":6228,"stargazers_count":814,"open_issues_count":46,"forks_count":48,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-11T14:16:51.832Z","etag":null,"topics":["debugger","debugging","python","tracer"],"latest_commit_sha":null,"homepage":"https://python-hunter.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ionelmc.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-16T18:03:16.000Z","updated_at":"2025-04-10T16:06:31.000Z","dependencies_parsed_at":"2023-09-23T17:12:19.029Z","dependency_job_id":"e311df45-4c87-4bd4-8dea-ab8a4752f9ea","html_url":"https://github.com/ionelmc/python-hunter","commit_stats":{"total_commits":1072,"total_committers":10,"mean_commits":107.2,"dds":"0.018656716417910446","last_synced_commit":"cfae650dd2b7a89e5bf9eb81b109f268397c45e9"},"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionelmc%2Fpython-hunter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionelmc%2Fpython-hunter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionelmc%2Fpython-hunter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionelmc%2Fpython-hunter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ionelmc","download_url":"https://codeload.github.com/ionelmc/python-hunter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254249197,"owners_count":22039029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugger","debugging","python","tracer"],"created_at":"2024-07-31T15:01:14.209Z","updated_at":"2025-05-15T00:07:45.220Z","avatar_url":"https://github.com/ionelmc.png","language":"Python","readme":"========\nOverview\n========\n\n.. start-badges\n\n.. list-table::\n    :stub-columns: 1\n\n    * - docs\n      - |docs|\n    * - tests\n      - |github-actions| |codecov|\n    * - package\n      - |version| |wheel| |supported-versions| |supported-implementations| |commits-since|\n.. |docs| image:: https://readthedocs.org/projects/python-hunter/badge/?style=flat\n    :target: https://readthedocs.org/projects/python-hunter/\n    :alt: Documentation Status\n\n.. |github-actions| image:: https://github.com/ionelmc/python-hunter/actions/workflows/github-actions.yml/badge.svg\n    :alt: GitHub Actions Build Status\n    :target: https://github.com/ionelmc/python-hunter/actions\n\n.. |codecov| image:: https://codecov.io/gh/ionelmc/python-hunter/branch/master/graphs/badge.svg?branch=master\n    :alt: Coverage Status\n    :target: https://app.codecov.io/github/ionelmc/python-hunter\n\n.. |version| image:: https://img.shields.io/pypi/v/hunter.svg\n    :alt: PyPI Package latest release\n    :target: https://pypi.org/project/hunter\n\n.. |wheel| image:: https://img.shields.io/pypi/wheel/hunter.svg\n    :alt: PyPI Wheel\n    :target: https://pypi.org/project/hunter\n\n.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/hunter.svg\n    :alt: Supported versions\n    :target: https://pypi.org/project/hunter\n\n.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/hunter.svg\n    :alt: Supported implementations\n    :target: https://pypi.org/project/hunter\n\n.. |commits-since| image:: https://img.shields.io/github/commits-since/ionelmc/python-hunter/v3.7.0.svg\n    :alt: Commits since latest release\n    :target: https://github.com/ionelmc/python-hunter/compare/v3.7.0...master\n\n\n\n.. end-badges\n\nHunter is a flexible code tracing toolkit, not for measuring coverage, but for debugging, logging, inspection and other\nnefarious purposes. It has a `simple Python API \u003chttps://python-hunter.readthedocs.io/en/latest/introduction.html\u003e`_,\na `convenient terminal API \u003cenvironment-variable-activation_\u003e`_ and\na `CLI tool to attach to processes \u003ctracing-processes_\u003e`_.\n\n* Free software: BSD 2-Clause License\n\nInstallation\n============\n\n::\n\n    pip install hunter\n\nDocumentation\n=============\n\n\nhttps://python-hunter.readthedocs.io/\n\nGetting started\n===============\n\nBasic use involves passing various filters to the ``trace`` option. An example:\n\n.. sourcecode:: python\n\n    import hunter\n    hunter.trace(module='posixpath', action=hunter.CallPrinter)\n\n    import os\n    os.path.join('a', 'b')\n\nThat would result in:\n\n.. sourcecode:: pycon\n\n    \u003e\u003e\u003e os.path.join('a', 'b')\n             /usr/lib/python3.6/posixpath.py:75    call      =\u003e join(a='a')\n             /usr/lib/python3.6/posixpath.py:80    line         a = os.fspath(a)\n             /usr/lib/python3.6/posixpath.py:81    line         sep = _get_sep(a)\n             /usr/lib/python3.6/posixpath.py:41    call         =\u003e _get_sep(path='a')\n             /usr/lib/python3.6/posixpath.py:42    line            if isinstance(path, bytes):\n             /usr/lib/python3.6/posixpath.py:45    line            return '/'\n             /usr/lib/python3.6/posixpath.py:45    return       \u003c= _get_sep: '/'\n             /usr/lib/python3.6/posixpath.py:82    line         path = a\n             /usr/lib/python3.6/posixpath.py:83    line         try:\n             /usr/lib/python3.6/posixpath.py:84    line         if not p:\n             /usr/lib/python3.6/posixpath.py:86    line         for b in map(os.fspath, p):\n             /usr/lib/python3.6/posixpath.py:87    line         if b.startswith(sep):\n             /usr/lib/python3.6/posixpath.py:89    line         elif not path or path.endswith(sep):\n             /usr/lib/python3.6/posixpath.py:92    line         path += sep + b\n             /usr/lib/python3.6/posixpath.py:86    line         for b in map(os.fspath, p):\n             /usr/lib/python3.6/posixpath.py:96    line         return path\n             /usr/lib/python3.6/posixpath.py:96    return    \u003c= join: 'a/b'\n    'a/b'\n\nIn a terminal it would look like:\n\n.. image:: https://raw.githubusercontent.com/ionelmc/python-hunter/master/docs/code-trace.png\n\n\nAnother useful scenario is to ignore all standard modules and force colors to make them stay even if the output is\nredirected to a file.\n\n.. sourcecode:: python\n\n    import hunter\n    hunter.trace(stdlib=False, action=hunter.CallPrinter(force_colors=True))\n\nActions\n-------\n\nOutput format can be controlled with \"actions\". There's an alternative ``CodePrinter`` action that doesn't handle\nnesting (it was the default action until Hunter 2.0).\n\nIf filters match then action will be run. Example:\n\n.. sourcecode:: python\n\n    import hunter\n    hunter.trace(module='posixpath', action=hunter.CodePrinter)\n\n    import os\n    os.path.join('a', 'b')\n\nThat would result in:\n\n.. sourcecode:: pycon\n\n    \u003e\u003e\u003e os.path.join('a', 'b')\n             /usr/lib/python3.6/posixpath.py:75    call      def join(a, *p):\n             /usr/lib/python3.6/posixpath.py:80    line          a = os.fspath(a)\n             /usr/lib/python3.6/posixpath.py:81    line          sep = _get_sep(a)\n             /usr/lib/python3.6/posixpath.py:41    call      def _get_sep(path):\n             /usr/lib/python3.6/posixpath.py:42    line          if isinstance(path, bytes):\n             /usr/lib/python3.6/posixpath.py:45    line              return '/'\n             /usr/lib/python3.6/posixpath.py:45    return            return '/'\n                                                   ...       return value: '/'\n             /usr/lib/python3.6/posixpath.py:82    line          path = a\n             /usr/lib/python3.6/posixpath.py:83    line          try:\n             /usr/lib/python3.6/posixpath.py:84    line              if not p:\n             /usr/lib/python3.6/posixpath.py:86    line              for b in map(os.fspath, p):\n             /usr/lib/python3.6/posixpath.py:87    line                  if b.startswith(sep):\n             /usr/lib/python3.6/posixpath.py:89    line                  elif not path or path.endswith(sep):\n             /usr/lib/python3.6/posixpath.py:92    line                      path += sep + b\n             /usr/lib/python3.6/posixpath.py:86    line              for b in map(os.fspath, p):\n             /usr/lib/python3.6/posixpath.py:96    line          return path\n             /usr/lib/python3.6/posixpath.py:96    return        return path\n                                                   ...       return value: 'a/b'\n    'a/b'\n\n- or in a terminal:\n\n.. image:: https://raw.githubusercontent.com/ionelmc/python-hunter/master/docs/simple-trace.png\n\n------\n\nAnother useful action is the ``VarsPrinter``:\n\n.. sourcecode:: python\n\n    import hunter\n    # note that this kind of invocation will also use the default `CallPrinter` action\n    hunter.trace(hunter.Q(module='posixpath', action=hunter.VarsPrinter('path')))\n\n    import os\n    os.path.join('a', 'b')\n\nThat would result in:\n\n.. sourcecode:: pycon\n\n    \u003e\u003e\u003e os.path.join('a', 'b')\n         /usr/lib/python3.6/posixpath.py:75    call      =\u003e join(a='a')\n         /usr/lib/python3.6/posixpath.py:80    line         a = os.fspath(a)\n         /usr/lib/python3.6/posixpath.py:81    line         sep = _get_sep(a)\n         /usr/lib/python3.6/posixpath.py:41    call      [path =\u003e 'a']\n         /usr/lib/python3.6/posixpath.py:41    call         =\u003e _get_sep(path='a')\n         /usr/lib/python3.6/posixpath.py:42    line      [path =\u003e 'a']\n         /usr/lib/python3.6/posixpath.py:42    line            if isinstance(path, bytes):\n         /usr/lib/python3.6/posixpath.py:45    line      [path =\u003e 'a']\n         /usr/lib/python3.6/posixpath.py:45    line            return '/'\n         /usr/lib/python3.6/posixpath.py:45    return    [path =\u003e 'a']\n         /usr/lib/python3.6/posixpath.py:45    return       \u003c= _get_sep: '/'\n         /usr/lib/python3.6/posixpath.py:82    line         path = a\n         /usr/lib/python3.6/posixpath.py:83    line      [path =\u003e 'a']\n         /usr/lib/python3.6/posixpath.py:83    line         try:\n         /usr/lib/python3.6/posixpath.py:84    line      [path =\u003e 'a']\n         /usr/lib/python3.6/posixpath.py:84    line         if not p:\n         /usr/lib/python3.6/posixpath.py:86    line      [path =\u003e 'a']\n         /usr/lib/python3.6/posixpath.py:86    line         for b in map(os.fspath, p):\n         /usr/lib/python3.6/posixpath.py:87    line      [path =\u003e 'a']\n         /usr/lib/python3.6/posixpath.py:87    line         if b.startswith(sep):\n         /usr/lib/python3.6/posixpath.py:89    line      [path =\u003e 'a']\n         /usr/lib/python3.6/posixpath.py:89    line         elif not path or path.endswith(sep):\n         /usr/lib/python3.6/posixpath.py:92    line      [path =\u003e 'a']\n         /usr/lib/python3.6/posixpath.py:92    line         path += sep + b\n         /usr/lib/python3.6/posixpath.py:86    line      [path =\u003e 'a/b']\n         /usr/lib/python3.6/posixpath.py:86    line         for b in map(os.fspath, p):\n         /usr/lib/python3.6/posixpath.py:96    line      [path =\u003e 'a/b']\n         /usr/lib/python3.6/posixpath.py:96    line         return path\n         /usr/lib/python3.6/posixpath.py:96    return    [path =\u003e 'a/b']\n         /usr/lib/python3.6/posixpath.py:96    return    \u003c= join: 'a/b'\n    'a/b'\n\nIn a terminal it would look like:\n\n.. image:: https://raw.githubusercontent.com/ionelmc/python-hunter/master/docs/vars-trace.png\n\n-----\n\nYou can give it a tree-like configuration where you can optionally configure specific actions for parts of the\ntree (like dumping variables or a pdb set_trace):\n\n.. sourcecode:: python\n\n    from hunter import trace, Q, Debugger\n    from pdb import Pdb\n\n    trace(\n        # drop into a Pdb session if ``foo.bar()`` is called\n        Q(module=\"foo\", function=\"bar\", kind=\"call\", action=Debugger(klass=Pdb))\n        |  # or\n        Q(\n            # show code that contains \"mumbo.jumbo\" on the current line\n            lambda event: event.locals.get(\"mumbo\") == \"jumbo\",\n            # and it's not in Python's stdlib\n            stdlib=False,\n            # and it contains \"mumbo\" on the current line\n            source__contains=\"mumbo\"\n        )\n    )\n\n    import foo\n    foo.func()\n\nWith a ``foo.py`` like this:\n\n.. sourcecode:: python\n\n    def bar():\n        execution_will_get_stopped  # cause we get a Pdb session here\n\n    def func():\n        mumbo = 1\n        mumbo = \"jumbo\"\n        print(\"not shown in trace\")\n        print(mumbo)\n        mumbo = 2\n        print(mumbo) # not shown in trace\n        bar()\n\n\nWe get:\n\n.. sourcecode:: pycon\n\n    \u003e\u003e\u003e foo.func()\n    not shown in trace\n        /home/ionel/osp/python-hunter/foo.py:8     line          print(mumbo)\n    jumbo\n        /home/ionel/osp/python-hunter/foo.py:9     line          mumbo = 2\n    2\n        /home/ionel/osp/python-hunter/foo.py:1     call      def bar():\n    \u003e /home/ionel/osp/python-hunter/foo.py(2)bar()\n    -\u003e execution_will_get_stopped  # cause we get a Pdb session here\n    (Pdb)\n\nIn a terminal it would look like:\n\n.. image:: https://raw.githubusercontent.com/ionelmc/python-hunter/master/docs/tree-trace.png\n\n.. _tracing-processes:\n\nTracing processes\n-----------------\n\nIn similar fashion to ``strace`` Hunter can trace other processes, eg::\n\n    hunter-trace --gdb -p 123\n\nIf you wanna play it safe (no messy GDB) then add this in your code::\n\n    from hunter import remote\n    remote.install()\n\nThen you can do::\n\n    hunter-trace -p 123\n\nSee `docs on the remote feature \u003chttps://python-hunter.readthedocs.org/en/latest/remote.html\u003e`_.\n\n**Note:** Windows ain't supported.\n\n.. _environment-variable-activation:\n\nEnvironment variable activation\n-------------------------------\n\nFor your convenience environment variable activation is available. Just run your app like this::\n\n\n    PYTHONHUNTER=\"module='os.path'\" python yourapp.py\n\nOn Windows you'd do something like::\n\n    set PYTHONHUNTER=module='os.path'\n    python yourapp.py\n\nThe activation works with a clever ``.pth`` file that checks for that env var presence and before your app runs does something\nlike this::\n\n    from hunter import *\n    trace(\u003cwhatever-you-had-in-the-PYTHONHUNTER-env-var\u003e)\n\nNote that Hunter is activated even if the env var is empty, eg: ``PYTHONHUNTER=\"\"``.\n\nEnvironment variable configuration\n``````````````````````````````````\n\nSometimes you always use the same options (like ``stdlib=False`` or ``force_colors=True``). To save typing you can\nset something like this in your environment::\n\n    PYTHONHUNTERCONFIG=\"stdlib=False,force_colors=True\"\n\nThis is the same as ``PYTHONHUNTER=\"stdlib=False,action=CallPrinter(force_colors=True)\"``.\n\nNotes:\n\n* Setting ``PYTHONHUNTERCONFIG`` alone doesn't activate hunter.\n* All the options for the builtin actions are supported.\n* Although using predicates is supported it can be problematic. Example of setup that won't trace anything::\n\n    PYTHONHUNTERCONFIG=\"Q(module_startswith='django')\"\n    PYTHONHUNTER=\"Q(module_startswith='celery')\"\n\n  which is the equivalent of::\n\n    PYTHONHUNTER=\"Q(module_startswith='django'),Q(module_startswith='celery')\"\n\n  which is the equivalent of::\n\n    PYTHONHUNTER=\"Q(module_startswith='django')\u0026Q(module_startswith='celery')\"\n\n\n\nFiltering DSL\n-------------\n\nHunter supports a flexible query DSL, see the `introduction\n\u003chttps://python-hunter.readthedocs.org/en/latest/introduction.html\u003e`_.\n\nDevelopment\n===========\n\nTo run the all tests run::\n\n    tox\n\nDesign notes\n============\n\nHunter doesn't do everything. As a design goal of this library some things are made intentionally austere and verbose (to avoid complexity,\nconfusion and inconsistency). This has few consequences:\n\n* There are `Operators \u003chttps://python-hunter.readthedocs.io/en/stable/introduction.html#operators\u003e`_ but there's no negation operator.\n  Instead you're expected to negate a Query object, eg: ``~Q(module='re')``.\n* There are no specialized operators or filters - all filters behave exactly the same. For example:\n\n  * No filter for packages. You're expected to filter by module with an operator.\n  * No filter for arguments, return values or variables. You're expected to write your own filter function and deal with the problems\n    of poking into objects.\n* Layering is minimal. There's are some `helpers \u003chttps://python-hunter.readthedocs.io/en/stable/reference.html#helpers\u003e`_ that do\n  some argument processing and conversions to save you some typing but that's about it.\n* The library doesn't try to hide the mechanics of tracing in Python - it's 1:1 regarding what Python sends to a trace function if you'd be\n  using `sys.settrace \u003chttps://docs.python.org/3/library/sys.html#sys.settrace\u003e`_.\n* Doesn't have any storage. You are expected to redirect output to a file.\n\nYou should look at it like it's a tool to help you understand and debug big applications, or a framework ridding you of the boring parts of\nsettrace, not something that helps you learn Python.\n\nFAQ\n===\n\nWhy not Smiley?\n---------------\n\nThere's some obvious overlap with `smiley \u003chttps://pypi.org/project/smiley/\u003e`_ but there are few fundamental differences:\n\n* Complexity. Smiley is simply over-engineered:\n\n  * It uses IPC and a SQL database.\n  * It has a webserver. Lots of dependencies.\n  * It uses threads. Side-effects and subtle bugs are introduced in your code.\n  * It records everything. Tries to dump any variable. Often fails and stops working.\n\n  Why do you need all that just to debug some stuff in a terminal? Simply put, it's a nice idea but the design choices work\n  against you when you're already neck-deep into debugging your own code. In my experience Smiley has been very buggy and\n  unreliable. Your mileage may vary of course.\n\n* Tracing long running code. This will make Smiley record lots of data, making it unusable.\n\n  Now because Smiley records everything, you'd think it's better suited for short programs. But alas, if your program runs\n  quickly then it's pointless to record the execution. You can just run it again.\n\n  It seems there's only one situation where it's reasonable to use Smiley: tracing io-bound apps remotely. Those apps don't\n  execute lots of code, they just wait on network so Smiley's storage won't blow out of proportion and tracing overhead might\n  be acceptable.\n* Use-cases. It seems to me Smiley's purpose is not really debugging code, but more of a \"non interactive monitoring\" tool.\n\nIn contrast, Hunter is very simple:\n\n* Few dependencies.\n* Low overhead (tracing/filtering code has an optional Cython extension).\n* No storage. This simplifies lots of things.\n\n  The only cost is that you might need to run the code multiple times to get the filtering/actions right. This means Hunter is\n  not really suited for \"post-mortem\" debugging. If you can't reproduce the problem anymore then Hunter won't be of much help.\n\nWhy not pytrace?\n----------------\n\n`Pytrace \u003chttps://pypi.org/project/pytrace/\u003e`_ is another tracer tool. It seems quite similar to Smiley - it uses a sqlite\ndatabase for the events, threads and IPC, thus it's reasonable to expect the same kind of problems.\n\nWhy not PySnooper or snoop?\n---------------------------\n\n`snoop \u003chttps://pypi.org/project/snoop/\u003e`_ is a refined version of `PySnooper \u003chttps://pypi.org/project/PySnooper/\u003e`_. Both are\nmore suited to tracing small programs or functions as the output is more verbose and less suited to the needs of tracing a big application\nwhere Hunter provides more flexible setup, filtering capabilities, speed and brevity.\n\nWhy not coverage?\n-----------------\n\nFor purposes of debugging `coverage \u003chttps://pypi.org/project/coverage/\u003e`_ is a great tool but only as far as \"debugging\nby looking at what code is (not) run\". Checking branch coverage is good but it will only get you as far.\n\nFrom the other perspective, you'd be wondering if you could use Hunter to measure coverage-like things. You could do it but\nfor that purpose Hunter is very \"rough\": it has no builtin storage. You'd have to implement your own storage. You can do it\nbut it wouldn't give you any advantage over making your own tracer if you don't need to \"pre-filter\" whatever you're\nrecording.\n\nIn other words, filtering events is the main selling point of Hunter - it's fast (cython implementation) and the query API is\nflexible enough.\n\nProjects using Hunter\n=====================\n\nNoteworthy usages or Hunter (submit a PR with your project if you built a tool that relies on hunter):\n\n* `Crunch-io/diagnose \u003chttps://github.com/Crunch-io/diagnose\u003e`_ - a runtime instrumentation library.\n* `talwrii/huntrace \u003chttps://github.com/talwrii/huntrace\u003e`_ - an alternative cli (similar to ltrace).\n* `anki-code/xunter \u003chttps://github.com/anki-code/xunter\u003e`_ - a profiling tool made specifically for `the xonsh shell \u003chttps://xon.sh\u003e`_.\n\nMore projects using it at https://github.com/ionelmc/python-hunter/network/dependents\n","funding_links":[],"categories":["Debugging Tools","Python","资源列表","调试工具","Debugging Tools [🔝](#readme)","Awesome Python"],"sub_categories":["调试工具","Other dialects and variants","Debugging Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionelmc%2Fpython-hunter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fionelmc%2Fpython-hunter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionelmc%2Fpython-hunter/lists"}