Execution¶

When running your code, thecoveragerun command will by default measureall code, unless it is part of the Python standard library.

You can specify source to measure with the--source command-line switch, orthe[run]source configuration value. The value is a comma- ornewline-separated list of directories or package names. If specified, onlysource inside these directories or packages will be measured. Specifying thesource option also enables coverage.py to report on unexecuted files, since itcan search the source tree for files that haven’t been measured at all. Onlyimportable files (ones at the root of the tree, or in directories with a__init__.py file) will be considered. Files with unusual punctuation intheir names will be skipped (they are assumed to be scratch files written bytext editors). Files that do not end with.py or.pyo or.pycwill also be skipped.

You can further fine-tune coverage.py’s attention with the--include and--omit switches (or[run]include and[run]omit configurationvalues).--include is a list of file name patterns. If specified, onlyfiles matching those patterns will be measured.--omit is also a list offile name patterns, specifying files not to measure. If bothinclude andomit are specified, first the set of files is reduced to only those thatmatch the include patterns, then any files that match the omit pattern areremoved from the set.

Theinclude andomit file name patterns follow typical shell syntax:* matches any number of characters and? matches a single character.Patterns that start with a wildcard character are used as-is, other patternsare interpreted relative to the current directory:

[run]omit=# omit anything in a .local directory anywhere*/.local/*# omit everything in /usr/usr/*# omit this single fileutils/tirefire.py

Thesource,include, andomit values all work together to determinethe source that will be measured.

Reporting¶

Once your program is measured, you can specify the source files you wantreported. Usually you want to see all the code that was measured, but if youare measuring a large project, you may want to get reports for just certainparts.

The report commands (report,html,annotate, andxml) all takeoptionalmodules arguments, and--include and--omit switches. Themodules arguments specify particular modules to report on. Theincludeandomit values are lists of file name patterns, just as with theruncommand.

Remember that the reporting commands can only report on the data that has beencollected, so the data you’re looking for may not be in the data available forreporting.

Note that these are ways of specifying files to measure. You can also excludeindividual source lines. SeeExcluding code from coverage.py for details.