feat: add "lcov" command for generating LCOV reports

* Add LCOV functionality into coverage.py

* Add testing for the LCOV reporter

* Add documentation for the LCOV reporter

5 files changed, 73 insertions, 4 deletions

diff --git a/doc/cmd.rst b/doc/cmd.rst
index a26aa8ac..f4cbff34 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -58,6 +58,8 @@ Coverage.py has a number of commands:
 
 * **json** -- :ref:`Produce a JSON report with coverage results <cmd_json>`.
 
+* **lcov** -- :ref:`Produce an LCOV report with coverage results <cmd_lcov>`.
+
 * **annotate** --
   :ref:`Annotate source files with coverage results <cmd_annotate>`.
 
@@ -430,8 +432,8 @@ Reporting
 ---------
 
 Coverage.py provides a few styles of reporting, with the **report**, **html**,
-**annotate**, **json**, and **xml** commands.  They share a number of common
-options.
+**annotate**, **json**, **lcov**, and **xml** commands.  They share a number
+of common options.
 
 The command-line arguments are module or file names to report on, if you'd like
 to report on a subset of the data collected.
@@ -785,6 +787,42 @@ The **json** command writes coverage data to a "coverage.json" file.
 You can specify the name of the output file with the ``-o`` switch.  The JSON
 can be nicely formatted by specifying the ``--pretty-print`` switch.
 
+.. _cmd_lcov:
+
+LCOV reporting: ``coverage lcov``
+---------------------------------
+
+The **json** command writes coverage data to a "coverage.lcov" file.
+
+.. [[[cog show_help("lcov") ]]]
+.. code::
+
+    $ coverage lcov --help
+    Usage: coverage lcov [options] [modules]
+
+    Generate an LCOV report of coverage results.
+
+    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.
+      --include=PAT1,PAT2,...
+                            Include only files whose paths match one of these
+                            patterns. Accepts shell-style wildcards, which must be
+                            quoted.
+      -o OUTFILE            Write the LCOV report to this file. Defaults to
+                            'coverage.lcov'
+      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
+                            Accepts shell-style wildcards, which must be quoted.
+      -q, --quiet           Don't print messages about what is happening.
+      --debug=OPTS          Debug options, separated by commas. [env:
+                            COVERAGE_DEBUG]
+      -h, --help            Get help on this command.
+      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
+                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
+                            tried. [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: 4d078e4637e5b507cbb997803a0d4758)
+
 Other common reporting options are described above in :ref:`cmd_reporting`.
 
 
diff --git a/doc/dict.txt b/doc/dict.txt
index 70c4a890..b9411bb9 100644
--- a/doc/dict.txt
+++ b/doc/dict.txt
@@ -107,6 +107,7 @@ jquery
 json
 jython
 kwargs
+lcov
 Mako
 matcher
 matchers
diff --git a/doc/index.rst b/doc/index.rst
index 9661797b..74193cbb 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -152,7 +152,8 @@ Coverage.py can do a number of things:
 - It can tell you :ref:`what tests ran which lines <dynamic_contexts>`.
 
 - It can produce reports in a number of formats: :ref:`text <cmd_report>`,
-  :ref:`HTML <cmd_html>`, :ref:`XML <cmd_xml>`, and :ref:`JSON <cmd_json>`.
+  :ref:`HTML <cmd_html>`, :ref:`XML <cmd_xml>`, :ref:`LCOV <cmd_lcov>`,
+  and :ref:`JSON <cmd_json>`.
 
 - For advanced uses, there's an :ref:`API <api>`, and the result data is
   available in a :ref:`SQLite database <dbschema>`.
diff --git a/doc/python-coverage.1.txt b/doc/python-coverage.1.txt
index bffc7072..41a3bbea 100644
--- a/doc/python-coverage.1.txt
+++ b/doc/python-coverage.1.txt
@@ -67,6 +67,9 @@ COMMAND OVERVIEW
 |command| **xml**
     Create an XML report of coverage results.
 
+|command| **lcov**
+    Create an LCOV report of coverage results.
+
 
 GLOBAL OPTIONS
 ==============
@@ -229,6 +232,31 @@ COMMAND REFERENCE
     \--show-contexts
         Include information about the contexts that executed each line.
 
+**lcov** [ `option` ... ] [ `MODULE` ... ]
+
+    Create an LCOV report of the coverage results.
+
+    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 LCOV report to `OUTFILE`. Defaults to ``coverage.lcov``.
+
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
+    \-q, --quiet
+        Don't print messages about what is happening.
 
 **report** [ `option` ... ] [ `MODULE` ... ]
 
diff --git a/doc/source.rst b/doc/source.rst
index 85a46a33..34aa611f 100644
--- a/doc/source.rst
+++ b/doc/source.rst
@@ -88,7 +88,8 @@ reported.  Usually you want to see all the code that was measured, but if you
 are measuring a large project, you may want to get reports for just certain
 parts.
 
-The report commands (``report``, ``html``, ``json``, ``annotate``, and ``xml``)
+The report commands (``report``, ``html``, ``json``, ``lcov``, ``annotate``,
+and ``xml``)
 all take optional ``modules`` arguments, and ``--include`` and ``--omit``
 switches. The ``modules`` arguments specify particular modules to report on.
 The ``include`` and ``omit`` values are lists of file name patterns, just as