27.6. trace — Trace or track Python statement execution (2024)

documentation.HELP! Python 3.7 Documentation

Python 3.7

previous page next page

Navigation

  • index
  • modules |
  • next |
  • previous |
  • 27.6. trace — Trace or track Python statement execution (1)
  • Python »
  • 3.7.0b1 Documentation »
  • The Python Standard Library »
  • 27. Debugging and Profiling »

Source code: Lib/trace.py

The trace module allows you to trace program execution, generateannotated statement coverage listings, print caller/callee relationships andlist functions executed during a program run. It can be used in another programor from the command line.

See also

Coverage.py
A popular third-party coverage tool that provides HTMLoutput along with advanced features such as branch coverage.

27.6.1. Command-Line Usage

The trace module can be invoked from the command line. It can be assimple as

python -m trace --count -C . somefile.py ...

The above will execute somefile.py and generate annotated listings ofall Python modules imported during the execution into the current directory.

--help

Display usage and exit.

--version

Display the version of the module and exit.

27.6.1.1. Main options

At least one of the following options must be specified when invokingtrace. The --listfuncs option is mutually exclusive withthe --trace and --count options. When--listfuncs is provided, neither --count nor--trace are accepted, and vice versa.

-c, --count

Produce a set of annotated listing files upon program completion that showshow many times each statement was executed. See also--coverdir, --file and--no-report below.

-t, --trace

Display lines as they are executed.

-l, --listfuncs

Display the functions executed by running the program.

-r, --report

Produce an annotated list from an earlier program run that used the--count and --file option. This does notexecute any code.

-T, --trackcalls

Display the calling relationships exposed by running the program.

27.6.1.2. Modifiers

-f, --file=<file>

Name of a file to accumulate counts over several tracing runs. Should beused with the --count option.

-C, --coverdir=<dir>

Directory where the report files go. The coverage report forpackage.module is written to file dir/package/module.cover.

-m, --missing

When generating annotated listings, mark lines which were not executed with>>>>>>.

-s, --summary

When using --count or --report, write a briefsummary to stdout for each file processed.

-R, --no-report

Do not generate annotated listings. This is useful if you intend to makeseveral runs with --count, and then produce a single set ofannotated listings at the end.

-g, --timing

Prefix each line with the time since the program started. Only used whiletracing.

27.6.1.3. Filters

These options may be repeated multiple times.

--ignore-module=<mod>

Ignore each of the given module names and its submodules (if it is apackage). The argument can be a list of names separated by a comma.

--ignore-dir=<dir>

Ignore all modules and packages in the named directory and subdirectories.The argument can be a list of directories separated by os.pathsep.

27.6.2. Programmatic Interface

class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

Create an object to trace execution of a single statement or expression. Allparameters are optional. count enables counting of line numbers. traceenables line execution tracing. countfuncs enables listing of thefunctions called during the run. countcallers enables call relationshiptracking. ignoremods is a list of modules or packages to ignore.ignoredirs is a list of directories whose modules or packages should beignored. infile is the name of the file from which to read stored countinformation. outfile is the name of the file in which to write updatedcount information. timing enables a timestamp relative to when tracing wasstarted to be displayed.

run(cmd)

Execute the command and gather statistics from the execution withthe current tracing parameters. cmd must be a string or code object,suitable for passing into exec().

runctx(cmd, globals=None, locals=None)

Execute the command and gather statistics from the execution with thecurrent tracing parameters, in the defined global and localenvironments. If not defined, globals and locals default to emptydictionaries.

runfunc(func, *args, **kwds)

Call func with the given arguments under control of the Traceobject with the current tracing parameters.

results()

Return a CoverageResults object that contains the cumulativeresults of all previous calls to run, runctx and runfuncfor the given Trace instance. Does not reset the accumulatedtrace results.

class trace.CoverageResults

A container for coverage results, created by Trace.results(). Shouldnot be created directly by the user.

update(other)

Merge in data from another CoverageResults object.

write_results(show_missing=True, summary=False, coverdir=None)

Write coverage results. Set show_missing to show lines that had nohits. Set summary to include in the output the coverage summary permodule. coverdir specifies the directory into which the coverageresult files will be output. If None, the results for each sourcefile are placed in its directory.

A simple example demonstrating the use of the programmatic interface:

import sysimport trace# create a Trace object, telling it what to ignore, and whether to# do tracing or line-counting or both.tracer = trace.Trace( ignoredirs=[sys.prefix, sys.exec_prefix], trace=0, count=1)# run the new command using the given tracertracer.run('main()')# make a report, placing output in the current directoryr = tracer.results()r.write_results(show_missing=True, coverdir=".")

Navigation

  • index
  • modules |
  • next |
  • previous |
  • 27.6. trace — Trace or track Python statement execution (2)
  • Python »
  • 3.7.0b1 Documentation »
  • The Python Standard Library »
  • 27. Debugging and Profiling »

© Copyright 2001-2018, Python Software Foundation.
The Python Software Foundation is a non-profit corporation.Please donate.
Last updated on Jan 31, 2018.Found a bug?
Created using Sphinx 1.6.6.

previous page start next page

27.6. trace — Trace or track Python statement execution (2024)
Top Articles
Latest Posts
Recommended Articles
Article information

Author: Rev. Leonie Wyman

Last Updated:

Views: 5663

Rating: 4.9 / 5 (59 voted)

Reviews: 90% of readers found this page helpful

Author information

Name: Rev. Leonie Wyman

Birthday: 1993-07-01

Address: Suite 763 6272 Lang Bypass, New Xochitlport, VT 72704-3308

Phone: +22014484519944

Job: Banking Officer

Hobby: Sailing, Gaming, Basketball, Calligraphy, Mycology, Astronomy, Juggling

Introduction: My name is Rev. Leonie Wyman, I am a colorful, tasty, splendid, fair, witty, gorgeous, splendid person who loves writing and wants to share my knowledge and understanding with you.