cpython/Doc/library/trace.rst

131 lines
4.3 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
:mod:`trace` --- Trace or track Python statement execution
==========================================================
.. module:: trace
:synopsis: Trace or track Python statement execution.
The :mod:`trace` module allows you to trace program execution, generate
annotated statement coverage listings, print caller/callee relationships and
list functions executed during a program run. It can be used in another program
or from the command line.
.. _trace-cli:
Command Line Usage
------------------
The :mod:`trace` module can be invoked from the command line. It can be as
simple as ::
python -m trace --count somefile.py ...
The above will generate annotated listings of all Python modules imported during
the execution of :file:`somefile.py`.
The following command-line arguments are supported:
:option:`--trace`, :option:`-t`
Display lines as they are executed.
:option:`--count`, :option:`-c`
Produce a set of annotated listing files upon program completion that shows how
many times each statement was executed.
:option:`--report`, :option:`-r`
Produce an annotated list from an earlier program run that used the
:option:`--count` and :option:`--file` arguments.
:option:`--no-report`, :option:`-R`
Do not generate annotated listings. This is useful if you intend to make
several runs with :option:`--count` then produce a single set of annotated
listings at the end.
:option:`--listfuncs`, :option:`-l`
List the functions executed by running the program.
:option:`--trackcalls`, :option:`-T`
Generate calling relationships exposed by running the program.
:option:`--file`, :option:`-f`
Name a file containing (or to contain) counts.
:option:`--coverdir`, :option:`-C`
Name a directory in which to save annotated listing files.
:option:`--missing`, :option:`-m`
When generating annotated listings, mark lines which were not executed with
'``>>>>>>``'.
:option:`--summary`, :option:`-s`
When using :option:`--count` or :option:`--report`, write a brief summary to
stdout for each file processed.
:option:`--ignore-module`
Merged revisions 60080-60089,60091-60093 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60080 | andrew.kuchling | 2008-01-19 17:26:13 +0100 (Sat, 19 Jan 2008) | 2 lines Patch #742598 from Michael Pomraning: add .timeout attribute to SocketServer that will call .handle_timeout() method when no requests are received within the timeout period. ........ r60081 | andrew.kuchling | 2008-01-19 17:34:09 +0100 (Sat, 19 Jan 2008) | 1 line Add item ........ r60082 | christian.heimes | 2008-01-19 17:39:27 +0100 (Sat, 19 Jan 2008) | 2 lines Disabled test_xmlrpc:test_404. It's causing lots of false alarms. I also disabled a test in test_ssl which requires network access to svn.python.org. This fixes a bug Skip has reported a while ago. ........ r60083 | georg.brandl | 2008-01-19 18:38:53 +0100 (Sat, 19 Jan 2008) | 2 lines Clarify thread.join() docs. #1873. ........ r60084 | georg.brandl | 2008-01-19 19:02:46 +0100 (Sat, 19 Jan 2008) | 2 lines #1782: don't leak in error case in PyModule_AddXxxConstant. Patch by Hrvoje Nik?\197?\161i?\196?\135. ........ r60085 | andrew.kuchling | 2008-01-19 19:08:52 +0100 (Sat, 19 Jan 2008) | 1 line Sort two names into position ........ r60086 | andrew.kuchling | 2008-01-19 19:18:41 +0100 (Sat, 19 Jan 2008) | 2 lines Patch #976880: add mmap .rfind() method, and 'end' paramter to .find(). Contributed by John Lenton. ........ r60087 | facundo.batista | 2008-01-19 19:38:19 +0100 (Sat, 19 Jan 2008) | 5 lines Fix #1693149. Now you can pass several modules separated by coma to trace.py in the same --ignore-module option. Thanks Raghuram Devarakonda. ........ r60088 | facundo.batista | 2008-01-19 19:45:46 +0100 (Sat, 19 Jan 2008) | 3 lines Comment in NEWS regarding the change in trace.py. ........ r60089 | skip.montanaro | 2008-01-19 19:47:24 +0100 (Sat, 19 Jan 2008) | 2 lines missing from r60088 checkin. ........ r60091 | andrew.kuchling | 2008-01-19 20:14:05 +0100 (Sat, 19 Jan 2008) | 1 line Add item ........ r60092 | georg.brandl | 2008-01-19 20:27:05 +0100 (Sat, 19 Jan 2008) | 4 lines Fix #1679: "0x" was taken as a valid integer literal. Fixes the tokenizer, tokenize.py and int() to reject this. Patches by Malte Helmert. ........ r60093 | georg.brandl | 2008-01-19 20:48:19 +0100 (Sat, 19 Jan 2008) | 3 lines Fix #1146: TextWrap vs words 1-character shorter than the width. Patch by Quentin Gallet-Gilles. ........
2008-01-19 16:08:23 -04:00
Accepts comma separated list of module names. Ignore each of the named
2009-01-03 17:18:54 -04:00
module and its submodules (if it is a package). May be given
2007-08-15 11:28:22 -03:00
multiple times.
:option:`--ignore-dir`
Merged revisions 60080-60089,60091-60093 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60080 | andrew.kuchling | 2008-01-19 17:26:13 +0100 (Sat, 19 Jan 2008) | 2 lines Patch #742598 from Michael Pomraning: add .timeout attribute to SocketServer that will call .handle_timeout() method when no requests are received within the timeout period. ........ r60081 | andrew.kuchling | 2008-01-19 17:34:09 +0100 (Sat, 19 Jan 2008) | 1 line Add item ........ r60082 | christian.heimes | 2008-01-19 17:39:27 +0100 (Sat, 19 Jan 2008) | 2 lines Disabled test_xmlrpc:test_404. It's causing lots of false alarms. I also disabled a test in test_ssl which requires network access to svn.python.org. This fixes a bug Skip has reported a while ago. ........ r60083 | georg.brandl | 2008-01-19 18:38:53 +0100 (Sat, 19 Jan 2008) | 2 lines Clarify thread.join() docs. #1873. ........ r60084 | georg.brandl | 2008-01-19 19:02:46 +0100 (Sat, 19 Jan 2008) | 2 lines #1782: don't leak in error case in PyModule_AddXxxConstant. Patch by Hrvoje Nik?\197?\161i?\196?\135. ........ r60085 | andrew.kuchling | 2008-01-19 19:08:52 +0100 (Sat, 19 Jan 2008) | 1 line Sort two names into position ........ r60086 | andrew.kuchling | 2008-01-19 19:18:41 +0100 (Sat, 19 Jan 2008) | 2 lines Patch #976880: add mmap .rfind() method, and 'end' paramter to .find(). Contributed by John Lenton. ........ r60087 | facundo.batista | 2008-01-19 19:38:19 +0100 (Sat, 19 Jan 2008) | 5 lines Fix #1693149. Now you can pass several modules separated by coma to trace.py in the same --ignore-module option. Thanks Raghuram Devarakonda. ........ r60088 | facundo.batista | 2008-01-19 19:45:46 +0100 (Sat, 19 Jan 2008) | 3 lines Comment in NEWS regarding the change in trace.py. ........ r60089 | skip.montanaro | 2008-01-19 19:47:24 +0100 (Sat, 19 Jan 2008) | 2 lines missing from r60088 checkin. ........ r60091 | andrew.kuchling | 2008-01-19 20:14:05 +0100 (Sat, 19 Jan 2008) | 1 line Add item ........ r60092 | georg.brandl | 2008-01-19 20:27:05 +0100 (Sat, 19 Jan 2008) | 4 lines Fix #1679: "0x" was taken as a valid integer literal. Fixes the tokenizer, tokenize.py and int() to reject this. Patches by Malte Helmert. ........ r60093 | georg.brandl | 2008-01-19 20:48:19 +0100 (Sat, 19 Jan 2008) | 3 lines Fix #1146: TextWrap vs words 1-character shorter than the width. Patch by Quentin Gallet-Gilles. ........
2008-01-19 16:08:23 -04:00
Ignore all modules and packages in the named directory and subdirectories
(multiple directories can be joined by os.pathsep). May be given multiple
2009-01-03 17:18:54 -04:00
times.
2007-08-15 11:28:22 -03:00
.. _trace-api:
Programming Interface
---------------------
.. class:: Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)
2007-08-15 11:28:22 -03:00
Create an object to trace execution of a single statement or expression. All
parameters are optional. *count* enables counting of line numbers. *trace*
enables line execution tracing. *countfuncs* enables listing of the functions
called during the run. *countcallers* enables call relationship tracking.
*ignoremods* is a list of modules or packages to ignore. *ignoredirs* is a list
of directories whose modules or packages should be ignored. *infile* is the
file from which to read stored count information. *outfile* is a file in which
Merged revisions 61038,61042-61045,61047,61050,61053,61055-61056,61061-61062,61066,61068,61070,61081-61095 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r61081 | neal.norwitz | 2008-02-26 09:04:59 +0100 (Tue, 26 Feb 2008) | 7 lines Speed up this test by about 99%. Remove sleeps and replace with events. (This may fail on some slow platforms, but we can fix those cases which should be relatively isolated and easier to find now.) Move two test cases that didn't require a server to be started to a separate TestCase. These tests were taking 3 seconds which is what the timeout was set to. ........ r61082 | christian.heimes | 2008-02-26 09:18:11 +0100 (Tue, 26 Feb 2008) | 1 line The contains function raised a gcc warning. The new code is copied straight from py3k. ........ r61084 | neal.norwitz | 2008-02-26 09:21:28 +0100 (Tue, 26 Feb 2008) | 3 lines Add a timing flag to Trace so you can see where slowness occurs like waiting for socket timeouts in test_smtplib :-). ........ r61086 | christian.heimes | 2008-02-26 18:23:51 +0100 (Tue, 26 Feb 2008) | 3 lines Patch #1691070 from Roger Upole: Speed up PyArg_ParseTupleAndKeywords() and improve error msg My tests don't show the promised speed up of 10%. The code is as fast as the old code for simple cases and slightly faster for complex cases with several of args and kwargs. But the patch simplifies the code, too. ........ r61087 | georg.brandl | 2008-02-26 20:13:45 +0100 (Tue, 26 Feb 2008) | 2 lines #2194: fix some typos. ........ r61088 | raymond.hettinger | 2008-02-27 00:40:50 +0100 (Wed, 27 Feb 2008) | 1 line Add itertools.combinations(). ........ r61089 | raymond.hettinger | 2008-02-27 02:08:04 +0100 (Wed, 27 Feb 2008) | 1 line One too many decrefs. ........ r61090 | raymond.hettinger | 2008-02-27 02:08:30 +0100 (Wed, 27 Feb 2008) | 1 line Larger test range ........ r61091 | raymond.hettinger | 2008-02-27 02:44:34 +0100 (Wed, 27 Feb 2008) | 1 line Simply the sample code for combinations(). ........
2008-02-28 07:19:05 -04:00
to write updated count information. *timing* enables a timestamp relative
to when tracing was started to be displayed.
2007-08-15 11:28:22 -03:00
.. method:: Trace.run(cmd)
Run *cmd* under control of the Trace object with the current tracing parameters.
.. method:: Trace.runctx(cmd, globals=None, locals=None)
2007-08-15 11:28:22 -03:00
Run *cmd* under control of the Trace object with the current tracing parameters
in the defined global and local environments. If not defined, *globals* and
*locals* default to empty dictionaries.
.. method:: Trace.runfunc(func, *args, **kwds)
Call *func* with the given arguments under control of the :class:`Trace` object
with the current tracing parameters.
This is a simple example showing the use of this module::
import sys
import 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 tracer
tracer.run('main()')
# make a report, placing output in /tmp
r = tracer.results()
r.write_results(show_missing=True, coverdir="/tmp")