home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / pyth_os2.zip / python-1.0.2 / Lib / profile.doc < prev    next >
Text File  |  1993-12-29  |  3KB  |  75 lines
  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.
  75.