1 2:mod:`hotshot` --- High performance logging profiler 3==================================================== 4 5.. module:: hotshot 6 :synopsis: High performance logging profiler, mostly written in C. 7.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 8.. sectionauthor:: Anthony Baxter <anthony@interlink.com.au> 9 10 11.. versionadded:: 2.2 12 13This module provides a nicer interface to the :mod:`_hotshot` C module. Hotshot 14is a replacement for the existing :mod:`profile` module. As it's written mostly 15in C, it should result in a much smaller performance impact than the existing 16:mod:`profile` module. 17 18.. note:: 19 20 The :mod:`hotshot` module focuses on minimizing the overhead while profiling, at 21 the expense of long data post-processing times. For common usage it is 22 recommended to use :mod:`cProfile` instead. :mod:`hotshot` is not maintained and 23 might be removed from the standard library in the future. 24 25.. versionchanged:: 2.5 26 The results should be more meaningful than in the past: the timing core 27 contained a critical bug. 28 29.. note:: 30 31 The :mod:`hotshot` profiler does not yet work well with threads. It is useful to 32 use an unthreaded script to run the profiler over the code you're interested in 33 measuring if at all possible. 34 35 36.. class:: Profile(logfile[, lineevents[, linetimings]]) 37 38 The profiler object. The argument *logfile* is the name of a log file to use for 39 logged profile data. The argument *lineevents* specifies whether to generate 40 events for every source line, or just on function call/return. It defaults to 41 ``0`` (only log function call/return). The argument *linetimings* specifies 42 whether to record timing information. It defaults to ``1`` (store timing 43 information). 44 45 46.. _hotshot-objects: 47 48Profile Objects 49--------------- 50 51Profile objects have the following methods: 52 53 54.. method:: Profile.addinfo(key, value) 55 56 Add an arbitrary labelled value to the profile output. 57 58 59.. method:: Profile.close() 60 61 Close the logfile and terminate the profiler. 62 63 64.. method:: Profile.fileno() 65 66 Return the file descriptor of the profiler's log file. 67 68 69.. method:: Profile.run(cmd) 70 71 Profile an :keyword:`exec`\ -compatible string in the script environment. The 72 globals from the :mod:`__main__` module are used as both the globals and locals 73 for the script. 74 75 76.. method:: Profile.runcall(func, *args, **keywords) 77 78 Profile a single call of a callable. Additional positional and keyword arguments 79 may be passed along; the result of the call is returned, and exceptions are 80 allowed to propagate cleanly, while ensuring that profiling is disabled on the 81 way out. 82 83 84.. method:: Profile.runctx(cmd, globals, locals) 85 86 Evaluate an :keyword:`exec`\ -compatible string in a specific environment. The 87 string is compiled before profiling begins. 88 89 90.. method:: Profile.start() 91 92 Start the profiler. 93 94 95.. method:: Profile.stop() 96 97 Stop the profiler. 98 99 100Using hotshot data 101------------------ 102 103.. module:: hotshot.stats 104 :synopsis: Statistical analysis for Hotshot 105 106 107.. versionadded:: 2.2 108 109This module loads hotshot profiling data into the standard :mod:`pstats` Stats 110objects. 111 112 113.. function:: load(filename) 114 115 Load hotshot data from *filename*. Returns an instance of the 116 :class:`pstats.Stats` class. 117 118 119.. seealso:: 120 121 Module :mod:`profile` 122 The :mod:`profile` module's :class:`Stats` class 123 124 125.. _hotshot-example: 126 127Example Usage 128------------- 129 130Note that this example runs the Python "benchmark" pystones. It can take some 131time to run, and will produce large output files. :: 132 133 >>> import hotshot, hotshot.stats, test.pystone 134 >>> prof = hotshot.Profile("stones.prof") 135 >>> benchtime, stones = prof.runcall(test.pystone.pystones) 136 >>> prof.close() 137 >>> stats = hotshot.stats.load("stones.prof") 138 >>> stats.strip_dirs() 139 >>> stats.sort_stats('time', 'calls') 140 >>> stats.print_stats(20) 141 850004 function calls in 10.090 CPU seconds 142 143 Ordered by: internal time, call count 144 145 ncalls tottime percall cumtime percall filename:lineno(function) 146 1 3.295 3.295 10.090 10.090 pystone.py:79(Proc0) 147 150000 1.315 0.000 1.315 0.000 pystone.py:203(Proc7) 148 50000 1.313 0.000 1.463 0.000 pystone.py:229(Func2) 149 . 150 . 151 . 152 153