python-coverage(1)

📦
version 7.16.1 · 2 versions
, in ubuntu stonking

💅 python-coverage — the manual page, but make it cute

okay bestie, grab a boba, because we're about to learn python-coverage, which lives in the Coverage section of your manual (that's the manual name, and you're gonna see it everywhere, iykyk 🎀).

✨ SYNOPSIS ✨

python-coverage command [ option ... ]
python-coverage help [ command ]

🌸 DESCRIPTION 🌸

So basically python-coverage runs your Python program, watches very closely which lines actually get executed and which ones just sit there like wallflowers 🙈, and then reports all those coverage measurements back to you. It's giving surveillance but make it helpful.

👑 COMMAND OVERVIEW 👑

Here's the whole roster, main character energy for days:

  • python-coverage annotate — annotate your source files with execution info. Little notes everywhere, so cute.
  • python-coverage combine — combine a bunch of data files into one. Bestie behavior: uniting the squad 🫶
  • python-coverage debug — show diagnostic info about the internals of this program. Peek behind the curtain 💀
  • python-coverage erase — erase previously collected coverage data. Not me hitting delete on the past.
  • python-coverage help — get help on using coverage.py. We love a supportive icon.
  • python-coverage html — create an HTML report. Pretty pages, slay.
  • python-coverage report — report coverage stats on modules. The receipts 📋
  • python-coverage run — run a Python program and measure code execution. The whole point, honestly.
  • python-coverage xml — create an XML report of coverage results. For the machine-girlies 🤖

⭐ GLOBAL OPTIONS ⭐

  • --help, -h — describes how to use Coverage, either in general or for a specific command. Your SOS button 💖
  • --rcfile RCFILE — specify the configuration file RCFILE. The default is .coveragerc. Like a settings file but with a shadowy dot in front.
  • --omit PATTERN ... — omit files when their filename matches one of these *PATTERN*s. Ngl, this usually needs quoting on the command line.
  • --include PATTERN ... — include files only when their filename path matches one of these *PATTERN*s. Also usually needs quoting on the command line, fr fr.

🔥 COMMAND REFERENCE 🔥

annotate 🎀

Options:

  • -d DIR, --directory DIR — write the output files to DIR.
  • -i, --ignore-errors — ignore errors while reading source files. We're unbothered 💅

combine PATH PATH [ ... ] 🦋

Combine data from multiple coverage files PATH, collected with run -p. The combined results get written to a single file that represents the union of the data. One file to rule them all ✨

debug topic 🔍

Display information on the internals of coverage.py, for diagnosing problems. Love a deep dive.

Topics are:

  • data, to show a summary of the collected data.
  • sys, to show installation information.

erase 🌪️

Erase previously collected coverage data. Gone. Poof. Periodt.

help [ command ] 🙋‍♀️

Describe how to use Coverage.

html [ option ... ] [ MODULE ... ] 🌈

Create an HTML report of the coverage of each MODULE file. Each file gets its own page, with the source decorated to show executed, excluded, and missed lines. It's giving scrapbook.

Options:

  • -d DIR, --directory DIR — write the output files to DIR.
  • --title TITLE — use the text string TITLE as the title on the HTML.
  • --fail-under MIN — exit with a status of 2 if the total coverage is less than MIN. Failing with flair.
  • -i, --ignore-errors — ignore errors while reading source files.

report [ option ... ] [ MODULE ... ] 📊

Report coverage statistics on each MODULE.

Options:

  • --fail-under MIN — exit with a status of 2 if the total coverage is less than MIN.
  • -i, --ignore-errors — ignore errors while reading source files.
  • -m, --show-missing — show line numbers of statements in each module that weren't executed. The callout post, but constructive.

run [ options ... ] PROGRAMFILE [ program_options ] 🏃‍♀️💨

Run a Python program PROGRAMFILE, measuring code execution. The main event.

Options:

  • -a, --append — append coverage data to .coverage; otherwise it's started clean with each run. Fresh start vs. building the lore.
  • --branch — measure branch coverage in addition to statement coverage. Two types of coverage, double the power ✨
  • --debug DEBUGOPT,... — debug options DEBUGOPT, separated by commas.
  • -L, --pylib — measure coverage even inside the Python installed library, which isn't done by default.
  • -p, --parallel-mode — append the machine name, process id and random number to the .coverage data file name, to simplify collecting data from many processes. Chaos-coordinated 🎀
  • --timid — use a simpler but slower trace method. Try this if you get seemingly impossible results!
  • --source SOURCE ... — a list of packages or directories of code to be measured.

xml [ options ... ] [ MODULES ... ] 🤖

Generate an XML report of coverage results on each MODULE.

Options:

  • --fail-under MIN — exit with a status of 2 if the total coverage is less than MIN.
  • -i, --ignore-errors — ignore errors while reading source files.
  • -o OUTFILE — write the XML report to OUTFILE. Defaults to coverage.xml.

🧚 ENVIRONMENT VARIABLES 🧚

  • COVERAGE_FILE — path to the file where coverage measurements are collected to and reported from. Default: .coverage in the current working directory.
  • COVERAGE_OPTIONS — space-separated series of command-line options to python-coverage. Default: empty.

💜 HISTORY 💜

The python-coverage command is a Python program which calls the coverage Python library to do all the work. No cap, it's the library doing the heavy lifting.

The library was originally developed by Gareth Rees, and is now developed by Ned Batchelder. Shoutout to both 👑

This manual page was written to document the python-coverage command for Debian. This is free software: you may copy, modify and/or distribute this work under the terms of the GNU General Public License, version 3 or later <http://www.gnu.org/licenses/> as published by the Free Software Foundation, version 3 or later. No warranty expressed or implied.

On Debian systems, the complete text of the GNU General Public License version 3 can be found in the file /usr/share/common-licenses/GPL-3.

Author ✍️

Ben Finney <ben+python@benfinney.id.au>

Copyright © 2010–2017 Ben Finney <bignose@debian.org>

and that's the whole thing bestie, dated 2020-09-06, from the Coverage manual (that python-coverage(1) footer vibe). go measure some lines, you're gonna slay 🫶💖✨

📦 where this page comes from