1013 lines
34 KiB
Python
1013 lines
34 KiB
Python
|
# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
|
||
|
|
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
|
||
|
|
|
||
|
|
"""Command-line support for coverage.py."""
|
||
|
|
|
||
|
|
from __future__ import annotations
|
||
|
|
|
||
|
|
import glob
|
||
|
|
import optparse # pylint: disable=deprecated-module
|
||
|
|
import os
|
||
|
|
import os.path
|
||
|
|
import shlex
|
||
|
|
import sys
|
||
|
|
import textwrap
|
||
|
|
import traceback
|
||
|
|
|
||
|
|
from typing import cast, Any, List, NoReturn, Optional, Tuple
|
||
|
|
|
||
|
|
import coverage
|
||
|
|
from coverage import Coverage
|
||
|
|
from coverage import env
|
||
|
|
from coverage.collector import HAS_CTRACER
|
||
|
|
from coverage.config import CoverageConfig
|
||
|
|
from coverage.control import DEFAULT_DATAFILE
|
||
|
|
from coverage.data import combinable_files, debug_data_file
|
||
|
|
from coverage.debug import info_header, short_stack, write_formatted_info
|
||
|
|
from coverage.exceptions import _BaseCoverageException, _ExceptionDuringRun, NoSource
|
||
|
|
from coverage.execfile import PyRunner
|
||
|
|
from coverage.results import Numbers, should_fail_under
|
||
|
|
from coverage.version import __url__
|
||
|
|
|
||
|
|
# When adding to this file, alphabetization is important. Look for
|
||
|
|
# "alphabetize" comments throughout.
|
||
|
|
|
||
|
|
class Opts:
|
||
|
|
"""A namespace class for individual options we'll build parsers from."""
|
||
|
|
|
||
|
|
# Keep these entries alphabetized (roughly) by the option name as it
|
||
|
|
# appears on the command line.
|
||
|
|
|
||
|
|
append = optparse.make_option(
|
||
|
|
"-a", "--append", action="store_true",
|
||
|
|
help="Append coverage data to .coverage, otherwise it starts clean each time.",
|
||
|
|
)
|
||
|
|
keep = optparse.make_option(
|
||
|
|
"", "--keep", action="store_true",
|
||
|
|
help="Keep original coverage files, otherwise they are deleted.",
|
||
|
|
)
|
||
|
|
branch = optparse.make_option(
|
||
|
|
"", "--branch", action="store_true",
|
||
|
|
help="Measure branch coverage in addition to statement coverage.",
|
||
|
|
)
|
||
|
|
concurrency = optparse.make_option(
|
||
|
|
"", "--concurrency", action="store", metavar="LIBS",
|
||
|
|
help=(
|
||
|
|
"Properly measure code using a concurrency library. " +
|
||
|
|
"Valid values are: {}, or a comma-list of them."
|
||
|
|
).format(", ".join(sorted(CoverageConfig.CONCURRENCY_CHOICES))),
|
||
|
|
)
|
||
|
|
context = optparse.make_option(
|
||
|
|
"", "--context", action="store", metavar="LABEL",
|
||
|
|
help="The context label to record for this coverage run.",
|
||
|
|
)
|
||
|
|
contexts = optparse.make_option(
|
||
|
|
"", "--contexts", action="store", metavar="REGEX1,REGEX2,...",
|
||
|
|
help=(
|
||
|
|
"Only display data from lines covered in the given contexts. " +
|
||
|
|
"Accepts Python regexes, which must be quoted."
|
||
|
|
),
|
||
|
|
)
|
||
|
|
combine_datafile = optparse.make_option(
|
||
|
|
"", "--data-file", action="store", metavar="DATAFILE",
|
||
|
|
help=(
|
||
|
|
"Base name of the data files to operate on. " +
|
||
|
|
"Defaults to '.coverage'. [env: COVERAGE_FILE]"
|
||
|
|
),
|
||
|
|
)
|
||
|
|
input_datafile = optparse.make_option(
|
||
|
|
"", "--data-file", action="store", metavar="INFILE",
|
||
|
|
help=(
|
||
|
|
"Read coverage data for report generation from this file. " +
|
||
|
|
"Defaults to '.coverage'. [env: COVERAGE_FILE]"
|
||
|
|
),
|
||
|
|
)
|
||
|
|
output_datafile = optparse.make_option(
|
||
|
|
"", "--data-file", action="store", metavar="OUTFILE",
|
||
|
|
help=(
|
||
|
|
"Write the recorded coverage data to this file. " +
|
||
|
|
"Defaults to '.coverage'. [env: COVERAGE_FILE]"
|
||
|
|
),
|
||
|
|
)
|
||
|
|
debug = optparse.make_option(
|
||
|
|
"", "--debug", action="store", metavar="OPTS",
|
||
|
|
help="Debug options, separated by commas. [env: COVERAGE_DEBUG]",
|
||
|
|
)
|
||
|
|
directory = optparse.make_option(
|
||
|
|
"-d", "--directory", action="store", metavar="DIR",
|
||
|
|
help="Write the output files to DIR.",
|
||
|
|
)
|
||
|
|
fail_under = optparse.make_option(
|
||
|
|
"", "--fail-under", action="store", metavar="MIN", type="float",
|
||
|
|
help="Exit with a status of 2 if the total coverage is less than MIN.",
|
||
|
|
)
|
||
|
|
format = optparse.make_option(
|
||
|
|
"", "--format", action="store", metavar="FORMAT",
|
||
|
|
help="Output format, either text (default), markdown, or total.",
|
||
|
|
)
|
||
|
|
help = optparse.make_option(
|
||
|
|
"-h", "--help", action="store_true",
|
||
|
|
help="Get help on this command.",
|
||
|
|
)
|
||
|
|
ignore_errors = optparse.make_option(
|
||
|
|
"-i", "--ignore-errors", action="store_true",
|
||
|
|
help="Ignore errors while reading source files.",
|
||
|
|
)
|
||
|
|
include = optparse.make_option(
|
||
|
|
"", "--include", action="store", metavar="PAT1,PAT2,...",
|
||
|
|
help=(
|
||
|
|
"Include only files whose paths match one of these patterns. " +
|
||
|
|
"Accepts shell-style wildcards, which must be quoted."
|
||
|
|
),
|
||
|
|
)
|
||
|
|
pylib = optparse.make_option(
|
||
|
|
"-L", "--pylib", action="store_true",
|
||
|
|
help=(
|
||
|
|
"Measure coverage even inside the Python installed library, " +
|
||
|
|
"which isn't done by default."
|
||
|
|
),
|
||
|
|
)
|
||
|
|
show_missing = optparse.make_option(
|
||
|
|
"-m", "--show-missing", action="store_true",
|
||
|
|
help="Show line numbers of statements in each module that weren't executed.",
|
||
|
|
)
|
||
|
|
module = optparse.make_option(
|
||
|
|
"-m", "--module", action="store_true",
|
||
|
|
help=(
|
||
|
|
"<pyfile> is an importable Python module, not a script path, " +
|
||
|
|
"to be run as 'python -m' would run it."
|
||
|
|
),
|
||
|
|
)
|
||
|
|
omit = optparse.make_option(
|
||
|
|
"", "--omit", action="store", metavar="PAT1,PAT2,...",
|
||
|
|
help=(
|
||
|
|
"Omit files whose paths match one of these patterns. " +
|
||
|
|
"Accepts shell-style wildcards, which must be quoted."
|
||
|
|
),
|
||
|
|
)
|
||
|
|
output_xml = optparse.make_option(
|
||
|
|
"-o", "", action="store", dest="outfile", metavar="OUTFILE",
|
||
|
|
help="Write the XML report to this file. Defaults to 'coverage.xml'",
|
||
|
|
)
|
||
|
|
output_json = optparse.make_option(
|
||
|
|
"-o", "", action="store", dest="outfile", metavar="OUTFILE",
|
||
|
|
help="Write the JSON report to this file. Defaults to 'coverage.json'",
|
||
|
|
)
|
||
|
|
output_lcov = optparse.make_option(
|
||
|
|
"-o", "", action="store", dest="outfile", metavar="OUTFILE",
|
||
|
|
help="Write the LCOV report to this file. Defaults to 'coverage.lcov'",
|
||
|
|
)
|
||
|
|
json_pretty_print = optparse.make_option(
|
||
|
|
"", "--pretty-print", action="store_true",
|
||
|
|
help="Format the JSON for human readers.",
|
||
|
|
)
|
||
|
|
parallel_mode = optparse.make_option(
|
||
|
|
"-p", "--parallel-mode", action="store_true",
|
||
|
|
help=(
|
||
|
|
"Append the machine name, process id and random number to the " +
|
||
|
|
"data file name to simplify collecting data from " +
|
||
|
|
"many processes."
|
||
|
|
),
|
||
|
|
)
|
||
|
|
precision = optparse.make_option(
|
||
|
|
"", "--precision", action="store", metavar="N", type=int,
|
||
|
|
help=(
|
||
|
|
"Number of digits after the decimal point to display for " +
|
||
|
|
"reported coverage percentages."
|
||
|
|
),
|
||
|
|
)
|
||
|
|
quiet = optparse.make_option(
|
||
|
|
"-q", "--quiet", action="store_true",
|
||
|
|
help="Don't print messages about what is happening.",
|
||
|
|
)
|
||
|
|
rcfile = optparse.make_option(
|
||
|
|
"", "--rcfile", action="store",
|
||
|
|
help=(
|
||
|
|
"Specify configuration file. " +
|
||
|
|
"By default '.coveragerc', 'setup.cfg', 'tox.ini', and " +
|
||
|
|
"'pyproject.toml' are tried. [env: COVERAGE_RCFILE]"
|
||
|
|
),
|
||
|
|
)
|
||
|
|
show_contexts = optparse.make_option(
|
||
|
|
"--show-contexts", action="store_true",
|
||
|
|
help="Show contexts for covered lines.",
|
||
|
|
)
|
||
|
|
skip_covered = optparse.make_option(
|
||
|
|
"--skip-covered", action="store_true",
|
||
|
|
help="Skip files with 100% coverage.",
|
||
|
|
)
|
||
|
|
no_skip_covered = optparse.make_option(
|
||
|
|
"--no-skip-covered", action="store_false", dest="skip_covered",
|
||
|
|
help="Disable --skip-covered.",
|
||
|
|
)
|
||
|
|
skip_empty = optparse.make_option(
|
||
|
|
"--skip-empty", action="store_true",
|
||
|
|
help="Skip files with no code.",
|
||
|
|
)
|
||
|
|
sort = optparse.make_option(
|
||
|
|
"--sort", action="store", metavar="COLUMN",
|
||
|
|
help=(
|
||
|
|
"Sort the report by the named column: name, stmts, miss, branch, brpart, or cover. " +
|
||
|
|
"Default is name."
|
||
|
|
),
|
||
|
|
)
|
||
|
|
source = optparse.make_option(
|
||
|
|
"", "--source", action="store", metavar="SRC1,SRC2,...",
|
||
|
|
help="A list of directories or importable names of code to measure.",
|
||
|
|
)
|
||
|
|
timid = optparse.make_option(
|
||
|
|
"", "--timid", action="store_true",
|
||
|
|
help=(
|
||
|
|
"Use a simpler but slower trace method. Try this if you get " +
|
||
|
|
"seemingly impossible results!"
|
||
|
|
),
|
||
|
|
)
|
||
|
|
title = optparse.make_option(
|
||
|
|
"", "--title", action="store", metavar="TITLE",
|
||
|
|
help="A text string to use as the title on the HTML.",
|
||
|
|
)
|
||
|
|
version = optparse.make_option(
|
||
|
|
"", "--version", action="store_true",
|
||
|
|
help="Display version information and exit.",
|
||
|
|
)
|
||
|
|
|
||
|
|
|
||
|
|
class CoverageOptionParser(optparse.OptionParser):
|
||
|
|
"""Base OptionParser for coverage.py.
|
||
|
|
|
||
|
|
Problems don't exit the program.
|
||
|
|
Defaults are initialized for all options.
|
||
|
|
|
||
|
|
"""
|
||
|
|
|
||
|
|
def __init__(self, *args: Any, **kwargs: Any) -> None:
|
||
|
|
kwargs["add_help_option"] = False
|
||
|
|
super().__init__(*args, **kwargs)
|
||
|
|
self.set_defaults(
|
||
|
|
# Keep these arguments alphabetized by their names.
|
||
|
|
action=None,
|
||
|
|
append=None,
|
||
|
|
branch=None,
|
||
|
|
concurrency=None,
|
||
|
|
context=None,
|
||
|
|
contexts=None,
|
||
|
|
data_file=None,
|
||
|
|
debug=None,
|
||
|
|
directory=None,
|
||
|
|
fail_under=None,
|
||
|
|
format=None,
|
||
|
|
help=None,
|
||
|
|
ignore_errors=None,
|
||
|
|
include=None,
|
||
|
|
keep=None,
|
||
|
|
module=None,
|
||
|
|
omit=None,
|
||
|
|
parallel_mode=None,
|
||
|
|
precision=None,
|
||
|
|
pylib=None,
|
||
|
|
quiet=None,
|
||
|
|
rcfile=True,
|
||
|
|
show_contexts=None,
|
||
|
|
show_missing=None,
|
||
|
|
skip_covered=None,
|
||
|
|
skip_empty=None,
|
||
|
|
sort=None,
|
||
|
|
source=None,
|
||
|
|
timid=None,
|
||
|
|
title=None,
|
||
|
|
version=None,
|
||
|
|
)
|
||
|
|
|
||
|
|
self.disable_interspersed_args()
|
||
|
|
|
||
|
|
class OptionParserError(Exception):
|
||
|
|
"""Used to stop the optparse error handler ending the process."""
|
||
|
|
pass
|
||
|
|
|
||
|
|
def parse_args_ok(self, args: List[str]) -> Tuple[bool, Optional[optparse.Values], List[str]]:
|
||
|
|
"""Call optparse.parse_args, but return a triple:
|
||
|
|
|
||
|
|
(ok, options, args)
|
||
|
|
|
||
|
|
"""
|
||
|
|
try:
|
||
|
|
options, args = super().parse_args(args)
|
||
|
|
except self.OptionParserError:
|
||
|
|
return False, None, []
|
||
|
|
return True, options, args
|
||
|
|
|
||
|
|
def error(self, msg: str) -> NoReturn:
|
||
|
|
"""Override optparse.error so sys.exit doesn't get called."""
|
||
|
|
show_help(msg)
|
||
|
|
raise self.OptionParserError
|
||
|
|
|
||
|
|
|
||
|
|
class GlobalOptionParser(CoverageOptionParser):
|
||
|
|
"""Command-line parser for coverage.py global option arguments."""
|
||
|
|
|
||
|
|
def __init__(self) -> None:
|
||
|
|
super().__init__()
|
||
|
|
|
||
|
|
self.add_options([
|
||
|
|
Opts.help,
|
||
|
|
Opts.version,
|
||
|
|
])
|
||
|
|
|
||
|
|
|
||
|
|
class CmdOptionParser(CoverageOptionParser):
|
||
|
|
"""Parse one of the new-style commands for coverage.py."""
|
||
|
|
|
||
|
|
def __init__(
|
||
|
|
self,
|
||
|
|
action: str,
|
||
|
|
options: List[optparse.Option],
|
||
|
|
description: str,
|
||
|
|
usage: Optional[str] = None,
|
||
|
|
):
|
||
|
|
"""Create an OptionParser for a coverage.py command.
|
||
|
|
|
||
|
|
`action` is the slug to put into `options.action`.
|
||
|
|
`options` is a list of Option's for the command.
|
||
|
|
`description` is the description of the command, for the help text.
|
||
|
|
`usage` is the usage string to display in help.
|
||
|
|
|
||
|
|
"""
|
||
|
|
if usage:
|
||
|
|
usage = "%prog " + usage
|
||
|
|
super().__init__(
|
||
|
|
usage=usage,
|
||
|
|
description=description,
|
||
|
|
)
|
||
|
|
self.set_defaults(action=action)
|
||
|
|
self.add_options(options)
|
||
|
|
self.cmd = action
|
||
|
|
|
||
|
|
def __eq__(self, other: str) -> bool: # type: ignore[override]
|
||
|
|
# A convenience equality, so that I can put strings in unit test
|
||
|
|
# results, and they will compare equal to objects.
|
||
|
|
return (other == f"<CmdOptionParser:{self.cmd}>")
|
||
|
|
|
||
|
|
__hash__ = None # type: ignore[assignment]
|
||
|
|
|
||
|
|
def get_prog_name(self) -> str:
|
||
|
|
"""Override of an undocumented function in optparse.OptionParser."""
|
||
|
|
program_name = super().get_prog_name()
|
||
|
|
|
||
|
|
# Include the sub-command for this parser as part of the command.
|
||
|
|
return f"{program_name} {self.cmd}"
|
||
|
|
|
||
|
|
# In lists of Opts, keep them alphabetized by the option names as they appear
|
||
|
|
# on the command line, since these lists determine the order of the options in
|
||
|
|
# the help output.
|
||
|
|
#
|
||
|
|
# In COMMANDS, keep the keys (command names) alphabetized.
|
||
|
|
|
||
|
|
GLOBAL_ARGS = [
|
||
|
|
Opts.debug,
|
||
|
|
Opts.help,
|
||
|
|
Opts.rcfile,
|
||
|
|
]
|
||
|
|
|
||
|
|
COMMANDS = {
|
||
|
|
"annotate": CmdOptionParser(
|
||
|
|
"annotate",
|
||
|
|
[
|
||
|
|
Opts.directory,
|
||
|
|
Opts.input_datafile,
|
||
|
|
Opts.ignore_errors,
|
||
|
|
Opts.include,
|
||
|
|
Opts.omit,
|
||
|
|
] + GLOBAL_ARGS,
|
||
|
|
usage="[options] [modules]",
|
||
|
|
description=(
|
||
|
|
"Make annotated copies of the given files, marking statements that are executed " +
|
||
|
|
"with > and statements that are missed with !."
|
||
|
|
),
|
||
|
|
),
|
||
|
|
|
||
|
|
"combine": CmdOptionParser(
|
||
|
|
"combine",
|
||
|
|
[
|
||
|
|
Opts.append,
|
||
|
|
Opts.combine_datafile,
|
||
|
|
Opts.keep,
|
||
|
|
Opts.quiet,
|
||
|
|
] + GLOBAL_ARGS,
|
||
|
|
usage="[options] <path1> <path2> ... <pathN>",
|
||
|
|
description=(
|
||
|
|
"Combine data from multiple coverage files. " +
|
||
|
|
"The combined results are written to a single " +
|
||
|
|
"file representing the union of the data. The positional " +
|
||
|
|
"arguments are data files or directories containing data files. " +
|
||
|
|
"If no paths are provided, data files in the default data file's " +
|
||
|
|
"directory are combined."
|
||
|
|
),
|
||
|
|
),
|
||
|
|
|
||
|
|
"debug": CmdOptionParser(
|
||
|
|
"debug", GLOBAL_ARGS,
|
||
|
|
usage="<topic>",
|
||
|
|
description=(
|
||
|
|
"Display information about the internals of coverage.py, " +
|
||
|
|
"for diagnosing problems. " +
|
||
|
|
"Topics are: " +
|
||
|
|
"'data' to show a summary of the collected data; " +
|
||
|
|
"'sys' to show installation information; " +
|
||
|
|
"'config' to show the configuration; " +
|
||
|
|
"'premain' to show what is calling coverage; " +
|
||
|
|
"'pybehave' to show internal flags describing Python behavior."
|
||
|
|
),
|
||
|
|
),
|
||
|
|
|
||
|
|
"erase": CmdOptionParser(
|
||
|
|
"erase",
|
||
|
|
[
|
||
|
|
Opts.combine_datafile
|
||
|
|
] + GLOBAL_ARGS,
|
||
|
|
description="Erase previously collected coverage data.",
|
||
|
|
),
|
||
|
|
|
||
|
|
"help": CmdOptionParser(
|
||
|
|
"help", GLOBAL_ARGS,
|
||
|
|
usage="[command]",
|
||
|
|
description="Describe how to use coverage.py",
|
||
|
|
),
|
||
|
|
|
||
|
|
"html": CmdOptionParser(
|
||
|
|
"html",
|
||
|
|
[
|
||
|
|
Opts.contexts,
|
||
|
|
Opts.directory,
|
||
|
|
Opts.input_datafile,
|
||
|
|
Opts.fail_under,
|
||
|
|
Opts.ignore_errors,
|
||
|
|
Opts.include,
|
||
|
|
Opts.omit,
|
||
|
|
Opts.precision,
|
||
|
|
Opts.quiet,
|
||
|
|
Opts.show_contexts,
|
||
|
|
Opts.skip_covered,
|
||
|
|
Opts.no_skip_covered,
|
||
|
|
Opts.skip_empty,
|
||
|
|
Opts.title,
|
||
|
|
] + GLOBAL_ARGS,
|
||
|
|
usage="[options] [modules]",
|
||
|
|
description=(
|
||
|
|
"Create an HTML report of the coverage of the files. " +
|
||
|
|
"Each file gets its own page, with the source decorated to show " +
|
||
|
|
"executed, excluded, and missed lines."
|
||
|
|
),
|
||
|
|
),
|
||
|
|
|
||
|
|
"json": CmdOptionParser(
|
||
|
|
"json",
|
||
|
|
[
|
||
|
|
Opts.contexts,
|
||
|
|
Opts.input_datafile,
|
||
|
|
Opts.fail_under,
|
||
|
|
Opts.ignore_errors,
|
||
|
|
Opts.include,
|
||
|
|
Opts.omit,
|
||
|
|
Opts.output_json,
|
||
|
|
Opts.json_pretty_print,
|
||
|
|
Opts.quiet,
|
||
|
|
Opts.show_contexts,
|
||
|
|
] + GLOBAL_ARGS,
|
||
|
|
usage="[options] [modules]",
|
||
|
|
description="Generate a JSON report of coverage results.",
|
||
|
|
),
|
||
|
|
|
||
|
|
"lcov": CmdOptionParser(
|
||
|
|
"lcov",
|
||
|
|
[
|
||
|
|
Opts.input_datafile,
|
||
|
|
Opts.fail_under,
|
||
|
|
Opts.ignore_errors,
|
||
|
|
Opts.include,
|
||
|
|
Opts.output_lcov,
|
||
|
|
Opts.omit,
|
||
|
|
Opts.quiet,
|
||
|
|
] + GLOBAL_ARGS,
|
||
|
|
usage="[options] [modules]",
|
||
|
|
description="Generate an LCOV report of coverage results.",
|
||
|
|
),
|
||
|
|
|
||
|
|
"report": CmdOptionParser(
|
||
|
|
"report",
|
||
|
|
[
|
||
|
|
Opts.contexts,
|
||
|
|
Opts.input_datafile,
|
||
|
|
Opts.fail_under,
|
||
|
|
Opts.format,
|
||
|
|
Opts.ignore_errors,
|
||
|
|
Opts.include,
|
||
|
|
Opts.omit,
|
||
|
|
Opts.precision,
|
||
|
|
Opts.sort,
|
||
|
|
Opts.show_missing,
|
||
|
|
Opts.skip_covered,
|
||
|
|
Opts.no_skip_covered,
|
||
|
|
Opts.skip_empty,
|
||
|
|
] + GLOBAL_ARGS,
|
||
|
|
usage="[options] [modules]",
|
||
|
|
description="Report coverage statistics on modules.",
|
||
|
|
),
|
||
|
|
|
||
|
|
"run": CmdOptionParser(
|
||
|
|
"run",
|
||
|
|
[
|
||
|
|
Opts.append,
|
||
|
|
Opts.branch,
|
||
|
|
Opts.concurrency,
|
||
|
|
Opts.context,
|
||
|
|
Opts.output_datafile,
|
||
|
|
Opts.include,
|
||
|
|
Opts.module,
|
||
|
|
Opts.omit,
|
||
|
|
Opts.pylib,
|
||
|
|
Opts.parallel_mode,
|
||
|
|
Opts.source,
|
||
|
|
Opts.timid,
|
||
|
|
] + GLOBAL_ARGS,
|
||
|
|
usage="[options] <pyfile> [program options]",
|
||
|
|
description="Run a Python program, measuring code execution.",
|
||
|
|
),
|
||
|
|
|
||
|
|
"xml": CmdOptionParser(
|
||
|
|
"xml",
|
||
|
|
[
|
||
|
|
Opts.input_datafile,
|
||
|
|
Opts.fail_under,
|
||
|
|
Opts.ignore_errors,
|
||
|
|
Opts.include,
|
||
|
|
Opts.omit,
|
||
|
|
Opts.output_xml,
|
||
|
|
Opts.quiet,
|
||
|
|
Opts.skip_empty,
|
||
|
|
] + GLOBAL_ARGS,
|
||
|
|
usage="[options] [modules]",
|
||
|
|
description="Generate an XML report of coverage results.",
|
||
|
|
),
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
def show_help(
|
||
|
|
error: Optional[str] = None,
|
||
|
|
topic: Optional[str] = None,
|
||
|
|
parser: Optional[optparse.OptionParser] = None,
|
||
|
|
) -> None:
|
||
|
|
"""Display an error message, or the named topic."""
|
||
|
|
assert error or topic or parser
|
||
|
|
|
||
|
|
program_path = sys.argv[0]
|
||
|
|
if program_path.endswith(os.path.sep + "__main__.py"):
|
||
|
|
# The path is the main module of a package; get that path instead.
|
||
|
|
program_path = os.path.dirname(program_path)
|
||
|
|
program_name = os.path.basename(program_path)
|
||
|
|
if env.WINDOWS:
|
||
|
|
# entry_points={"console_scripts":...} on Windows makes files
|
||
|
|
# called coverage.exe, coverage3.exe, and coverage-3.5.exe. These
|
||
|
|
# invoke coverage-script.py, coverage3-script.py, and
|
||
|
|
# coverage-3.5-script.py. argv[0] is the .py file, but we want to
|
||
|
|
# get back to the original form.
|
||
|
|
auto_suffix = "-script.py"
|
||
|
|
if program_name.endswith(auto_suffix):
|
||
|
|
program_name = program_name[:-len(auto_suffix)]
|
||
|
|
|
||
|
|
help_params = dict(coverage.__dict__)
|
||
|
|
help_params["__url__"] = __url__
|
||
|
|
help_params["program_name"] = program_name
|
||
|
|
if HAS_CTRACER:
|
||
|
|
help_params["extension_modifier"] = "with C extension"
|
||
|
|
else:
|
||
|
|
help_params["extension_modifier"] = "without C extension"
|
||
|
|
|
||
|
|
if error:
|
||
|
|
print(error, file=sys.stderr)
|
||
|
|
print(f"Use '{program_name} help' for help.", file=sys.stderr)
|
||
|
|
elif parser:
|
||
|
|
print(parser.format_help().strip())
|
||
|
|
print()
|
||
|
|
else:
|
||
|
|
assert topic is not None
|
||
|
|
help_msg = textwrap.dedent(HELP_TOPICS.get(topic, "")).strip()
|
||
|
|
if help_msg:
|
||
|
|
print(help_msg.format(**help_params))
|
||
|
|
else:
|
||
|
|
print(f"Don't know topic {topic!r}")
|
||
|
|
print("Full documentation is at {__url__}".format(**help_params))
|
||
|
|
|
||
|
|
|
||
|
|
OK, ERR, FAIL_UNDER = 0, 1, 2
|
||
|
|
|
||
|
|
|
||
|
|
class CoverageScript:
|
||
|
|
"""The command-line interface to coverage.py."""
|
||
|
|
|
||
|
|
def __init__(self) -> None:
|
||
|
|
self.global_option = False
|
||
|
|
self.coverage: Coverage
|
||
|
|
|
||
|
|
def command_line(self, argv: List[str]) -> int:
|
||
|
|
"""The bulk of the command line interface to coverage.py.
|
||
|
|
|
||
|
|
`argv` is the argument list to process.
|
||
|
|
|
||
|
|
Returns 0 if all is well, 1 if something went wrong.
|
||
|
|
|
||
|
|
"""
|
||
|
|
# Collect the command-line options.
|
||
|
|
if not argv:
|
||
|
|
show_help(topic="minimum_help")
|
||
|
|
return OK
|
||
|
|
|
||
|
|
# The command syntax we parse depends on the first argument. Global
|
||
|
|
# switch syntax always starts with an option.
|
||
|
|
parser: Optional[optparse.OptionParser]
|
||
|
|
self.global_option = argv[0].startswith("-")
|
||
|
|
if self.global_option:
|
||
|
|
parser = GlobalOptionParser()
|
||
|
|
else:
|
||
|
|
parser = COMMANDS.get(argv[0])
|
||
|
|
if not parser:
|
||
|
|
show_help(f"Unknown command: {argv[0]!r}")
|
||
|
|
return ERR
|
||
|
|
argv = argv[1:]
|
||
|
|
|
||
|
|
ok, options, args = parser.parse_args_ok(argv)
|
||
|
|
if not ok:
|
||
|
|
return ERR
|
||
|
|
assert options is not None
|
||
|
|
|
||
|
|
# Handle help and version.
|
||
|
|
if self.do_help(options, args, parser):
|
||
|
|
return OK
|
||
|
|
|
||
|
|
# Listify the list options.
|
||
|
|
source = unshell_list(options.source)
|
||
|
|
omit = unshell_list(options.omit)
|
||
|
|
include = unshell_list(options.include)
|
||
|
|
debug = unshell_list(options.debug)
|
||
|
|
contexts = unshell_list(options.contexts)
|
||
|
|
|
||
|
|
if options.concurrency is not None:
|
||
|
|
concurrency = options.concurrency.split(",")
|
||
|
|
else:
|
||
|
|
concurrency = None
|
||
|
|
|
||
|
|
# Do something.
|
||
|
|
self.coverage = Coverage(
|
||
|
|
data_file=options.data_file or DEFAULT_DATAFILE,
|
||
|
|
data_suffix=options.parallel_mode,
|
||
|
|
cover_pylib=options.pylib,
|
||
|
|
timid=options.timid,
|
||
|
|
branch=options.branch,
|
||
|
|
config_file=options.rcfile,
|
||
|
|
source=source,
|
||
|
|
omit=omit,
|
||
|
|
include=include,
|
||
|
|
debug=debug,
|
||
|
|
concurrency=concurrency,
|
||
|
|
check_preimported=True,
|
||
|
|
context=options.context,
|
||
|
|
messages=not options.quiet,
|
||
|
|
)
|
||
|
|
|
||
|
|
if options.action == "debug":
|
||
|
|
return self.do_debug(args)
|
||
|
|
|
||
|
|
elif options.action == "erase":
|
||
|
|
self.coverage.erase()
|
||
|
|
return OK
|
||
|
|
|
||
|
|
elif options.action == "run":
|
||
|
|
return self.do_run(options, args)
|
||
|
|
|
||
|
|
elif options.action == "combine":
|
||
|
|
if options.append:
|
||
|
|
self.coverage.load()
|
||
|
|
data_paths = args or None
|
||
|
|
self.coverage.combine(data_paths, strict=True, keep=bool(options.keep))
|
||
|
|
self.coverage.save()
|
||
|
|
return OK
|
||
|
|
|
||
|
|
# Remaining actions are reporting, with some common options.
|
||
|
|
report_args = dict(
|
||
|
|
morfs=unglob_args(args),
|
||
|
|
ignore_errors=options.ignore_errors,
|
||
|
|
omit=omit,
|
||
|
|
include=include,
|
||
|
|
contexts=contexts,
|
||
|
|
)
|
||
|
|
|
||
|
|
# We need to be able to import from the current directory, because
|
||
|
|
# plugins may try to, for example, to read Django settings.
|
||
|
|
sys.path.insert(0, "")
|
||
|
|
|
||
|
|
self.coverage.load()
|
||
|
|
|
||
|
|
total = None
|
||
|
|
if options.action == "report":
|
||
|
|
total = self.coverage.report(
|
||
|
|
precision=options.precision,
|
||
|
|
show_missing=options.show_missing,
|
||
|
|
skip_covered=options.skip_covered,
|
||
|
|
skip_empty=options.skip_empty,
|
||
|
|
sort=options.sort,
|
||
|
|
output_format=options.format,
|
||
|
|
**report_args
|
||
|
|
)
|
||
|
|
elif options.action == "annotate":
|
||
|
|
self.coverage.annotate(directory=options.directory, **report_args)
|
||
|
|
elif options.action == "html":
|
||
|
|
total = self.coverage.html_report(
|
||
|
|
directory=options.directory,
|
||
|
|
precision=options.precision,
|
||
|
|
skip_covered=options.skip_covered,
|
||
|
|
skip_empty=options.skip_empty,
|
||
|
|
show_contexts=options.show_contexts,
|
||
|
|
title=options.title,
|
||
|
|
**report_args
|
||
|
|
)
|
||
|
|
elif options.action == "xml":
|
||
|
|
total = self.coverage.xml_report(
|
||
|
|
outfile=options.outfile,
|
||
|
|
skip_empty=options.skip_empty,
|
||
|
|
**report_args
|
||
|
|
)
|
||
|
|
elif options.action == "json":
|
||
|
|
total = self.coverage.json_report(
|
||
|
|
outfile=options.outfile,
|
||
|
|
pretty_print=options.pretty_print,
|
||
|
|
show_contexts=options.show_contexts,
|
||
|
|
**report_args
|
||
|
|
)
|
||
|
|
elif options.action == "lcov":
|
||
|
|
total = self.coverage.lcov_report(
|
||
|
|
outfile=options.outfile,
|
||
|
|
**report_args
|
||
|
|
)
|
||
|
|
else:
|
||
|
|
# There are no other possible actions.
|
||
|
|
raise AssertionError
|
||
|
|
|
||
|
|
if total is not None:
|
||
|
|
# Apply the command line fail-under options, and then use the config
|
||
|
|
# value, so we can get fail_under from the config file.
|
||
|
|
if options.fail_under is not None:
|
||
|
|
self.coverage.set_option("report:fail_under", options.fail_under)
|
||
|
|
if options.precision is not None:
|
||
|
|
self.coverage.set_option("report:precision", options.precision)
|
||
|
|
|
||
|
|
fail_under = cast(float, self.coverage.get_option("report:fail_under"))
|
||
|
|
precision = cast(int, self.coverage.get_option("report:precision"))
|
||
|
|
if should_fail_under(total, fail_under, precision):
|
||
|
|
msg = "total of {total} is less than fail-under={fail_under:.{p}f}".format(
|
||
|
|
total=Numbers(precision=precision).display_covered(total),
|
||
|
|
fail_under=fail_under,
|
||
|
|
p=precision,
|
||
|
|
)
|
||
|
|
print("Coverage failure:", msg)
|
||
|
|
return FAIL_UNDER
|
||
|
|
|
||
|
|
return OK
|
||
|
|
|
||
|
|
def do_help(
|
||
|
|
self,
|
||
|
|
options: optparse.Values,
|
||
|
|
args: List[str],
|
||
|
|
parser: optparse.OptionParser,
|
||
|
|
) -> bool:
|
||
|
|
"""Deal with help requests.
|
||
|
|
|
||
|
|
Return True if it handled the request, False if not.
|
||
|
|
|
||
|
|
"""
|
||
|
|
# Handle help.
|
||
|
|
if options.help:
|
||
|
|
if self.global_option:
|
||
|
|
show_help(topic="help")
|
||
|
|
else:
|
||
|
|
show_help(parser=parser)
|
||
|
|
return True
|
||
|
|
|
||
|
|
if options.action == "help":
|
||
|
|
if args:
|
||
|
|
for a in args:
|
||
|
|
parser_maybe = COMMANDS.get(a)
|
||
|
|
if parser_maybe is not None:
|
||
|
|
show_help(parser=parser_maybe)
|
||
|
|
else:
|
||
|
|
show_help(topic=a)
|
||
|
|
else:
|
||
|
|
show_help(topic="help")
|
||
|
|
return True
|
||
|
|
|
||
|
|
# Handle version.
|
||
|
|
if options.version:
|
||
|
|
show_help(topic="version")
|
||
|
|
return True
|
||
|
|
|
||
|
|
return False
|
||
|
|
|
||
|
|
def do_run(self, options: optparse.Values, args: List[str]) -> int:
|
||
|
|
"""Implementation of 'coverage run'."""
|
||
|
|
|
||
|
|
if not args:
|
||
|
|
if options.module:
|
||
|
|
# Specified -m with nothing else.
|
||
|
|
show_help("No module specified for -m")
|
||
|
|
return ERR
|
||
|
|
command_line = cast(str, self.coverage.get_option("run:command_line"))
|
||
|
|
if command_line is not None:
|
||
|
|
args = shlex.split(command_line)
|
||
|
|
if args and args[0] in {"-m", "--module"}:
|
||
|
|
options.module = True
|
||
|
|
args = args[1:]
|
||
|
|
if not args:
|
||
|
|
show_help("Nothing to do.")
|
||
|
|
return ERR
|
||
|
|
|
||
|
|
if options.append and self.coverage.get_option("run:parallel"):
|
||
|
|
show_help("Can't append to data files in parallel mode.")
|
||
|
|
return ERR
|
||
|
|
|
||
|
|
if options.concurrency == "multiprocessing":
|
||
|
|
# Can't set other run-affecting command line options with
|
||
|
|
# multiprocessing.
|
||
|
|
for opt_name in ["branch", "include", "omit", "pylib", "source", "timid"]:
|
||
|
|
# As it happens, all of these options have no default, meaning
|
||
|
|
# they will be None if they have not been specified.
|
||
|
|
if getattr(options, opt_name) is not None:
|
||
|
|
show_help(
|
||
|
|
"Options affecting multiprocessing must only be specified " +
|
||
|
|
"in a configuration file.\n" +
|
||
|
|
f"Remove --{opt_name} from the command line."
|
||
|
|
)
|
||
|
|
return ERR
|
||
|
|
|
||
|
|
os.environ["COVERAGE_RUN"] = "true"
|
||
|
|
|
||
|
|
runner = PyRunner(args, as_module=bool(options.module))
|
||
|
|
runner.prepare()
|
||
|
|
|
||
|
|
if options.append:
|
||
|
|
self.coverage.load()
|
||
|
|
|
||
|
|
# Run the script.
|
||
|
|
self.coverage.start()
|
||
|
|
code_ran = True
|
||
|
|
try:
|
||
|
|
runner.run()
|
||
|
|
except NoSource:
|
||
|
|
code_ran = False
|
||
|
|
raise
|
||
|
|
finally:
|
||
|
|
self.coverage.stop()
|
||
|
|
if code_ran:
|
||
|
|
self.coverage.save()
|
||
|
|
|
||
|
|
return OK
|
||
|
|
|
||
|
|
def do_debug(self, args: List[str]) -> int:
|
||
|
|
"""Implementation of 'coverage debug'."""
|
||
|
|
|
||
|
|
if not args:
|
||
|
|
show_help("What information would you like: config, data, sys, premain, pybehave?")
|
||
|
|
return ERR
|
||
|
|
if args[1:]:
|
||
|
|
show_help("Only one topic at a time, please")
|
||
|
|
return ERR
|
||
|
|
|
||
|
|
if args[0] == "sys":
|
||
|
|
write_formatted_info(print, "sys", self.coverage.sys_info())
|
||
|
|
elif args[0] == "data":
|
||
|
|
print(info_header("data"))
|
||
|
|
data_file = self.coverage.config.data_file
|
||
|
|
debug_data_file(data_file)
|
||
|
|
for filename in combinable_files(data_file):
|
||
|
|
print("-----")
|
||
|
|
debug_data_file(filename)
|
||
|
|
elif args[0] == "config":
|
||
|
|
write_formatted_info(print, "config", self.coverage.config.debug_info())
|
||
|
|
elif args[0] == "premain":
|
||
|
|
print(info_header("premain"))
|
||
|
|
print(short_stack())
|
||
|
|
elif args[0] == "pybehave":
|
||
|
|
write_formatted_info(print, "pybehave", env.debug_info())
|
||
|
|
else:
|
||
|
|
show_help(f"Don't know what you mean by {args[0]!r}")
|
||
|
|
return ERR
|
||
|
|
|
||
|
|
return OK
|
||
|
|
|
||
|
|
|
||
|
|
def unshell_list(s: str) -> Optional[List[str]]:
|
||
|
|
"""Turn a command-line argument into a list."""
|
||
|
|
if not s:
|
||
|
|
return None
|
||
|
|
if env.WINDOWS:
|
||
|
|
# When running coverage.py as coverage.exe, some of the behavior
|
||
|
|
# of the shell is emulated: wildcards are expanded into a list of
|
||
|
|
# file names. So you have to single-quote patterns on the command
|
||
|
|
# line, but (not) helpfully, the single quotes are included in the
|
||
|
|
# argument, so we have to strip them off here.
|
||
|
|
s = s.strip("'")
|
||
|
|
return s.split(",")
|
||
|
|
|
||
|
|
|
||
|
|
def unglob_args(args: List[str]) -> List[str]:
|
||
|
|
"""Interpret shell wildcards for platforms that need it."""
|
||
|
|
if env.WINDOWS:
|
||
|
|
globbed = []
|
||
|
|
for arg in args:
|
||
|
|
if "?" in arg or "*" in arg:
|
||
|
|
globbed.extend(glob.glob(arg))
|
||
|
|
else:
|
||
|
|
globbed.append(arg)
|
||
|
|
args = globbed
|
||
|
|
return args
|
||
|
|
|
||
|
|
|
||
|
|
HELP_TOPICS = {
|
||
|
|
"help": """\
|
||
|
|
Coverage.py, version {__version__} {extension_modifier}
|
||
|
|
Measure, collect, and report on code coverage in Python programs.
|
||
|
|
|
||
|
|
usage: {program_name} <command> [options] [args]
|
||
|
|
|
||
|
|
Commands:
|
||
|
|
annotate Annotate source files with execution information.
|
||
|
|
combine Combine a number of data files.
|
||
|
|
debug Display information about the internals of coverage.py
|
||
|
|
erase Erase previously collected coverage data.
|
||
|
|
help Get help on using coverage.py.
|
||
|
|
html Create an HTML report.
|
||
|
|
json Create a JSON report of coverage results.
|
||
|
|
lcov Create an LCOV report of coverage results.
|
||
|
|
report Report coverage stats on modules.
|
||
|
|
run Run a Python program and measure code execution.
|
||
|
|
xml Create an XML report of coverage results.
|
||
|
|
|
||
|
|
Use "{program_name} help <command>" for detailed help on any command.
|
||
|
|
""",
|
||
|
|
|
||
|
|
"minimum_help": (
|
||
|
|
"Code coverage for Python, version {__version__} {extension_modifier}. " +
|
||
|
|
"Use '{program_name} help' for help."
|
||
|
|
),
|
||
|
|
|
||
|
|
"version": "Coverage.py, version {__version__} {extension_modifier}",
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
def main(argv: Optional[List[str]] = None) -> Optional[int]:
|
||
|
|
"""The main entry point to coverage.py.
|
||
|
|
|
||
|
|
This is installed as the script entry point.
|
||
|
|
|
||
|
|
"""
|
||
|
|
if argv is None:
|
||
|
|
argv = sys.argv[1:]
|
||
|
|
try:
|
||
|
|
status = CoverageScript().command_line(argv)
|
||
|
|
except _ExceptionDuringRun as err:
|
||
|
|
# An exception was caught while running the product code. The
|
||
|
|
# sys.exc_info() return tuple is packed into an _ExceptionDuringRun
|
||
|
|
# exception.
|
||
|
|
traceback.print_exception(*err.args) # pylint: disable=no-value-for-parameter
|
||
|
|
status = ERR
|
||
|
|
except _BaseCoverageException as err:
|
||
|
|
# A controlled error inside coverage.py: print the message to the user.
|
||
|
|
msg = err.args[0]
|
||
|
|
print(msg)
|
||
|
|
status = ERR
|
||
|
|
except SystemExit as err:
|
||
|
|
# The user called `sys.exit()`. Exit with their argument, if any.
|
||
|
|
if err.args:
|
||
|
|
status = err.args[0]
|
||
|
|
else:
|
||
|
|
status = None
|
||
|
|
return status
|
||
|
|
|
||
|
|
# Profiling using ox_profile. Install it from GitHub:
|
||
|
|
# pip install git+https://github.com/emin63/ox_profile.git
|
||
|
|
#
|
||
|
|
# $set_env.py: COVERAGE_PROFILE - Set to use ox_profile.
|
||
|
|
_profile = os.environ.get("COVERAGE_PROFILE", "")
|
||
|
|
if _profile: # pragma: debugging
|
||
|
|
from ox_profile.core.launchers import SimpleLauncher # pylint: disable=import-error
|
||
|
|
original_main = main
|
||
|
|
|
||
|
|
def main( # pylint: disable=function-redefined
|
||
|
|
argv: Optional[List[str]] = None,
|
||
|
|
) -> Optional[int]:
|
||
|
|
"""A wrapper around main that profiles."""
|
||
|
|
profiler = SimpleLauncher.launch()
|
||
|
|
try:
|
||
|
|
return original_main(argv)
|
||
|
|
finally:
|
||
|
|
data, _ = profiler.query(re_filter="coverage", max_records=100)
|
||
|
|
print(profiler.show(query=data, limit=100, sep="", col=""))
|
||
|
|
profiler.cancel()
|