An `--output-format` option for the verdi cli

ltalirz commented 1 year ago

Is your feature request related to a problem? Please describe

Some commands in the verdi cli have a --raw option that hides information intended for interactive use, making it easier to further process the outputs.

This is useful, but the "raw" output is still aiida-specific and requires the user to parse it. We may eventually want to support other output formats, such as JSON / YAML / ... that make it easy for the user to pick out exactly the information they need via cli tools like jq / yq / ...

Describe the solution you'd like

Instead of the binary --raw option, I would suggest to use a --output-format <format> option (name up for discussion), that defaults to something like interactive but can also take other values such as tabular (or raw if you prefer) / json / yaml / ...

The option does not need to be present on every cli command (can be added one by one), and the formats available may depend on the cli command.

Additional context

Discussion in https://github.com/aiidateam/aiida-core/pull/5763#pullrequestreview-1182269512

As an example of a cli that does this, see kubectl

kartikeysaran commented 1 year ago

Hey hi, I am new to the community and would like to contribute on this issue.

sphuber commented 1 year ago

After discussion with the team, here is the proposed solution:

[ ] The --raw option is deprecated. All commands keep it for now but when used, a deprecation message is echoed in the command body.
[ ] It is replaced by the -o/--output-format option. This will be a type=click.Choice option with the default values: ['json', 'yaml', 'tabular', 'raw']. Here tabular is the default and correspond to the current default output of the commands that will get this option. This includes any additional messages and headers of the table. The raw option corresponds to the tabular option but without all additional messages and headers (as the current --raw flag accomplishes). The json and yaml formats will print the output in JSON and YAML, respectively, without any additional messages and no headers.
[ ] There will be a conflict for verdi code list which already has a -o option, but it is already deprecated, so I think we can remove it. It was added in https://github.com/aiidateam/aiida-core/pull/5750 and released with v2.1.0
[ ] There is already the aiida.cmdline.params.options.main.DICT_FORMAT option that does something similar to what the propose -o/--output-format option would do. We should confirm that the former can be replaced by the new option, so as not to end up with two different but equivalent options.

ltalirz commented 1 year ago

Fully support this proposal.

Maybe one small suggestion would be to think about whether the name tabular is generic enough to fit the current default format for all cli commands that may end up using the --output option (e.g. some default output may be interspersed with info messages to the user). Perhaps something more generic like text may be more widely applicable.

There is already the aiida.cmdline.params.options.main.DICT_FORMAT option that does something similar to what the propose -o/--output-format option would do. We should confirm that the former can be replaced by the new option, so as not to end up with two different but equivalent options.

Good catch. Looks to me like this option mainly supports json (with datetime decoding) and yaml. Would be interesting to know what the use case was for the "expanded" yaml format with default_flow_style=False (I am not aware of a use case and would suggest we drop this).

aiidateam / aiida-core