/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
  9The :mod:`trace` module allows you to trace program execution, generate
 10annotated statement coverage listings, print caller/callee relationships and
 11list functions executed during a program run.  It can be used in another program
 12or from the command line.
 13
 14
 15.. _trace-cli:
 16
 17Command Line Usage
 18------------------
 19
 20The :mod:`trace` module can be invoked from the command line.  It can be as
 21simple as ::
 22
 23   python -m trace --count somefile.py ...
 24
 25The above will generate annotated listings of all Python modules imported during
 26the execution of :file:`somefile.py`.
 27
 28The 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
 79Programming 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
113This 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