Coverage.py [path] configuration

@nedbat
I was reading about [path] section of .coveragerc
https://coverage.readthedocs.io/en/latest/config.html#paths

[paths]
source =
    src/
    /jenkins/build/*/src
    c:\myproj\src

What does
“The value is a list of strings. When combining data with the combine command, two file paths will be combined if they start with paths from the same list.”
mean? It’s a bit ambiguous

  1. The two file path, I’m assuming it refers to /jenkins/build/*/src and c:\myproj\src.
  2. “Two file paths will be combined” that means “coverage report from the two file paths will be combined”?

Thanks, the text could be more explicit. How is this?

The combine command uses this list to decide when different source file paths refer to the same file. Two source files will be considered the same and their data will be combined if their paths start with paths from the same list.

Thank you for replying Ned.

Q1
Just to be clear, it doesn’t combine the data for the files in the first path right?
For example,

[paths]
source =
    src/

    /jenkins/build/*/src
    c:\myproj\src 
    c:\myproj2\src  
    c:\myproj3\src 

  • As far as I know, it combines coverage data of files in /jenkins/build/*/src, c:\myproj\src, c:\myproj2\src, c:\myproj3\src, but NOT src/.
  • The combined coverage data is reported against the files in src/ ONLY if the same file exists in the src/.
  • If there is extra file hello.py in let’s say in c:\myproj\src but isn’t in src/. That is reported independently.

Q2

Two source files will be considered the same and their data will be combined if their paths start with paths from the same list.

I don’t really understand the phrase “if their paths start with paths from the same list” (and it’s also written like that in the documentation). Is there a detail I’m missing?

Isn’t it as simple as
“Except for the first path (src/), all the source files in the all the other paths listed will be considered the same and their coverage data will be combined”?

It will be easier to talk about mapping file data than combining files. Data from a file in /jenkins/build/*/src, c:\myproj\src, c:\myproj2\src, or c:\myproj3\src will be treated as if it was data for the corresponding file in src/ .

This mapping happens during the coverage combine operation and also when reporting from a single data file, since a single data file can have data from many source files.

Yes.

Yes.

I think the overlooked detail is that the [paths] section can have more than one list, although in practice it almost never does.

Maybe this: “Source files in each directory will be mapped to the corresponding file in the first entry”? There’s no real need to exclude the first path: it’s correspondence mapping is the identity. If you want to explicitly exclude it, then: “Source files in directories after the first will be mapped to the corresponding file in the first entry.”

Thank you for your effort to reply in detailed manner. I think I have deeper understanding when you explained with “mapping” analogy.

Sorry I think I explained the question 2 badly.
I’m aware you can have multiple lists under [path].

I was more puzzled about
“if their paths start with paths" part of the phrase “if their paths start with paths from the same list”.
Like what does that even mean? Path starts with path?
It sounds like they have to share a common starting path from the same list.
Sort of like this:

[paths]
sourceList =
    src/

    commonStartingFolder/jenkins/build/*/src
    commonStartingFolder/myproj/src 
    commonStartingFolder/myproj2/src  
    commonStartingFolder/myproj3/src 

But obviously that’s not true. You don’t have to share the common starting directory.
I don’t mean to sound pedantic, but I was reading the documentation this specific phrase many times but it just didn’t register into my brain.