[internal] Make missing arc fragments useful to more report generators

[zackw]

This is following on from the discussion near the end of #1846. parser.py has a sophisticated algorithm for characterizing branch arc destinations - ordinary if statement, exiting the function, exiting a with clause, etc. - but the way it's presently implemented, it is only useful to the HTML report generator. To make it useful to more reporters, I'd like to ask for the following:

• A new FileReporter API, analogous to the existing missing_arc_description function, that tersely describes the destination of an arc without any leading text about whether it was or wasn't executed. For ordinary if destinations, it'd be most useful to get just "line {lineno}". For function returns, "return from {self.name!r}". And so on.
• Similarly, an exposed API that describes the circumstances where an arc would fail to have been taken - the existing "condition on line {lineno} was never {true/false}", "pattern on line {lineno} {always/never} matched" texts - in isolation, without the rest of the missing_arc_description verbiage, would be useful (not directly to the LCOV reporter, but I bet someone will want it eventually).
• And finally, an exposed API that tells you whether an arc should be ignored, whether or not it was ever taken or not taken. This is for things like if any(pred(x) for x in xs), where the uninteresting exit arc from the generator expression gets filtered out of the HTML report by (it seems) always getting executed, but a reporter like LCOV that needs to talk about all the arcs has no good way to tell. (Split to #1852.)

[nedbat]

I need to understand more about what you are requesting. I've been de-emphasizing arcs to focus more on true branches. I haven't checked the code, but I thought exit arcs from generator expressions were already removed.

[zackw]

You know what, this should have been two separate issues. I've split the exit-arcs-from-generator-expressions item to #1852 and I hope I've explained it better there. Let's focus this issue on the first two items.

The code at stake for the first two items is like this

def fn(pred):
    if pred:
        print("yes")
fn(True)
fn(False)

The LCOV reporter (using the code in #1851) currently generates these BRDA: records for this code:

BRDA:2,0,to line 3,1
BRDA:2,0,to exit,1

I want to make "to exit" be "return from 'fn'" instead, the way the HTML reporter would do it. But the problem is that the HTML reporter gets the text "return from 'fn'" from missing_arc_description, which produces a much longer sentence saying that the arc wasn't executed and why. The LCOV reporter only wants the "return from 'fn'" part, and it wants it whether or not the arc was executed, and I can't tell if it's legit to call missing_arc_description at all on arcs that were executed.

So I am suggesting there should be an API more like the internal missing_arc_fragments but exposed (to report generators), and which works on any arc, and uses words that don't imply anything about whether or not the arc was executed. The LCOV reporter only wants descriptions for arc destinations, but I can imagine other report generators might have a use for text describing when arcs would be executed, like the existing "cause" slot of a TArcFragment but reworded.

[nedbat]

I've added an arc_description method that I think does what you need, in branch https://github.com/nedbat/coveragepy/tree/nedbat/arc-description-for-1850. Try it out and let me know.

[zackw]

Thanks! I rebased https://github.com/MillionConcepts/coveragepy-fixes/tree/lcov-report-improvements-2 on top of https://github.com/nedbat/coveragepy/tree/nedbat/arc-description-for-1850 and adjusted the code in lcovreport.py to use arc_description. It definitely makes things simpler in the reporter to have this API available. However, it doesn't seem to work for exit arcs. I'm getting "jump to line -1" instead of "return from function 'foo'" consistently. It's supposed to be called via the FileReporter for the source file, right? That wasn't 100% clear to me.

The current batch of test failures for #1851 are because of this (and also #1852).

[nedbat]

I've made a pull request into your branch that fixes things.

[zackw]

Have now gotten around to checking your PR; it looks good on my end, let's see how it does in CI...

[nedbat]

Fixed in commit 6118798a5702a90dd89b726d44d4696bb0f82eec.

[nedbat]

This is now released as part of coverage 7.6.2.