proposing new --format=<format> --out-file=<file.ext> feature

[memsharded]

Changelog: Feature: Allow defining --out-file=file.ext instead of --format=ext > file.ext to write to files directly and avoid issues with redirects.
Docs: https://github.com/conan-io/docs/pull/XXXX

This would solve issues with stdout/stderr redirects and potential pollution, while not using new arguments, not breaking existing code and allow easy introduction to existing formatters.

Close #17462

[czoido]

Related to #17462

[AbrilRBS]

Question, otherwise looks good, but I think checking with the team in as look-into is a good idea first, good call

[AbrilRBS]

There are a few commands whose formatter calls cli_out_write multiple times in a row.

Should we convert those to only call it once, or should this new functionality support appending?

[memsharded]

Good catch. Not sure to be honest, I tend to think to re-write the formatter to include only 1 call, but there are some case that use colors and that would be a bit less elegant, but still doable

[czoido]

I'm not sure I prefer this over having a new --output-file argument to specify the file... I was thinking... what about something at the midpoint like: --format="json:myfile.json" ?

[memsharded]

I'm not sure I prefer this over having a new --output-file argument to specify the file... I was thinking... what about something at the midpoint like: --format="json:myfile.json" ?

Yes, I like that midpoint. I thought about the extra argument, but that further pollutes the CLI, like --format=json --output-file=graph.json is like "Hey, I am already telling you in the filename that I want a json file, don't be that dumb".

But if you think the --output-file is better, we can do it too, I am not strongly opposed either.

[perseoGI]

I agree with having another CLI option, it might be confusing that the fact of defining an output format could also lead to defining the output file.

In conanlint we have made something similar:

Also, it may cause issues with future formats which could contain a dot delimiter.

All in all, the feature is a good one! Some console redirections are not always consistent.
(In the linter I add this option to allow progress bar + redirection to file)

[czoido]

I'm not sure I prefer this over having a new --output-file argument to specify the file... I was thinking... what about something at the midpoint like: --format="json:myfile.json" ?

Yes, I like that midpoint. I thought about the extra argument, but that further pollutes the CLI, like --format=json --output-file=graph.json is like "Hey, I am already telling you in the filename that I want a json file, don't be that dumb".

But if you think the --output-file is better, we can do it too, I am not strongly opposed either.

The main thing for me is to maintain the concept of a formatter. A --format=file.json argument doesn’t feel like a formatter anymore. The original idea was that the formatter should define how the output is formatted (HTML, JSON, etc.), not where it’s written. So, for me, any idea that maintains in some way the meaning of the formatter is ok.

[memsharded]

Looking good

[memsharded]

This should be injected automatically and conditionally to the existence of formatters together with the definition of the --format argument. There cannot be a --out-file without a --format definition.

[czoido]

Finally, my proposal is to add the --out-file always, to enable users do for example
conan config home --out-file=file.ext
and it uses the text formatter that is the one by default. Because in the end, there's always a formatter there that is the text one even if it does not show in the --help, but let's discuss about this with the team.

EDIT: Looks like this works in the test suite but not in my CLI, I'm leaving the PR in draft until I understand why.

[czoido]

I'm leaving this as draft, apparently these lines:

conan/conan/api/output.py

Lines 298 to 300 in 003e2cf

	colorama.deinit()
	sys.stdout.write(data)
	colorama.reinit()

are making that this approach redirecting the stdout do not work on a real console but they do work on testing because we capture the streams. I'll investigate a solution that also prevent #17245 to not happen any more.