Doc/library/trace.rst

   1
   2 :mod:`trace` --- Trace or track Python statement execution
   3 ==========================================================
   4
   5 .. module:: trace
   6    :synopsis: Trace or track Python statement execution.
   7
   8
   9 The :mod:`trace` module allows you to trace program execution, generate
  10 annotated statement coverage listings, print caller/callee relationships and
  11 list functions executed during a program run.  It can be used in another program
  12 or from the command line.
  13
  14
  15 .. _trace-cli:
  16
  17 Command Line Usage
  18 ------------------
  19
  20 The :mod:`trace` module can be invoked from the command line.  It can be as
  21 simple as ::
  22
  23    python -m trace --count somefile.py ...
  24
  25 The above will generate annotated listings of all Python modules imported during
  26 the execution of :file:`somefile.py`.
  27
  28 The following command-line arguments are supported:
  29
  30 :option:`--trace`, :option:`-t`
  31    Display lines as they are executed.
  32
  33 :option:`--count`, :option:`-c`
  34    Produce a set of  annotated listing files upon program completion that shows how
  35    many times each statement was executed.
  36
  37 :option:`--report`, :option:`-r`
  38    Produce an annotated list from an earlier program run that used the
  39    :option:`--count` and :option:`--file` arguments.
  40
  41 :option:`--no-report`, :option:`-R`
  42    Do not generate annotated listings.  This is useful if you intend to make
  43    several runs with :option:`--count` then produce a single set of annotated
  44    listings at the end.
  45
  46 :option:`--listfuncs`, :option:`-l`
  47    List the functions executed by running the program.
  48
  49 :option:`--trackcalls`, :option:`-T`
  50    Generate calling relationships exposed by running the program.
  51
  52 :option:`--file`, :option:`-f`
  53    Name a file containing (or to contain) counts.
  54
  55 :option:`--coverdir`, :option:`-C`
  56    Name a directory in which to save annotated listing files.
  57
  58 :option:`--missing`, :option:`-m`
  59    When generating annotated listings, mark lines which were not executed with
  60    '``>>>>>>``'.
  61
  62 :option:`--summary`, :option:`-s`
  63    When using :option:`--count` or :option:`--report`, write a brief summary to
  64    stdout for each file processed.
  65
  66 :option:`--ignore-module`
  67    Accepts comma separated list of module names. Ignore each of the named
  68    module and its submodules (if it is a package).  May be given
  69    multiple times.
  70
  71 :option:`--ignore-dir`
  72    Ignore all modules and packages in the named directory and subdirectories
  73    (multiple directories can be joined by os.pathsep).  May be given multiple
  74    times.
  75
  76
  77 .. _trace-api:
  78
  79 Programming Interface
  80 ---------------------
  81
  82
  83 .. class:: Trace([count=1[, trace=1[, countfuncs=0[, countcallers=0[, ignoremods=()[, ignoredirs=()[, infile=None[, outfile=None[, timing=False]]]]]]]]])
  84
  85    Create an object to trace execution of a single statement or expression. All
  86    parameters are optional.  *count* enables counting of line numbers. *trace*
  87    enables line execution tracing.  *countfuncs* enables listing of the functions
  88    called during the run.  *countcallers* enables call relationship tracking.
  89    *ignoremods* is a list of modules or packages to ignore.  *ignoredirs* is a list
  90    of directories whose modules or packages should be ignored.  *infile* is the
  91    file from which to read stored count information.  *outfile* is a file in which
  92    to write updated count information. *timing* enables a timestamp relative
  93    to when tracing was started to be displayed.
  94
  95
  96 .. method:: Trace.run(cmd)
  97
  98    Run *cmd* under control of the Trace object with the current tracing parameters.
  99
 100
 101 .. method:: Trace.runctx(cmd[, globals=None[, locals=None]])
 102
 103    Run *cmd* under control of the Trace object with the current tracing parameters
 104    in the defined global and local environments.  If not defined, *globals* and
 105    *locals* default to empty dictionaries.
 106
 107
 108 .. method:: Trace.runfunc(func, *args, **kwds)
 109
 110    Call *func* with the given arguments under control of the :class:`Trace` object
 111    with the current tracing parameters.
 112
 113 This is a simple example showing the use of this module::
 114
 115    import sys
 116    import trace
 117
 118    # create a Trace object, telling it what to ignore, and whether to
 119    # do tracing or line-counting or both.
 120    tracer = trace.Trace(
 121        ignoredirs=[sys.prefix, sys.exec_prefix],
 122        trace=0,
 123        count=1)
 124
 125    # run the new command using the given tracer
 126    tracer.run('main()')
 127
 128    # make a report, placing output in /tmp
 129    r = tracer.results()
 130    r.write_results(show_missing=True, coverdir="/tmp")
 131