feat: --format=total writes just the total number

6 files changed, 36 insertions, 14 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index ce4b4926..a03c052c 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -21,9 +21,13 @@ Unreleased
 ----------
 
 - Text reporting with ``coverage report`` now has a ``--format=`` option.
-  The original style (``--format=text``) is the default.  Now you can also
-  use ``--format=markdown`` to get the table in Markdown format, thanks to
-  Steve Oswald in `pull 1479`_, closing `issue 1418`_.
+  The original style (``--format=text``) is the default.
+
+  - Using ``--format=markdown`` will write the table in Markdown format, thanks
+    to Steve Oswald in `pull 1479`_, closing `issue 1418`_.
+
+  - Using ``--format=total`` will write a single total number to the
+    output.  This can be useful for making badges or writing status updates.
 
 - Fixed a mis-measurement of a strange use of wildcard alternatives in
   match/case statements, closing `issue 1421`_.
diff --git a/coverage/cmdline.py b/coverage/cmdline.py
index bea95993..b15a66f7 100644
--- a/coverage/cmdline.py
+++ b/coverage/cmdline.py
@@ -98,7 +98,7 @@ class Opts:
     )
     format = optparse.make_option(
         '', '--format', action='store', metavar="FORMAT",
-        help="Output format, either text (default) or markdown",
+        help="Output format, either text (default), markdown, or total.",
     )
     help = optparse.make_option(
         '-h', '--help', action='store_true',
diff --git a/coverage/control.py b/coverage/control.py
index d260eeab..9a55acb1 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -924,7 +924,7 @@ class Coverage:
         `file` is a file-like object, suitable for writing.
 
         `output_format` determines the format, either "text" (the default),
-        or "markdown".
+        "markdown", or "total".
 
         `include` is a list of file name patterns.  Files that match will be
         included in the report. Files matching `omit` will not be included in
diff --git a/coverage/summary.py b/coverage/summary.py
index 1aa802af..d1919e71 100644
--- a/coverage/summary.py
+++ b/coverage/summary.py
@@ -19,6 +19,7 @@ class SummaryReporter:
         self.config = self.coverage.config
         self.branches = coverage.get_data().has_arcs()
         self.outfile = None
+        self.output_format = self.config.format or "text"
         self.fr_analysis = []
         self.skipped_count = 0
         self.empty_count = 0
@@ -159,6 +160,15 @@ class SummaryReporter:
         if not self.total.n_files and not self.skipped_count:
             raise NoDataError("No data to report.")
 
+        if self.output_format == "total":
+            self.write(self.total.pc_covered_str)
+        else:
+            self.tabular_report()
+
+        return self.total.n_statements and self.total.pc_covered
+
+    def tabular_report(self):
+        """Writes tabular report formats."""
         # Prepare the header line and column sorting.
         header = ["Name", "Stmts", "Miss"]
         if self.branches:
@@ -221,15 +231,12 @@ class SummaryReporter:
             file_suffix = 's' if self.empty_count > 1 else ''
             end_lines.append(f"\n{self.empty_count} empty file{file_suffix} skipped.")
 
-        text_format = self.config.format or "text"
-        if text_format == "markdown":
+        if self.output_format == "markdown":
             formatter = self._report_markdown
         else:
             formatter = self._report_text
         formatter(header, lines_values, total_line, end_lines)
 
-        return self.total.n_statements and self.total.pc_covered
-
     def report_one_file(self, fr, analysis):
         """Report on just one file, the callback from report()."""
         nums = analysis.numbers
diff --git a/doc/cmd.rst b/doc/cmd.rst
index 7b49ec14..be323c0c 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -518,7 +518,8 @@ as a percentage.
                             file. Defaults to '.coverage'. [env: COVERAGE_FILE]
       --fail-under=MIN      Exit with a status of 2 if the total coverage is less
                             than MIN.
-      --format=FORMAT       Output format, either text (default) or markdown
+      --format=FORMAT       Output format, either text (default), markdown, or
+                            total.
       -i, --ignore-errors   Ignore errors while reading source files.
       --include=PAT1,PAT2,...
                             Include only files whose paths match one of these
@@ -541,7 +542,7 @@ as a percentage.
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (checksum: 8c671de502a388159689082d906f786a)
+.. [[[end]]] (checksum: 167272a29d9e7eb017a592a0e0747a06)
 
 The ``-m`` flag also shows the line numbers of missing statements::
 
@@ -592,9 +593,11 @@ decimal point in coverage percentages, defaulting to none.
 
 The ``--sort`` option is the name of a column to sort the report by.
 
-The ``--format`` option controls the style of the table.  ``--format=text``
+The ``--format`` option controls the style of the report.  ``--format=text``
 creates plain text tables as shown above.  ``--format=markdown`` creates
-Markdown tables.
+Markdown tables.  ``--format=total`` writes out a single number, the total
+coverage percentage as shown at the end of the tables, but without a percent
+sign.
 
 Other common reporting options are described above in :ref:`cmd_reporting`.
 These options can also be set in your .coveragerc file. See
diff --git a/tests/test_summary.py b/tests/test_summary.py
index 3a14ee3c..e32a1d2e 100644
--- a/tests/test_summary.py
+++ b/tests/test_summary.py
@@ -439,6 +439,9 @@ class SummaryTest(UsingModulesMixin, CoverageTest):
         squeezed = self.squeezed_lines(report)
         assert squeezed[4] == "1 file skipped due to complete coverage."
 
+        total = self.get_report(cov, output_format="total", skip_covered=True)
+        assert total == "100\n"
+
     def test_report_skip_covered_longfilename(self):
         self.make_file("long_______________filename.py", """
             def foo():
@@ -829,7 +832,7 @@ class SummaryTest(UsingModulesMixin, CoverageTest):
         cov = coverage.Coverage(source=["."])
         self.start_import_stop(cov, "mymissing")
         assert self.stdout() == 'y\nz\n'
-        report = self.get_report(cov,squeeze=False, output_format="markdown", show_missing=True)
+        report = self.get_report(cov, squeeze=False, output_format="markdown", show_missing=True)
 
         # | Name         |    Stmts |     Miss |   Cover |   Missing |
         # |------------- | -------: | -------: | ------: | --------: |
@@ -840,6 +843,11 @@ class SummaryTest(UsingModulesMixin, CoverageTest):
         assert report_lines[2] == "| mymissing.py |       14 |        3 |     79% |   3-4, 10 |"
         assert report_lines[3] == "|    **TOTAL** |   **14** |    **3** | **79%** |           |"
 
+        assert self.get_report(cov, output_format="total") == "79\n"
+        assert self.get_report(cov, output_format="total", precision=2) == "78.57\n"
+        assert self.get_report(cov, output_format="total", precision=4) == "78.5714\n"
+
+
 class ReportingReturnValueTest(CoverageTest):
     """Tests of reporting functions returning values."""