COVERAGE_FILE should be a command-line parameter instead.

[nedbat]

Originally reported by Anonymous

---

Hi, Ned. First of all, thank you for this wonderful tool.

In a UNIX environment, I would expect a tool to allow me to specify the output path from the command line, instead of setting it through an environment variable. Much so that I think coverage.py is the first tool I have seen with such behavior. In light of this, I am proposing to remove the COVERAGE_FILE environment variable, and add an option to run subcommand that exactly serves in place of the mentioned environment variable.

Comparing the existing API,

# Regular use
COVERAGE_FILE=my_file coverage run my_program.py

# alternatively
export COVERAGE_FILE=my_file
coverage run my_program.py

# Write to stdout of the process, to enable piping
COVERAGE_FILE=/dev/stdout my_program.py

with my proposal,

# Regular use
coverage run -o my_file my_program.py

# Write to stdout of the process, to enable piping
coverage run -o /dev/stdout my_program.py

I believe the command line argument option is more elegant, and something a programmer would expect. I personally had to search documents on how to specify the output file.

If you think this is a good idea, I am willing to do the work on the codebase to implement this feature.

---

• Bitbucket: https://bitbucket.org/ned/coveragepy/issue/624

[nedbat]

I suppose we could add -o support, though you're the first person to ask for it in a, so I don't see much demand for it.

We are not going to remove the environment variable support. I'm not sure why you would propose to.

Piping to stdout seems like an odd thing to want. I try to discourage people from dealing with the data file directly, so I hope people are not building tools that will read one from stdin.

[nedbat]

Original comment by Cengiz Kaygusuz (Bitbucket: cngkaygusuz, GitHub: cngkaygusuz)

---

I'm the author of the issue. I posted it thinking I was logged in :/

Can't really comment on the demand of other people. Maybe there will be more of such demands in the future, who knows. My specific use case is that I need to run a test suite both in python 2 and python 3, and combine them. To do so, I need to write the output of coverage to two distinct files. Running two commands appended with something like COVERAGE_FILE=my_file felt awkward, hence this proposal.

Co-existing both options would introduce complexity in the codebase with nothing to gain for. Ultimately, env variable and the command line option serve the goal to specify where the output of the tool should be written.

• There will be a need to establish precedence between two options, in case two is used at the same time since undefined behavior should be avoided whenever possible. This is more specification than necessary to achieve the goal.

• Implementations of both, their interactions and code validating their behavior should be included in the codebase. This is more code than necessary to achieve the goal.

• Users need to be made aware of the fact that there exist two options to achieve the same thing with one being precedent to another. Not only I believe this is unnecessary cognitive load, it also means more documentation than necessary to achieve the goal.

I concede that in case the command line option is opted for, both would live in the codebase while env is deprecated, but its ramifications wouldn't be that severe. Yes, there will be more code for a while, but there won't be more specification and documentation.

About piping; I believe you are envisioning a use case like piping the output of the .coverage contents to sed, awk'esque programs that would modify the contents. Piping also serves the convenience of merely handling the data without modifying it. Imagine a use case like a program forks to coverage.py, reads its output from stdout and sends it to a remote server to do further processing. If stdout piping is not available, a programmer would need to create the .coverage file, read its output from the file, and finally clean it up, with all the error handling code present. It is clearly inconvenient.

[nedbat]

@cngkaygusuz Thanks for the explanation.

For your py2/py3 flow, did you try --parallel? It's perfect for your use case. It will choose non-conflicting names automatically, and "coverage combine" will find them automatically.

I appreciate your concern about the extra complexity of having two ways to specify the output file. I value simplicity, but I also value backward compatibility, so it will be a more complex decision.

[cdunklau]

I just ran into this. While the lack of such an option certainly isn't a showstopper, it would be a reasonable addition IMHO. Here's my experience:

I run coverage indirectly via pytest-cov through tox, and my tox conf is set up such that the .coverage data file gets written inside the tox env's temp dir.

During testing, I wanted to get the nice HTML display so I could figure out where my tests were missing, without adding a coverage html run to my test command list. I couldn't just run coverage html since the data file was nested inside the .tox hierarchy, and I didn't want to cd in and out. I looked for a command-line option for the reporter to specify the data file, but was disappointed when I didn't find it.

I wound up using coverage combine .tox/py36/temp and then coverage html, before I found out about the env var.

[earonesty]

see: #802 for a quick fix. there's already an option that works to fix this, but it auto-uses pids (which are nonuniqe) .... which leaves the caller unable to associate a run with the output.

[avylove]

I'd agree this option should exist. The main reason is the first place I went looking when I needed this was coverage run --help. Yes, I can set an environment variable, and that does have value in some cases, but it's neither intuitive, straightforward, nor mentioned where it's consumed.

[nedbat]

Also see #752

[nedbat]

This is implemented in ba884e4.

[nedbat]

This is now released as part of coverage 6.3.