feat: Coverage.branch_stats() #1888

Author: nedbat

CHANGES.rst

@@ -23,6 +23,9 @@ upgrading your version of coverage.py.
 Unreleased
 ----------
 
+- The Coverage object has a new method, :meth:`.Coverage.branch_stats` for
+  getting simple branch information for a module.  Closes `issue 1888`_.
+
 - Many constant tests in if statements are now recognized as being optimized
   away.  For example, previously ``if 13:`` would have been considered a branch
   with one path not taken.  Now it is understood as always true and no coverage
@@ -39,6 +42,7 @@ Unreleased
 
 - Confirmed support for PyPy 3.11. Thanks Michał Górny.
 
+.. _issue 1888: https://github.com/nedbat/coveragepy/issues/1888
 .. _pull 1919: https://github.com/nedbat/coveragepy/pull/1919
 
 

coverage/control.py

@@ -950,6 +950,7 @@ def analysis2(
             analysis.missing_formatted(),
         )
 
+    @functools.lru_cache(maxsize=1)
     def _analyze(self, morf: TMorf) -> Analysis:
         """Analyze a module or file.  Private for now."""
         self._init()
@@ -960,6 +961,20 @@ def _analyze(self, morf: TMorf) -> Analysis:
         filename = self._file_mapper(file_reporter.filename)
         return analysis_from_file_reporter(data, self.config.precision, file_reporter, filename)
 
+    def branch_stats(self, morf: TMorf) -> dict[TLineNo, tuple[int, int]]:
+        """Get branch statistics about a module.
+
+        `morf` is a module or a file name.
+
+        Returns a dict mapping line numbers to a tuple:
+        (total_exits, taken_exits).
+
+        .. versionadded:: 7.7
+
+        """
+        analysis = self._analyze(morf)
+        return analysis.branch_stats()
+
     @functools.lru_cache(maxsize=1)
     def _get_file_reporter(self, morf: TMorf) -> FileReporter:
         """Get a FileReporter for a module or file name."""

coverage/results.py

@@ -231,6 +231,7 @@ def branch_stats(self) -> dict[TLineNo, tuple[int, int]]:
 
         Returns a dict mapping line numbers to a tuple:
         (total_exits, taken_exits).
+
         """
 
         missing_arcs = self.missing_branch_arcs()

tests/test_api.py

@@ -1008,7 +1008,10 @@ def fun1(x):
                 print("done")           # pragma: nocover
 
             def fun2(x):
-                print("x")
+                if x:
+                    print("x")
+                else:
+                    print("not x")
 
             fun2(3)
             """)
@@ -1018,12 +1021,22 @@ def fun2(x):
 
         nums = cov._analyze("missing.py").numbers
         assert nums.n_files == 1
-        assert nums.n_statements == 7
+        assert nums.n_statements == 9
         assert nums.n_excluded == 1
-        assert nums.n_missing == 3
-        assert nums.n_branches == 2
-        assert nums.n_partial_branches == 0
-        assert nums.n_missing_branches == 2
+        assert nums.n_missing == 4
+        assert nums.n_branches == 4
+        assert nums.n_partial_branches == 1
+        assert nums.n_missing_branches == 3
+
+        filename, statements, excluded, missing, missing_formatted = cov.analysis2("missing.py")
+        assert os.path.relpath(filename) == "missing.py"
+        assert statements == [1, 2, 3, 5, 8, 9, 10, 12, 14]
+        assert excluded == [6]
+        assert missing == [2, 3, 5, 12]
+        assert missing_formatted == "2-5, 12"
+
+        branch_stats = cov.branch_stats("missing.py")
+        assert branch_stats == {2: (2, 0), 9: (2, 1)}
 
 
 class TestRunnerPluginTest(CoverageTest):