summaryrefslogtreecommitdiffstats
path: root/Lib/profile.doc
diff options
context:
space:
mode:
authorGuido van Rossum <guido@python.org>1992-04-21 15:36:23 (GMT)
committerGuido van Rossum <guido@python.org>1992-04-21 15:36:23 (GMT)
commit8176258421df1e5fa8a521930178f6af8c93b52c (patch)
tree92ddfb5d372c663537633507972ec118a19af897 /Lib/profile.doc
parent6f1f39188c54b89bac8b0e3b91529ad733929bc4 (diff)
downloadcpython-8176258421df1e5fa8a521930178f6af8c93b52c.zip
cpython-8176258421df1e5fa8a521930178f6af8c93b52c.tar.gz
cpython-8176258421df1e5fa8a521930178f6af8c93b52c.tar.bz2
Initial revision
Diffstat (limited to 'Lib/profile.doc')
-rw-r--r--Lib/profile.doc74
1 files changed, 74 insertions, 0 deletions
diff --git a/Lib/profile.doc b/Lib/profile.doc
new file mode 100644
index 0000000..753d159
--- /dev/null
+++ b/Lib/profile.doc
@@ -0,0 +1,74 @@
+The Python Profiler
+
+To use the profiler in its simplest form:
+
+ >>> import profile
+ >>> profile.run(statement)
+
+This will execute the statement and print statistics. To get more
+information out of the profiler, use:
+
+ >>> import profile
+ >>> profile.run(statement, dump_file)
+
+where dump_file is a string naming a file to which the (binary)
+profile statistics is to be dumped. The binary format is a dump of a
+dictionary. The key is the function name in the format described
+above; the value is a tuple consisting of, in order, number of calls,
+total time spent in the function, total time spent in the function and
+all functions called from it, a list of functions called by this
+function, and a list of functions that called this function. The dump
+can be read back using the following code:
+
+ >>> import marshal
+ >>> f = open(dump_file, 'r')
+ >>> dict = marshal.load(f)
+ >>> f.close()
+
+An easier way of doing this is by using the class `Stats' which is
+also defined in profile:
+
+ >>> import profile
+ >>> s = profile.Stats().init(dump_file)
+
+The following methods are defined for instances of `Stats':
+
+ print_stats() -- Print the statistics in a format similar to
+ the format profile.run() uses.
+ print_callers() -- For each function, print all functions
+ which it calls.
+ print_callees() -- For each function, print all functions from
+ which it is called.
+ sort_stats(n) -- Sort the statistics for subsequent
+ printing. The argument determines on which
+ field the output should be sorted.
+ Possibilities are
+ -1 function name
+ 0 number of calls
+ 1 total time spent in a function
+ 2 total time spent in a function
+ plus all functions it called
+ strip_dirs() -- Strip the directory names off of the file
+ names which are part of the function names.
+ This undoes the effect of sort_stats(), but
+ a subsequent sort_stats() does work.
+
+The methods sort_stats and strip_dirs may change in the future.
+
+Output of profile.run(statement) and of the print_stats() method of
+the `Stats' class consists of the following fields.
+
+ Number of times the function was called.
+ Total time spent in the function.
+ Mean time per function call (second field divided by first).
+ Total time spent in the function and all functions it called,
+ recursively.
+ Mean time time spent in the function and all functions it
+ called (fourth field divided by first).
+ Name of the function in the format
+ <file name>:<line number>(<function name>)
+
+The output of the print_callers and print_callees methods consists of
+the name of the function and the names of all function it called or
+was called from. The latter names are followed by a parenthesised
+number which is the number of calls for this function.