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. <[email protected]>
8.. sectionauthor:: Anthony Baxter <[email protected]>
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