pyprof2calltree / README.txt


Script to help visualize profiling data collected with the cProfile
python module with the kcachegrind_ (screenshots_) graphical calltree

This is a rebranding of the venerable script by David Allouche
et Al. It aims at making it easier to distribute (e.g. through pypi)
and behave more like the scripts of the debian kcachegrind-converters_
package. The final goal is to make it part of the official upstream
kdesdk_ package.

.. _kcachegrind:
.. _kcachegrind-converters:
.. _kdesdk:
.. _screenshots:


- David Allouche (original author)
- Jp Calderone
- Itamar Shtull-Trauring
- Johan Dahlin
- Olivier Grisel (repackaging and pstats support)

Command line usage

Upon installation you shoould have a `pyprof2calltree` script in your path::

  $ pyprof2calltree --help
  Usage: /usr/bin/pyprof2calltree [-k] [-o output_file_path] [-i input_file_path] [-r scriptfile [args]]

    -h, --help            show this help message and exit
    -o OUTFILE, --outfile=OUTFILE
                          Save calltree stats to <outfile>
    -i INFILE, --infile=INFILE
                          Read python stats from <infile>
    -r SCRIPT, --run-script=SCRIPT
                          Name of the python script to run to collect profiling
    -k, --kcachegrind     Run the kcachegrind tool on the converted data

Python shell usage

`pyprof2calltree` is also best used from an interactive python shell such as
the defaulft shell. For instance let use profile XML parsing::

  >>> from xml.etree import ElementTree
  >>> from cProfile import Profile
  >>> xml_content = '<a>\n' + '\t<b/><c><d>text</d></c>\n' * 100 + '</a>'
  >>> profiler = Profile()
  >>> profiler.runctx(
  ...     "ElementTree.fromstring(xml_content)",
  ...     locals(), globals())

  >>> from pyprof2calltree import convert, visualize
  >>> visualize(profiler.getstats())                            # run kcachegrind
  >>> convert(profiler.getstats(), 'profiling_results.kgrind')  # save for later

or with the ipython_::

  In [1]: %doctest_mode
  Exception reporting mode: Plain
  Doctest mode is: ON

  >>> from xml.etree import ElementTree
  >>> xml_content = '<a>\n' + '\t<b/><c><d>text</d></c>\n' * 100 + '</a>'
  >>> %prun -D /tmp/out.stats ElementTree.fromstring(xml_content)

  >>> from pyprof2calltree import convert, visualize
  >>> visualize('/tmp/out.stats')
  >>> convert('/tmp/out.stats', 'out.kgrind')

  >>> results = %prun -r ElementTree.fromstring(xml_content)
  >>> visualize(results)

.. _ipython:

Change log

 - 1.0 - 2008-10-16: initial release under the pyprof2calltree name