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    Ignore the named module and its submodules (if it is a package).  May be given
  68    multiple times.
  69
  70 :option:`--ignore-dir`
  71    Ignore all modules and packages in the named directory and subdirectories.  May
  72    be given multiple times.
  73
  74
  75 .. _trace-api:
  76
  77 Programming Interface
  78 ---------------------
  79
  80
  81 .. class:: Trace([count=1[, trace=1[, countfuncs=0[, countcallers=0[, ignoremods=()[, ignoredirs=()[, infile=None[, outfile=None]]]]]]]])
  82
  83    Create an object to trace execution of a single statement or expression. All
  84    parameters are optional.  *count* enables counting of line numbers. *trace*
  85    enables line execution tracing.  *countfuncs* enables listing of the functions
  86    called during the run.  *countcallers* enables call relationship tracking.
  87    *ignoremods* is a list of modules or packages to ignore.  *ignoredirs* is a list
  88    of directories whose modules or packages should be ignored.  *infile* is the
  89    file from which to read stored count information.  *outfile* is a file in which
  90    to write updated count information.
  91
  92
  93 .. method:: Trace.run(cmd)
  94
  95    Run *cmd* under control of the Trace object with the current tracing parameters.
  96
  97
  98 .. method:: Trace.runctx(cmd[, globals=None[, locals=None]])
  99
 100    Run *cmd* under control of the Trace object with the current tracing parameters
 101    in the defined global and local environments.  If not defined, *globals* and
 102    *locals* default to empty dictionaries.
 103
 104
 105 .. method:: Trace.runfunc(func, *args, **kwds)
 106
 107    Call *func* with the given arguments under control of the :class:`Trace` object
 108    with the current tracing parameters.
 109
 110 This is a simple example showing the use of this module::
 111
 112    import sys
 113    import trace
 114
 115    # create a Trace object, telling it what to ignore, and whether to
 116    # do tracing or line-counting or both.
 117    tracer = trace.Trace(
 118        ignoredirs=[sys.prefix, sys.exec_prefix],
 119        trace=0,
 120        count=1)
 121
 122    # run the new command using the given tracer
 123    tracer.run('main()')
 124
 125    # make a report, placing output in /tmp
 126    r = tracer.results()
 127    r.write_results(show_missing=True, coverdir="/tmp")
 128