This module prints `function trace` to stdout from the moment it is called::

    import xtrace
    xtrace.start()
    ...
    xtrace.stop()

It is also possible to call `xtrace` as module from the command line::

    python -m xtrace <script.py> [param] ...

or use as a standalone script::

    python xtrace.py <script.py> [param] ...


The output format is inspired by Xdebug function traces and will likely to
merge with it http://xdebug.org/docs/execution_trace to be compatible with
PHP inspection tools. But I didn't have enough time to polish it, so feel
free to send a patch if you know how to bring them closer.

This code is released into public domain. Enjoy!


History
=======

  * 0.5 - fix major crash when function in executed script tried to read
    variables in its global scope
  * 0.4 - added beep function which beeps in DEBUG mode when excited
  * 0.3 - fix AttributeError when running from console (issue #2)
  * 0.2 - added version info, support running from command line, moved main
    functions into a class to isolate used variables in local namespace
  * 0.1 - initial release


Credits
=======
Amaury Forgeot d'Arc, for valuable insight into Python internals


Debugging
=========
To see various internal events that `xtrace` produces on top of standard
data provided by Python, enable DEBUG option::

    import xtrace
    xtrace.DEBUG = True

This will call `beep` functiton for every interesting event. Feel free to
override it (monkeypatch) with your own to filter messages, forward, etc. 


Known Python Bugs
=================
Python bugs affecting trace output in unexpected way:

http://bugs.python.org/issue15005 (Python 2, Linux only)
 - captured stdout from subprocess call becomes corrupted
   under a trace function that prints to the screen
