Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="prev" href="module-profile.html" /> | |
13 | <link rel="parent" href="module-profile.html" /> | |
14 | <link rel="next" href="profile-limits.html" /> | |
15 | <meta name='aesop' content='information' /> | |
16 | <title>10.5.1 The Stats Class </title> | |
17 | </head> | |
18 | <body> | |
19 | <DIV CLASS="navigation"> | |
20 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
21 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
22 | <tr> | |
23 | <td class='online-navigation'><a rel="prev" title="10.5 Reference Manual" | |
24 | href="module-profile.html"><img src='../icons/previous.png' | |
25 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
26 | <td class='online-navigation'><a rel="parent" title="10.5 Reference Manual" | |
27 | href="module-profile.html"><img src='../icons/up.png' | |
28 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
29 | <td class='online-navigation'><a rel="next" title="10.6 Limitations" | |
30 | href="profile-limits.html"><img src='../icons/next.png' | |
31 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
32 | <td align="center" width="100%">Python Library Reference</td> | |
33 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
34 | href="contents.html"><img src='../icons/contents.png' | |
35 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
36 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
37 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
38 | <td class='online-navigation'><a rel="index" title="Index" | |
39 | href="genindex.html"><img src='../icons/index.png' | |
40 | border='0' height='32' alt='Index' width='32' /></A></td> | |
41 | </tr></table> | |
42 | <div class='online-navigation'> | |
43 | <b class="navlabel">Previous:</b> | |
44 | <a class="sectref" rel="prev" href="module-profile.html">10.5 Reference Manual</A> | |
45 | <b class="navlabel">Up:</b> | |
46 | <a class="sectref" rel="parent" href="module-profile.html">10.5 Reference Manual</A> | |
47 | <b class="navlabel">Next:</b> | |
48 | <a class="sectref" rel="next" href="profile-limits.html">10.6 Limitations</A> | |
49 | </div> | |
50 | <hr /></div> | |
51 | </DIV> | |
52 | <!--End of Navigation Panel--> | |
53 | ||
54 | <H2><A NAME="SECTION0012510000000000000000"></A><A NAME="profile-stats"></A> | |
55 | <BR> | |
56 | 10.5.1 The <tt class="class">Stats</tt> Class | |
57 | </H2> | |
58 | ||
59 | <P> | |
60 | <tt class="class">Stats</tt> objects have the following methods: | |
61 | ||
62 | <P> | |
63 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
64 | <td><nobr><b><tt id='l2h-3112' xml:id='l2h-3112' class="method">strip_dirs</tt></b>(</nobr></td> | |
65 | <td><var></var>)</td></tr></table></dt> | |
66 | <dd> | |
67 | This method for the <tt class="class">Stats</tt> class removes all leading path | |
68 | information from file names. It is very useful in reducing the size | |
69 | of the printout to fit within (close to) 80 columns. This method | |
70 | modifies the object, and the stripped information is lost. After | |
71 | performing a strip operation, the object is considered to have its | |
72 | entries in a ``random'' order, as it was just after object | |
73 | initialization and loading. If <tt class="method">strip_dirs()</tt> causes two | |
74 | function names to be indistinguishable (they are on the same | |
75 | line of the same filename, and have the same function name), then the | |
76 | statistics for these two entries are accumulated into a single entry. | |
77 | </dl> | |
78 | ||
79 | <P> | |
80 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
81 | <td><nobr><b><tt id='l2h-3113' xml:id='l2h-3113' class="method">add</tt></b>(</nobr></td> | |
82 | <td><var>filename</var><big>[</big><var>, ...</var><big>]</big><var></var>)</td></tr></table></dt> | |
83 | <dd> | |
84 | This method of the <tt class="class">Stats</tt> class accumulates additional | |
85 | profiling information into the current profiling object. Its | |
86 | arguments should refer to filenames created by the corresponding | |
87 | version of <tt class="function">profile.run()</tt>. Statistics for identically named | |
88 | (re: file, line, name) functions are automatically accumulated into | |
89 | single function statistics. | |
90 | </dl> | |
91 | ||
92 | <P> | |
93 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
94 | <td><nobr><b><tt id='l2h-3114' xml:id='l2h-3114' class="method">dump_stats</tt></b>(</nobr></td> | |
95 | <td><var>filename</var>)</td></tr></table></dt> | |
96 | <dd> | |
97 | Save the data loaded into the <tt class="class">Stats</tt> object to a file named | |
98 | <var>filename</var>. The file is created if it does not exist, and is | |
99 | overwritten if it already exists. This is equivalent to the method of | |
100 | the same name on the <tt class="class">profile.Profile</tt> class. | |
101 | ||
102 | <span class="versionnote">New in version 2.3.</span> | |
103 | ||
104 | </dl> | |
105 | ||
106 | <P> | |
107 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
108 | <td><nobr><b><tt id='l2h-3115' xml:id='l2h-3115' class="method">sort_stats</tt></b>(</nobr></td> | |
109 | <td><var>key</var><big>[</big><var>, ...</var><big>]</big><var></var>)</td></tr></table></dt> | |
110 | <dd> | |
111 | This method modifies the <tt class="class">Stats</tt> object by sorting it according | |
112 | to the supplied criteria. The argument is typically a string | |
113 | identifying the basis of a sort (example: <code>'time'</code> or | |
114 | <code>'name'</code>). | |
115 | ||
116 | <P> | |
117 | When more than one key is provided, then additional keys are used as | |
118 | secondary criteria when there is equality in all keys selected | |
119 | before them. For example, <code>sort_stats('name', 'file')</code> will sort | |
120 | all the entries according to their function name, and resolve all ties | |
121 | (identical function names) by sorting by file name. | |
122 | ||
123 | <P> | |
124 | Abbreviations can be used for any key names, as long as the | |
125 | abbreviation is unambiguous. The following are the keys currently | |
126 | defined: | |
127 | ||
128 | <P> | |
129 | <div class="center"><table class="realtable"> | |
130 | <thead> | |
131 | <tr> | |
132 | <th class="left" >Valid Arg</th> | |
133 | <th class="left" >Meaning</th> | |
134 | </tr> | |
135 | </thead> | |
136 | <tbody> | |
137 | <tr><td class="left" valign="baseline"><code>'calls'</code></td> | |
138 | <td class="left" >call count</td></tr> | |
139 | <tr><td class="left" valign="baseline"><code>'cumulative'</code></td> | |
140 | <td class="left" >cumulative time</td></tr> | |
141 | <tr><td class="left" valign="baseline"><code>'file'</code></td> | |
142 | <td class="left" >file name</td></tr> | |
143 | <tr><td class="left" valign="baseline"><code>'module'</code></td> | |
144 | <td class="left" >file name</td></tr> | |
145 | <tr><td class="left" valign="baseline"><code>'pcalls'</code></td> | |
146 | <td class="left" >primitive call count</td></tr> | |
147 | <tr><td class="left" valign="baseline"><code>'line'</code></td> | |
148 | <td class="left" >line number</td></tr> | |
149 | <tr><td class="left" valign="baseline"><code>'name'</code></td> | |
150 | <td class="left" >function name</td></tr> | |
151 | <tr><td class="left" valign="baseline"><code>'nfl'</code></td> | |
152 | <td class="left" >name/file/line</td></tr> | |
153 | <tr><td class="left" valign="baseline"><code>'stdname'</code></td> | |
154 | <td class="left" >standard name</td></tr> | |
155 | <tr><td class="left" valign="baseline"><code>'time'</code></td> | |
156 | <td class="left" >internal time</td></tr></tbody> | |
157 | </table></div> | |
158 | ||
159 | <P> | |
160 | Note that all sorts on statistics are in descending order (placing | |
161 | most time consuming items first), where as name, file, and line number | |
162 | searches are in ascending order (alphabetical). The subtle | |
163 | distinction between <code>'nfl'</code> and <code>'stdname'</code> is that the | |
164 | standard name is a sort of the name as printed, which means that the | |
165 | embedded line numbers get compared in an odd way. For example, lines | |
166 | 3, 20, and 40 would (if the file names were the same) appear in the | |
167 | string order 20, 3 and 40. In contrast, <code>'nfl'</code> does a numeric | |
168 | compare of the line numbers. In fact, <code>sort_stats('nfl')</code> is the | |
169 | same as <code>sort_stats('name', 'file', 'line')</code>. | |
170 | ||
171 | <P> | |
172 | For compatibility with the old profiler, the numeric arguments | |
173 | <code>-1</code>, <code>0</code>, <code>1</code>, and <code>2</code> are permitted. They are | |
174 | interpreted as <code>'stdname'</code>, <code>'calls'</code>, <code>'time'</code>, and | |
175 | <code>'cumulative'</code> respectively. If this old style format (numeric) | |
176 | is used, only one sort key (the numeric key) will be used, and | |
177 | additional arguments will be silently ignored. | |
178 | </dl> | |
179 | ||
180 | <P> | |
181 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
182 | <td><nobr><b><tt id='l2h-3116' xml:id='l2h-3116' class="method">reverse_order</tt></b>(</nobr></td> | |
183 | <td><var></var>)</td></tr></table></dt> | |
184 | <dd> | |
185 | This method for the <tt class="class">Stats</tt> class reverses the ordering of the basic | |
186 | list within the object. This method is provided primarily for | |
187 | compatibility with the old profiler. Its utility is questionable | |
188 | now that ascending vs descending order is properly selected based on | |
189 | the sort key of choice. | |
190 | </dl> | |
191 | ||
192 | <P> | |
193 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
194 | <td><nobr><b><tt id='l2h-3117' xml:id='l2h-3117' class="method">print_stats</tt></b>(</nobr></td> | |
195 | <td><var></var><big>[</big><var>restriction, ...</var><big>]</big><var></var>)</td></tr></table></dt> | |
196 | <dd> | |
197 | This method for the <tt class="class">Stats</tt> class prints out a report as described | |
198 | in the <tt class="function">profile.run()</tt> definition. | |
199 | ||
200 | <P> | |
201 | The order of the printing is based on the last <tt class="method">sort_stats()</tt> | |
202 | operation done on the object (subject to caveats in <tt class="method">add()</tt> and | |
203 | <tt class="method">strip_dirs()</tt>). | |
204 | ||
205 | <P> | |
206 | The arguments provided (if any) can be used to limit the list down to | |
207 | the significant entries. Initially, the list is taken to be the | |
208 | complete set of profiled functions. Each restriction is either an | |
209 | integer (to select a count of lines), or a decimal fraction between | |
210 | 0.0 and 1.0 inclusive (to select a percentage of lines), or a regular | |
211 | expression (to pattern match the standard name that is printed; as of | |
212 | Python 1.5b1, this uses the Perl-style regular expression syntax | |
213 | defined by the <tt class="module"><a href="module-re.html">re</a></tt> module). If several restrictions are | |
214 | provided, then they are applied sequentially. For example: | |
215 | ||
216 | <P> | |
217 | <div class="verbatim"><pre> | |
218 | print_stats(.1, 'foo:') | |
219 | </pre></div> | |
220 | ||
221 | <P> | |
222 | would first limit the printing to first 10% of list, and then only | |
223 | print functions that were part of filename <span class="file">.*foo:</span>. In | |
224 | contrast, the command: | |
225 | ||
226 | <P> | |
227 | <div class="verbatim"><pre> | |
228 | print_stats('foo:', .1) | |
229 | </pre></div> | |
230 | ||
231 | <P> | |
232 | would limit the list to all functions having file names <span class="file">.*foo:</span>, | |
233 | and then proceed to only print the first 10% of them. | |
234 | </dl> | |
235 | ||
236 | <P> | |
237 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
238 | <td><nobr><b><tt id='l2h-3118' xml:id='l2h-3118' class="method">print_callers</tt></b>(</nobr></td> | |
239 | <td><var></var><big>[</big><var>restriction, ...</var><big>]</big><var></var>)</td></tr></table></dt> | |
240 | <dd> | |
241 | This method for the <tt class="class">Stats</tt> class prints a list of all functions | |
242 | that called each function in the profiled database. The ordering is | |
243 | identical to that provided by <tt class="method">print_stats()</tt>, and the definition | |
244 | of the restricting argument is also identical. For convenience, a | |
245 | number is shown in parentheses after each caller to show how many | |
246 | times this specific call was made. A second non-parenthesized number | |
247 | is the cumulative time spent in the function at the right. | |
248 | </dl> | |
249 | ||
250 | <P> | |
251 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
252 | <td><nobr><b><tt id='l2h-3119' xml:id='l2h-3119' class="method">print_callees</tt></b>(</nobr></td> | |
253 | <td><var></var><big>[</big><var>restriction, ...</var><big>]</big><var></var>)</td></tr></table></dt> | |
254 | <dd> | |
255 | This method for the <tt class="class">Stats</tt> class prints a list of all function | |
256 | that were called by the indicated function. Aside from this reversal | |
257 | of direction of calls (re: called vs was called by), the arguments and | |
258 | ordering are identical to the <tt class="method">print_callers()</tt> method. | |
259 | </dl> | |
260 | ||
261 | <P> | |
262 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
263 | <td><nobr><b><tt id='l2h-3120' xml:id='l2h-3120' class="method">ignore</tt></b>(</nobr></td> | |
264 | <td><var></var>)</td></tr></table></dt> | |
265 | <dd> | |
266 | <div class="versionnote"><b>Deprecated since release 1.5.1.</b> | |
267 | This is not needed in modern versions of | |
268 | Python.<A NAME="tex2html51" | |
269 | HREF="#foot46380"><SUP>10.2</SUP></A></div><p></p> | |
270 | </dl> | |
271 | ||
272 | <P> | |
273 | <BR><HR><H4>Footnotes</H4> | |
274 | <DL> | |
275 | <DT><A NAME="foot46380">... | |
276 | Python.</A><A | |
277 | href="profile-stats.html#tex2html51"><SUP>10.2</SUP></A></DT> | |
278 | <DD> | |
279 | This was once necessary, when Python would print any unused expression | |
280 | result that was not <code>None</code>. The method is still defined for | |
281 | backward compatibility. | |
282 | ||
283 | </DD> | |
284 | </DL> | |
285 | <DIV CLASS="navigation"> | |
286 | <div class='online-navigation'> | |
287 | <p></p><hr /> | |
288 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
289 | <tr> | |
290 | <td class='online-navigation'><a rel="prev" title="10.5 Reference Manual" | |
291 | href="module-profile.html"><img src='../icons/previous.png' | |
292 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
293 | <td class='online-navigation'><a rel="parent" title="10.5 Reference Manual" | |
294 | href="module-profile.html"><img src='../icons/up.png' | |
295 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
296 | <td class='online-navigation'><a rel="next" title="10.6 Limitations" | |
297 | href="profile-limits.html"><img src='../icons/next.png' | |
298 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
299 | <td align="center" width="100%">Python Library Reference</td> | |
300 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
301 | href="contents.html"><img src='../icons/contents.png' | |
302 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
303 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
304 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
305 | <td class='online-navigation'><a rel="index" title="Index" | |
306 | href="genindex.html"><img src='../icons/index.png' | |
307 | border='0' height='32' alt='Index' width='32' /></A></td> | |
308 | </tr></table> | |
309 | <div class='online-navigation'> | |
310 | <b class="navlabel">Previous:</b> | |
311 | <a class="sectref" rel="prev" href="module-profile.html">10.5 Reference Manual</A> | |
312 | <b class="navlabel">Up:</b> | |
313 | <a class="sectref" rel="parent" href="module-profile.html">10.5 Reference Manual</A> | |
314 | <b class="navlabel">Next:</b> | |
315 | <a class="sectref" rel="next" href="profile-limits.html">10.6 Limitations</A> | |
316 | </div> | |
317 | </div> | |
318 | <hr /> | |
319 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
320 | </DIV> | |
321 | <!--End of Navigation Panel--> | |
322 | <ADDRESS> | |
323 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
324 | </ADDRESS> | |
325 | </BODY> | |
326 | </HTML> |