mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-15 08:01:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Use nested method directives, rewrap long lines, fix whitespace.

Browse source
This commit is contained in:
Éric Araujo 2010-12-15 19:30:15 +00:00
parent e434b3b681
commit 67f0b6c5f2
1 changed files with 56 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

106
Doc/library/trace.rst
View file

@ -25,8 +25,8 @@ simple as ::
python -m trace --count -C . somefile.py ... python -m trace --count -C . somefile.py ...
The above will execute :file:`somefile.py` and generate annotated listings of all The above will execute :file:`somefile.py` and generate annotated listings of
Python modules imported during the execution into the current directory. all Python modules imported during the execution into the current directory.
.. program:: trace .. program:: trace
@ -41,19 +41,19 @@ Python modules imported during the execution into the current directory.
Main options Main options
^^^^^^^^^^^^ ^^^^^^^^^^^^
At least one of the following options must be specified when invoking :mod:`trace`. At least one of the following options must be specified when invoking
The :option:`--listfuncs <-l>` option is mutually exclusive with the :mod:`trace`. The :option:`--listfuncs <-l>` option is mutually exclusive with
:option:`--trace <-t>` and :option:`--counts <-c>` options . When :option:`--listfuncs <-l>` the :option:`--trace <-t>` and :option:`--counts <-c>` options . When
is provided, neither :option:`--counts <-c>` nor :option:`--trace <-t>` are accepted, :option:`--listfuncs <-l>` is provided, neither :option:`--counts <-c>` nor
and vice versa. :option:`--trace <-t>` are accepted, and vice versa.
.. program:: trace .. program:: trace
.. cmdoption:: -c, --count .. cmdoption:: -c, --count
Produce a set of annotated listing files upon program completion that shows Produce a set of annotated listing files upon program completion that shows
how many times each statement was executed. how many times each statement was executed. See also
See also :option:`--coverdir <-C>`, :option:`--file <-f>`, :option:`--coverdir <-C>`, :option:`--file <-f>` and
:option:`--no-report <-R>` below. :option:`--no-report <-R>` below.
.. cmdoption:: -t, --trace .. cmdoption:: -t, --trace
@ -67,7 +67,8 @@ and vice versa.
.. cmdoption:: -r, --report .. cmdoption:: -r, --report
Produce an annotated list from an earlier program run that used the Produce an annotated list from an earlier program run that used the
:option:`--count <-c>` and :option:`--file <-f>` option. Do not execute any code. :option:`--count <-c>` and :option:`--file <-f>` option. This does not
execute any code.
.. cmdoption:: -T, --trackcalls .. cmdoption:: -T, --trackcalls
@ -80,12 +81,12 @@ Modifiers
.. cmdoption:: -f, --file=<file> .. cmdoption:: -f, --file=<file>
Name of a file to accumulate counts over several tracing runs. Should be used Name of a file to accumulate counts over several tracing runs. Should be
with the :option:`--count <-c>` option. used with the :option:`--count <-c>` option.
.. cmdoption:: -C, --coverdir=<dir> .. cmdoption:: -C, --coverdir=<dir>
Directory where the report files go. The coverage report for Directory where the report files go. The coverage report for
``package.module`` is written to file :file:`{dir}/{package}/{module}.cover`. ``package.module`` is written to file :file:`{dir}/{package}/{module}.cover`.
.. cmdoption:: -m, --missing .. cmdoption:: -m, --missing
@ -106,7 +107,7 @@ Modifiers
.. cmdoption:: -g, --timing .. cmdoption:: -g, --timing
Prefix each line with the time since the program started. Only used while Prefix each line with the time since the program started. Only used while
tracing. tracing.
Filters Filters
@ -118,8 +119,8 @@ These options may be repeated multiple times.
.. cmdoption:: --ignore-module=<mod> .. cmdoption:: --ignore-module=<mod>
Ignore each of the given module names and its submodules (if it is a package). Ignore each of the given module names and its submodules (if it is a
The argument can be a list of names separated by a comma. package). The argument can be a list of names separated by a comma.
.. cmdoption:: --ignore-dir=<dir> .. cmdoption:: --ignore-dir=<dir>
@ -131,56 +132,61 @@ These options may be repeated multiple times.
Programmatic Interface Programmatic Interface
---------------------- ----------------------
.. class:: Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False) .. class:: 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. All Create an object to trace execution of a single statement or expression. All
parameters are optional. *count* enables counting of line numbers. *trace* parameters are optional. *count* enables counting of line numbers. *trace*
enables line execution tracing. *countfuncs* enables listing of the functions enables line execution tracing. *countfuncs* enables listing of the
called during the run. *countcallers* enables call relationship tracking. functions called during the run. *countcallers* enables call relationship
*ignoremods* is a list of modules or packages to ignore. *ignoredirs* is a list tracking. *ignoremods* is a list of modules or packages to ignore.
of directories whose modules or packages should be ignored. *infile* is the *ignoredirs* is a list of directories whose modules or packages should be
name of the file from which to read stored count information. *outfile* is ignored. *infile* is the name of the file from which to read stored count
the name of the file in which to write updated count information. *timing* information. *outfile* is the name of the file in which to write updated
enables a timestamp relative to when tracing was started to be displayed. count information. *timing* enables a timestamp relative to when tracing was
started to be displayed.
.. method:: Trace.run(cmd) .. method:: run(cmd)
Execute the command and gather statistics from the execution with Execute the command and gather statistics from the execution with
the current tracing parameters. the current tracing parameters. *cmd* must be a string or code object,
*cmd* must be a string or code object, suitable for passing into :func:`exec`. suitable for passing into :func:`exec`.
.. method:: Trace.runctx(cmd, globals=None, locals=None) .. method:: runctx(cmd, globals=None, locals=None)
Execute the command and gather statistics from the execution with Execute the command and gather statistics from the execution with the
the current tracing parameters, in the defined global and local environments. current tracing parameters, in the defined global and local
If not defined, *globals* and *locals* default to empty dictionaries. environments. If not defined, *globals* and *locals* default to empty
dictionaries.
.. method:: Trace.runfunc(func, *args, **kwds) .. method:: runfunc(func, *args, **kwds)
Call *func* with the given arguments under control of the :class:`Trace` object Call *func* with the given arguments under control of the :class:`Trace`
with the current tracing parameters. object with the current tracing parameters.
.. method:: Trace.results() .. method:: results()
Return a :class:`CoverageResults` object that contains the cumulative results Return a :class:`CoverageResults` object that contains the cumulative
of all previous calls to ``run``, ``runctx`` and ``runfunc`` for the given results of all previous calls to ``run``, ``runctx`` and ``runfunc``
:class:`Trace` instance. Does not reset the accumulated trace results. for the given :class:`Trace` instance. Does not reset the accumulated
trace results.
.. class:: CoverageResults .. class:: CoverageResults
A container for coverage results, created by :meth:`Trace.results`. Should not A container for coverage results, created by :meth:`Trace.results`. Should
be created directly by the user. not be created directly by the user.
.. method:: CoverageResults.update(other) .. method:: update(other)
Merge in data from another :class:`CoverageResults` object. Merge in data from another :class:`CoverageResults` object.
.. method:: CoverageResults.write_results(show_missing=True, summary=False, coverdir=None) .. method:: write_results(show_missing=True, summary=False, coverdir=None)
Write coverage results. Set *show_missing* to show lines that had no hits. Write coverage results. Set *show_missing* to show lines that had no
Set *summary* to include in the output the coverage summary per module. *coverdir* hits. Set *summary* to include in the output the coverage summary per
specifies the directory into which the coverage result files will be output. module. *coverdir* specifies the directory into which the coverage
If ``None``, the results for each source file are placed in its directory. result files will be output. If ``None``, the results for each source
file are placed in its directory.
A simple example demonstrating the use of the programmatic interface:: A simple example demonstrating the use of the programmatic interface::