The reporting functions now return a float, the total percentage covered.

6 files changed, 56 insertions, 4 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 0da1d94..8894734 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -13,6 +13,10 @@ Version 3.5.4b1
   configuration file, please check carefully that you were not relying on the
   old broken behavior.
 
+- The reporting functions coverage.report(), coverage.html_report(), and
+  coverage.xml_report() now all return a float, the total percentage covered
+  measurement.
+
 - 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.
diff --git a/coverage/control.py b/coverage/control.py
index acca99e..006f06b 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -532,13 +532,15 @@ class coverage(object):
         match those patterns will be included in the report. Modules matching
         `omit` will not be included in the report.
 
+        Returns a float, the total percentage covered.
+
         """
         self.config.from_args(
             ignore_errors=ignore_errors, omit=omit, include=include,
             show_missing=show_missing,
             )
         reporter = SummaryReporter(self, self.config)
-        reporter.report(morfs, outfile=file)
+        return reporter.report(morfs, outfile=file)
 
     def annotate(self, morfs=None, directory=None, ignore_errors=None,
                     omit=None, include=None):
@@ -571,13 +573,15 @@ class coverage(object):
 
         See `coverage.report()` for other arguments.
 
+        Returns a float, the total percentage covered.
+
         """
         self.config.from_args(
             ignore_errors=ignore_errors, omit=omit, include=include,
             html_dir=directory, extra_css=extra_css,
             )
         reporter = HtmlReporter(self, self.config)
-        reporter.report(morfs)
+        return reporter.report(morfs)
 
     def xml_report(self, morfs=None, outfile=None, ignore_errors=None,
                     omit=None, include=None):
@@ -590,6 +594,8 @@ class coverage(object):
 
         See `coverage.report()` for other arguments.
 
+        Returns a float, the total percentage covered.
+
         """
         self.config.from_args(
             ignore_errors=ignore_errors, omit=omit, include=include,
@@ -604,7 +610,7 @@ class coverage(object):
                 file_to_close = outfile
         try:
             reporter = XmlReporter(self, self.config)
-            reporter.report(morfs, outfile=outfile)
+            return reporter.report(morfs, outfile=outfile)
         finally:
             if file_to_close:
                 file_to_close.close()
diff --git a/coverage/html.py b/coverage/html.py
index 34bf6a6..65bc25e 100644
--- a/coverage/html.py
+++ b/coverage/html.py
@@ -94,6 +94,8 @@ class HtmlReporter(Reporter):
 
         self.make_local_static_report_files()
 
+        return self.totals.pc_covered
+
     def make_local_static_report_files(self):
         """Make local instances of static files for HTML report."""
         # The files we provide must always be copied.
@@ -245,7 +247,7 @@ class HtmlReporter(Reporter):
         files = self.files
         arcs = self.arcs
 
-        totals = sum([f['nums'] for f in files])
+        self.totals = totals = sum([f['nums'] for f in files])
         extra_css = self.extra_css
 
         self.write_html(
diff --git a/coverage/summary.py b/coverage/summary.py
index c8fa5be..03648e5 100644
--- a/coverage/summary.py
+++ b/coverage/summary.py
@@ -82,3 +82,5 @@ class SummaryReporter(Reporter):
             if self.config.show_missing:
                 args += ("",)
             outfile.write(fmt_coverage % args)
+
+        return total.pc_covered
diff --git a/coverage/xmlreport.py b/coverage/xmlreport.py
index 03f910c..e062cee 100644
--- a/coverage/xmlreport.py
+++ b/coverage/xmlreport.py
@@ -84,6 +84,9 @@ class XmlReporter(Reporter):
         # Use the DOM to write the output file.
         outfile.write(self.xml_out.toprettyxml())
 
+        # Return the total percentage.
+        return 100.0 * (lhits_tot + bhits_tot) / (lnum_tot + bnum_tot)
+
     def xml_file(self, cu, analysis):
         """Add to the XML report for a single file."""
 
diff --git a/test/test_summary.py b/test/test_summary.py
index 71fbb1a..9db8e4e 100644
--- a/test/test_summary.py
+++ b/test/test_summary.py
@@ -209,3 +209,38 @@ class SummaryTest2(CoverageTest):
         report = re.sub(r"\s+", " ", report)
         self.assert_("test/modules/pkg1/__init__ 1 0 100%" in report)
         self.assert_("test/modules/pkg2/__init__ 0 0 100%" in report)
+
+
+class ReportingReturnValue(CoverageTest):
+    def run_coverage(self):
+        self.make_file("doit.py", """\
+            a = 1
+            b = 2
+            c = 3
+            d = 4
+            if a > 10:
+                f = 6
+            g = 7
+            """)
+
+        cov = coverage.coverage()
+        cov.start()
+        self.import_local_file("doit")
+        cov.stop()
+        return cov
+
+    def test_report(self):
+        cov = self.run_coverage()
+        repout = StringIO()
+        val = cov.report(include="*/doit.py")
+        self.assertAlmostEqual(val, 85.7, 1)
+
+    def test_html(self):
+        cov = self.run_coverage()
+        val = cov.html_report(include="*/doit.py")
+        self.assertAlmostEqual(val, 85.7, 1)
+
+    def test_xml(self):
+        cov = self.run_coverage()
+        val = cov.xml_report(include="*/doit.py")
+        self.assertAlmostEqual(val, 85.7, 1)