line_profiler and kernprof 1.0b2

[Robert Kern]

line_profiler is a module for doing line-by-line profiling of functions.

kernprof is a convenient script for running either line_profiler or the standard
library's cProfile module.

  Download: http://pypi.python.org/pypi/line_profiler
  Docs:     http://packages.python.org/line_profiler
  HG Repo:  http://www.enthought.com/~rkern/cgi-bin/hgwebdir.cgi/line_profiler/

  Just kernprof: http://packages.python.org/line_profiler/kernprof.py


line_profiler
-------------

line_profiler will time individual statements in specified functions. For example,
here are the results of profiling a single function from a decorated version of
the pystone.py benchmark (the first two lines are output from pystone.py)::

     Pystone(1.1) time for 50000 passes = 2.48
     This machine benchmarks at 20161.3 pystones/second
     Wrote profile results to pystone.py.lprof
     Timer unit: 1e-06 s

     File: pystone.py
     Function: Proc2 at line 149
     Total time: 0.606656 s

     Line #      Hits         Time  Per Hit   % Time  Line Contents
     ==============================================================
        149                                           @profile
        150                                           def Proc2(IntParIO):
        151     50000        82003      1.6     13.5      IntLoc = IntParIO + 10
        152     50000        63162      1.3     10.4      while 1:
        153     50000        69065      1.4     11.4          if Char1Glob == 'A':
        154     50000        66354      1.3     10.9              IntLoc = IntLoc - 1
        155     50000        67263      1.3     11.1              IntParIO = IntLoc - IntGlob
        156     50000        65494      1.3     10.8              EnumLoc = Ident1
        157     50000        68001      1.4     11.2          if EnumLoc == Ident1:
        158     50000        63739      1.3     10.5              break
        159     50000        61575      1.2     10.1      return IntParIO


kernprof
--------

kernprof will run your scripts under one of cProfiler or line_profiler in a
variety of convenient ways. It has a few main features:

     * Encapsulation of profiling concerns. You do not have to modify your script
       in order to initiate profiling and save the results.

     * Robust script execution. Many scripts require things like __name__,
       __file__, and sys.path to be set relative to it. A naive approach at
       encapsulation would just use execfile(), but many scripts which rely on
       that information will fail. kernprof will set those variables correctly
       before executing the script.

     * Easy executable location. If you are profiling an application installed on
       your PATH, you can just give the name of the executable. If kernprof does
       not find the given script in the current directory, it will search your
       PATH for it.

     * Inserting the profiler into __builtins__. Sometimes, you just want to
       profile a small part of your code. With the [-b/--builtin] argument, the
       Profiler will be instantiated and inserted into your __builtins__ with the
       name "profile". It may be used as a decorator on the targeted functions.

     * Pre-profiling setup. With the [-s/--setup] option, you can provide
       a script which will be executed without profiling before executing the
       main script. This is typically useful for cases where imports of large
       libraries like wxPython or VTK are interfering with your results.

The results of profile script_to_profile.py will be written to
script_to_profile.py.prof by default. It will be a typical marshalled file that
can be read with pstats.Stats(). They may be interactively viewed with the
command::

     $ python -m pstats script_to_profile.py.prof

Such files may also be viewed with graphical tools like kcachegrind_ through the
converter program pyprof2calltree_ or RunSnakeRun_.

.. _kcachegrind: http://kcachegrind.sourceforge.net/html/Home.html
.. _pyprof2calltree: http://pypi.python.org/pypi/pyprof2calltree/
.. _RunSnakeRun: http://www.vrplumber.com/programming/runsnakerun/

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
  that is made terrible by our own mad attempt to interpret it as though it had
  an underlying truth."
   -- Umberto Eco