gh-90300: Improve the Python CLI help output

[serhiy-storchaka]

• document equivalent command-line options for all environment variables
• document equivalent environment variables for all command-line options
• reduce the size of variable and option descriptions to minimum
• sort the lists of -X options and variables that have equivalent command-line options
• remove the ending period in single-sentence descriptions

• Issue: python --help output is too long #90300

---

📚 Documentation preview 📚: https://cpython-previews--115853.org.readthedocs.build/

[serhiy-storchaka]

The CLI help should be short. It is a list of options and environment variables with short descriptions to have some idea what they are about. Ideally, every option description should be a single line. If you want to learn details, you should read the documentation. The CLI help is just to remind you exact names and format of some options and environment variables.

[merwok]

I’m not sure if I agree with that, or if it’s the consensus within python-dev.
Could you post your message to the issue at least, or even discuss?

[serhiy-storchaka]

What can be done so that this PR does not hang for another 2 years like #93415? It is painful and errorprone to resolve merge conflicts after adding new options and environment variables.

[merwok]

@erlend-aasland, @AlexWaygood and @hugovk agree with you on the ticket.

To me this needed a little discussion – I don’t think that there is a current agreement that help should be more concise than (relatively) comprehensive. But this is only an interpreter option, not the public API, so it would be fine to follow EAFP and go ahead! And it’s true that people probably use the online docs more than the command-line, and that we have help texts duplicated in three places – one removed with this change. 🚀

[erlend-aasland]

There's always the possibility of opening a topic on Discourse, so we can have a broader discussion. I think I want to read up some more on the CLI guide Hugo linked to in the issue, before I decide.

[ericsnowcurrently]

FTR, this is a follow-up to gh-93415.

[serhiy-storchaka]

Opened a topic: https://discuss.python.org/t/and-again-about-the-python-cli-help/48401.

[hugovk]

It would be easier to review if the bullet points were in split into separate (followup) PRs. For example:

• sort the lists of -X options and variables that have equivalent command-line options
• remove the ending period in single-sentence descriptions

I think I could review and approve those as a single PR immediately, and it'd make followups smaller and easier (and quicker 🤞) to review.

[serhiy-storchaka]

The part of the problem is that not for all options and variables the equivalent is currently specified, and that there are two lists for environment variables. So the change may require adding references to options and variables (which may increase the size of the description, and may not fit the style of the verbose description) and moving variables from one list to other. Is it okay?

[serhiy-storchaka]

See #116739 for a simple step.

[serhiy-storchaka]

Next step: #116756.

[serhiy-storchaka]

Next step: #116765.

[serhiy-storchaka]

Is it enough? What is left:

• shortening long descriptions
• adding equivalent envvar references (this may require shortening the descriptions)
• other minor changes, including removing the ending period in single-sentence descriptions

[hugovk]

Thanks, much easier to review now :)

Looks good, a few suggestions.

[miss-islington-app]

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker b85572c47dc7a8c65fc366a87a3660fc7a3ed244 3.12

[miss-islington-app]

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker b85572c47dc7a8c65fc366a87a3660fc7a3ed244 3.11

[bedevere-app]

GH-117022 is a backport of this pull request to the 3.12 branch.