Description not included by default

[norg]

Bug description

The readme points out that --desc defaults to auto and in json output mode to on, but when passing --desc auto it does not and if --desc is missing at all the description is also missing. It does work for --desc on and also --desc being passed.

Reproduction steps

Run pip audit with different options and compare json output:

• pip-audit -r requirements.txt -f json --desc auto -o /tmp/pipaudit_auto.json
• pip-audit -r requirements.txt -f json --desc on -o /tmp/pipaudit_desc_on.json
• pip-audit -r requirements.txt -f json --desc -o /tmp/pipaudit_desc.json
• pip-audit -r requirements.txt -f json -o /tmp/pipaudit.json

Expected behavior

I would have expected to have descriptions always included, the only debate might be if it should be there if --desc is missing overall.

Screenshots and logs

Platform information

• OS name and version: ArchLinux
• pip-audit version (pip-audit -V): pip-audit 2.4.5
• Python version (python -V or python3 -V): Python 3.10.8
• pip version (pip -V or pip3 -V): ip 22.3 from /usr/lib/python3.10/site-packages/pip (python 3.10)

Additional context

I might be even wrong with my case, so maybe it's just a clarification needed
Thanks for this helpful audit tool!

[woodruffw]

Thanks for the report!

Yes, this is intended behavior. To clarify:

1. --desc auto means "include the description, if it's the default for the selected output format"
2. --desc on means "always include the description, regardless of the format's default"
3. --desc off means "never include the description, regardless of the format's default"

Does that clarify things? If so, I can look into tweaking the README to include some of that.

[woodruffw]

Oh, unless I'm misunderstanding. Are you saying that --desc auto does not produce descriptions in the JSON format?

[norg]

Oh, unless I'm misunderstanding. Are you saying that --desc auto does not produce descriptions in the JSON format?

Yes that's one of the cases where I'm confused about :) Especially with --desc with no additional argument behaving different from the one where auto is added.

[woodruffw]

Whoops, looks like you're totally right: --desc auto is not behaving correctly. Looks like we're doing a comparison wrong there; sorry for the hasty response!

To clarify, here's the intended behavior of --desc:

• --desc: same as --desc on
• --desc on: always emit descriptions, format permitting
• --desc off: never emit descriptions
• --desc auto: emit descriptions if the selected format has descriptions by default

[woodruffw]

I'll have a PR open to fix --desc auto's behavior with the JSON formatter ready in a moment.

[norg]

Thanks for the confirmation. Although I might even argue that --desc should be the same like --desc auto instead of --desc on but at least your list explains why just --desc did work for me :)

[woodruffw]

Although I might even argue that --desc should be the same like --desc auto instead of --desc on but at least your list explains why just --desc did work for me :)

I think we did this because --desc on looks a little strange compared to "idiomatic" CLI design: --desc is a boolean option, so its mere presence should imply on rather than needing a value passed (or a non-on state). But I agree it's a little confusing.

[norg]

Awesome, thanks for the explanation and fix!