Guido van Rossum | 8176258 | 1992-04-21 15:36:23 +0000 | [diff] [blame^] | 1 | The Python Profiler |
| 2 | |
| 3 | To use the profiler in its simplest form: |
| 4 | |
| 5 | >>> import profile |
| 6 | >>> profile.run(statement) |
| 7 | |
| 8 | This will execute the statement and print statistics. To get more |
| 9 | information out of the profiler, use: |
| 10 | |
| 11 | >>> import profile |
| 12 | >>> profile.run(statement, dump_file) |
| 13 | |
| 14 | where dump_file is a string naming a file to which the (binary) |
| 15 | profile statistics is to be dumped. The binary format is a dump of a |
| 16 | dictionary. The key is the function name in the format described |
| 17 | above; the value is a tuple consisting of, in order, number of calls, |
| 18 | total time spent in the function, total time spent in the function and |
| 19 | all functions called from it, a list of functions called by this |
| 20 | function, and a list of functions that called this function. The dump |
| 21 | can be read back using the following code: |
| 22 | |
| 23 | >>> import marshal |
| 24 | >>> f = open(dump_file, 'r') |
| 25 | >>> dict = marshal.load(f) |
| 26 | >>> f.close() |
| 27 | |
| 28 | An easier way of doing this is by using the class `Stats' which is |
| 29 | also defined in profile: |
| 30 | |
| 31 | >>> import profile |
| 32 | >>> s = profile.Stats().init(dump_file) |
| 33 | |
| 34 | The following methods are defined for instances of `Stats': |
| 35 | |
| 36 | print_stats() -- Print the statistics in a format similar to |
| 37 | the format profile.run() uses. |
| 38 | print_callers() -- For each function, print all functions |
| 39 | which it calls. |
| 40 | print_callees() -- For each function, print all functions from |
| 41 | which it is called. |
| 42 | sort_stats(n) -- Sort the statistics for subsequent |
| 43 | printing. The argument determines on which |
| 44 | field the output should be sorted. |
| 45 | Possibilities are |
| 46 | -1 function name |
| 47 | 0 number of calls |
| 48 | 1 total time spent in a function |
| 49 | 2 total time spent in a function |
| 50 | plus all functions it called |
| 51 | strip_dirs() -- Strip the directory names off of the file |
| 52 | names which are part of the function names. |
| 53 | This undoes the effect of sort_stats(), but |
| 54 | a subsequent sort_stats() does work. |
| 55 | |
| 56 | The methods sort_stats and strip_dirs may change in the future. |
| 57 | |
| 58 | Output of profile.run(statement) and of the print_stats() method of |
| 59 | the `Stats' class consists of the following fields. |
| 60 | |
| 61 | Number of times the function was called. |
| 62 | Total time spent in the function. |
| 63 | Mean time per function call (second field divided by first). |
| 64 | Total time spent in the function and all functions it called, |
| 65 | recursively. |
| 66 | Mean time time spent in the function and all functions it |
| 67 | called (fourth field divided by first). |
| 68 | Name of the function in the format |
| 69 | <file name>:<line number>(<function name>) |
| 70 | |
| 71 | The output of the print_callers and print_callees methods consists of |
| 72 | the name of the function and the names of all function it called or |
| 73 | was called from. The latter names are followed by a parenthesised |
| 74 | number which is the number of calls for this function. |