Initial revision

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.