The latest beta version of coverage.py is available: I give you coverage.py v3.6b1. There are lots of changes here. Somehow I got on a roll, and fixed 22 tickets. The full list of changes is below.

But before we get to that, there are two bugs I’d like to fix but need some help with:

• Coverage xml doesn’t produce <sources> element: The XML report is meant to be consumed by Cobertura, particularly as a plugin in Jenkins. This bug says that the links to the source files don’t work, but in my tests they do, so I don’t understand the conditions that make it fail. If you have a publicly available repo that demonstrates this problem, let me know so I can use it as a test case.
• On Linux, packages get installed in places coverage.py doesn’t ignore: If you have any good ideas for determining which directories contain “third-party” packages, I’d like to make coverage.py smarter about it. It doesn’t have to be perfect, because users can always override the defaults, but I’d like it to start with a better guess.

Other than the 22 bugs fixed, big changes include:

• For continuous integration users, coverage.py can now easily indicate whether the total coverage percentage exceeds a given threshold, with the --fail-under switch. Similar information is available through the API as well.
• HTML reports can now be titled, which helps in multi-project environments.
• Configuration files now support environment variable substitution.

Try it out (or “give it a burl” as they say down under), and let me know if anything is amiss.

Full changes:

• Wildcards in include= and omit= arguments were not handled properly in reporting functions, though they were when running. Now they are handled uniformly, closing issue 143 and issue 163. NOTE: it is possible that your configurations may now be incorrect. If you use include or omit during reporting, whether on the command line, through the API, or in a configuration file, please check carefully that you were not relying on the old broken behavior.
• The report, html, and xml commands now accept a --fail-under switch that indicates in the exit status whether the coverage percentage was less than a particular value. Closes issue 139.
• The reporting functions coverage.report(), coverage.html_report(), and coverage.xml_report() now all return a float, the total percentage covered measurement.
• The HTML report’s title can now be set in the configuration file, with the --title switch on the command line, or via the API.
• Configuration files now support substitution of environment variables, using syntax like ${WORD}. Closes issue 97.
• Embarrassingly, the [xml] output= setting in the .coveragerc file simply didn’t work. Now it does.
• The XML report now consistently uses filenames for the filename attribute, rather than sometimes using module names. Fixes issue 67. Thanks, Marcus Cobden.
• Coverage percentage metrics are now computed slightly differently under branch coverage. This means that completely unexecuted files will now correctly have 0% coverage, fixing issue 156. This also means that your total coverage numbers will generally now be lower if you are measuring branch coverage.
• When installing, now in addition to creating a “coverage” command, two new aliases are also installed. A “coverage2” or “coverage3” command will be created, depending on whether you are installing in Python 2.x or 3.x. A “coverage-X.Y” command will also be created corresponding to your specific version of Python. Closes issue 111.
• The coverage.py installer no longer tries to bootstrap setuptools or Distribute. You must have one of them installed first, as issue 202 recommended.
• The coverage.py kit now includes docs (closing issue 137) and tests.
• On Windows, files are now reported in their correct case, fixing issue 89 and issue 203.
• If a file is missing during reporting, the path shown in the error message is now correct, rather than an incorrect path in the current directory. Fixes issue 60.
• Running an HTML report in Python 3 in the same directory as an old Python 2 HTML report would fail with a UnicodeDecodeError. This issue (issue 193) is now fixed.
• Fixed yet another error trying to parse non-Python files as Python, this time an IndentationError, closing issue 82 for the fourth time...
• If coverage xml fails because there is no data to report, it used to create a zero-length XML file. Now it doesn’t, fixing issue 210.
• Jython files now work with the --source option, fixing issue 100.
• Running coverage under a debugger is unlikely to work, but it shouldn’t fail with “TypeError: ‘NoneType’ object is not iterable”. Fixes issue 201.
• On some Linux distributions, when installed with the OS package manager, coverage.py would report its own code as part of the results. Now it won’t, fixing issue 214, though this will take some time to be repackaged by the operating systems.
• Docstrings for the legacy singleton methods are more helpful. Thanks Marius Gedminas. Closes issue 205.
• The pydoc tool can now show documentation for the class coverage.coverage. Closes issue 206.
• Added a page to the docs about contributing to coverage.py, closing issue 171.
• When coverage.py ended unsuccessfully, it may have reported odd errors like 'NoneType' object has no attribute 'isabs'. It no longer does, so kiss issue 153 goodbye.