Doc/library/trace.rst

   1 :mod:`trace` --- Trace or track Python statement execution
   2 ==========================================================
   3
   4 .. module:: trace
   5    :synopsis: Trace or track Python statement execution.
   6
   7 **Source code:** :source:`Lib/trace.py`
   8
   9 --------------
  10
  11 The :mod:`trace` module allows you to trace program execution, generate
  12 annotated statement coverage listings, print caller/callee relationships and
  13 list functions executed during a program run.  It can be used in another program
  14 or from the command line.
  15
  16 .. _trace-cli:
  17
  18 Command-Line Usage
  19 ------------------
  20
  21 The :mod:`trace` module can be invoked from the command line.  It can be as
  22 simple as ::
  23
  24    python -m trace --count -C . somefile.py ...
  25
  26 The above will execute :file:`somefile.py` and generate annotated listings of
  27 all Python modules imported during the execution into the current directory.
  28
  29 .. program:: trace
  30
  31 .. cmdoption:: --help
  32
  33    Display usage and exit.
  34
  35 .. cmdoption:: --version
  36
  37    Display the version of the module and exit.
  38
  39 Main options
  40 ^^^^^^^^^^^^
  41
  42 At least one of the following options must be specified when invoking
  43 :mod:`trace`.  The :option:`--listfuncs <-l>` option is mutually exclusive with
  44 the :option:`--trace <-t>` and :option:`--counts <-c>` options . When
  45 :option:`--listfuncs <-l>` is provided, neither :option:`--counts <-c>` nor
  46 :option:`--trace <-t>` are accepted, and vice versa.
  47
  48 .. program:: trace
  49
  50 .. cmdoption:: -c, --count
  51
  52    Produce a set of annotated listing files upon program completion that shows
  53    how many times each statement was executed.  See also
  54    :option:`--coverdir <-C>`, :option:`--file <-f>` and
  55    :option:`--no-report <-R>` below.
  56
  57 .. cmdoption:: -t, --trace
  58
  59    Display lines as they are executed.
  60
  61 .. cmdoption:: -l, --listfuncs
  62
  63    Display the functions executed by running the program.
  64
  65 .. cmdoption:: -r, --report
  66
  67    Produce an annotated list from an earlier program run that used the
  68    :option:`--count <-c>` and :option:`--file <-f>` option.  This does not
  69    execute any code.
  70
  71 .. cmdoption:: -T, --trackcalls
  72
  73    Display the calling relationships exposed by running the program.
  74
  75 Modifiers
  76 ^^^^^^^^^
  77
  78 .. program:: trace
  79
  80 .. cmdoption:: -f, --file=<file>
  81
  82    Name of a file to accumulate counts over several tracing runs.  Should be
  83    used with the :option:`--count <-c>` option.
  84
  85 .. cmdoption:: -C, --coverdir=<dir>
  86
  87    Directory where the report files go.  The coverage report for
  88    ``package.module`` is written to file :file:`{dir}/{package}/{module}.cover`.
  89
  90 .. cmdoption:: -m, --missing
  91
  92    When generating annotated listings, mark lines which were not executed with
  93    ``>>>>>>``.
  94
  95 .. cmdoption:: -s, --summary
  96
  97    When using :option:`--count <-c>` or :option:`--report <-r>`, write a brief
  98    summary to stdout for each file processed.
  99
 100 .. cmdoption:: -R, --no-report
 101
 102    Do not generate annotated listings.  This is useful if you intend to make
 103    several runs with :option:`--count <-c>`, and then produce a single set of
 104    annotated listings at the end.
 105
 106 .. cmdoption:: -g, --timing
 107
 108    Prefix each line with the time since the program started.  Only used while
 109    tracing.
 110
 111 Filters
 112 ^^^^^^^
 113
 114 These options may be repeated multiple times.
 115
 116 .. program:: trace
 117
 118 .. cmdoption:: --ignore-module=<mod>
 119
 120    Ignore each of the given module names and its submodules (if it is a
 121    package).  The argument can be a list of names separated by a comma.
 122
 123 .. cmdoption:: --ignore-dir=<dir>
 124
 125    Ignore all modules and packages in the named directory and subdirectories.
 126    The argument can be a list of directories separated by :data:`os.pathsep`.
 127
 128 .. _trace-api:
 129
 130 Programmatic Interface
 131 ----------------------
 132
 133 .. class:: Trace([count=1[, trace=1[, countfuncs=0[, countcallers=0[, ignoremods=()[, ignoredirs=()[, infile=None[, outfile=None[, timing=False]]]]]]]]])
 134
 135    Create an object to trace execution of a single statement or expression.  All
 136    parameters are optional.  *count* enables counting of line numbers.  *trace*
 137    enables line execution tracing.  *countfuncs* enables listing of the
 138    functions called during the run.  *countcallers* enables call relationship
 139    tracking.  *ignoremods* is a list of modules or packages to ignore.
 140    *ignoredirs* is a list of directories whose modules or packages should be
 141    ignored.  *infile* is the name of the file from which to read stored count
 142    information.  *outfile* is the name of the file in which to write updated
 143    count information.  *timing* enables a timestamp relative to when tracing was
 144    started to be displayed.
 145
 146     .. method:: run(cmd)
 147
 148        Execute the command and gather statistics from the execution with
 149        the current tracing parameters.  *cmd* must be a string or code object,
 150        suitable for passing into :func:`exec`.
 151
 152     .. method:: runctx(cmd[, globals=None[, locals=None]])
 153
 154        Execute the command and gather statistics from the execution with the
 155        current tracing parameters, in the defined global and local
 156        environments.  If not defined, *globals* and *locals* default to empty
 157        dictionaries.
 158
 159     .. method:: runfunc(func, *args, **kwds)
 160
 161        Call *func* with the given arguments under control of the :class:`Trace`
 162        object with the current tracing parameters.
 163
 164     .. method:: results()
 165
 166        Return a :class:`CoverageResults` object that contains the cumulative
 167        results of all previous calls to ``run``, ``runctx`` and ``runfunc``
 168        for the given :class:`Trace` instance.  Does not reset the accumulated
 169        trace results.
 170
 171 .. class:: CoverageResults
 172
 173    A container for coverage results, created by :meth:`Trace.results`.  Should
 174    not be created directly by the user.
 175
 176     .. method:: update(other)
 177
 178        Merge in data from another :class:`CoverageResults` object.
 179
 180     .. method:: write_results([show_missing=True[, summary=False[, coverdir=None]]])
 181
 182        Write coverage results.  Set *show_missing* to show lines that had no
 183        hits.  Set *summary* to include in the output the coverage summary per
 184        module.  *coverdir* specifies the directory into which the coverage
 185        result files will be output.  If ``None``, the results for each source
 186        file are placed in its directory.
 187
 188 A simple example demonstrating the use of the programmatic interface::
 189
 190    import sys
 191    import trace
 192
 193    # create a Trace object, telling it what to ignore, and whether to
 194    # do tracing or line-counting or both.
 195    tracer = trace.Trace(
 196        ignoredirs=[sys.prefix, sys.exec_prefix],
 197        trace=0,
 198        count=1)
 199
 200    # run the new command using the given tracer
 201    tracer.run('main()')
 202
 203    # make a report, placing output in /tmp
 204    r = tracer.results()
 205    r.write_results(show_missing=True, coverdir="/tmp")
 206