And again about the Python CLI help

Core Development
1

2 years ago I opened a topic about the python -h output:
https://mail.python.org/archives/list/python-dev@python.org/thread/QUUBM7DGSXYWBOLZNWOSCQUDALWJIYZF/

The problem was that it has grown to undesirable proportions. Too many lines, most of them were about the -X options and environment variables (which is something an advanced topic), some lines were too long, and the formatting in general was inconsistent. The general consensus was to split the output on several parts, output only info about options without the -X suboptions by default, and add options --help-env, --help-xoptions and --help-all.

The initial part of these changes (splitting out the output on parts) was done by @merwok. It did not fix inconsistent formatting and left some line overflows, so a follow-up PR for a clean reformat was created by me on the same day. For some reason, it hung for 1.5 years until it was merged. After that I created the third part – a PR that rewrites some descriptions (previous changes only moved them here and there).

The descriptions of different options and environment variables is not uniform. For old options and environment variables it was very brief – one or two lines, omitting all except the main. For the newest options and environment variables (like -X dev and PYTHONNODEBUGRANGES) it is unnecessary verbose, including remark about the rationale of these features. Note that the detailed description are available in the main Python documentation, and -X dev have even its own page.

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.

I opened this topic because not all core developers agree with the above.

5 Likes
2

CLI help is a form of documentation. We try to follow Diátaxis for docs.python.org, we can use it for --help.

One Diátaxis guideline is to work one step at a time. Iteratively, in small chunks. This should help avoid things hanging around for 1.5 years.

On the issue, I wrote:

The Command Line Interface Guidelines have a detailed section on help text:

(They suggest a concise help by default, when -h or --help not passed. This does not apply to Python.)

They suggest showing full help when -h or --help is passed, including:

  • link to web version of the docs
  • lead with examples
  • display most common flags/options at the start
  • use formatting for readability

I would especially like us to use bold/colour formatting, which should be controllable via the new colour env vars: https://docs.python.org/3.13/using/cmdline.html#using-on-controlling-color

We could aim in this direction, in small steps.

Yes, my general opinion is the help should be concise but not cramped. Whitespace helps (this is Python ;). I think argparse-style help is more readable than python --help right now.

Back to this PR. It doesn’t affect whitespace much. It aims to help showing the common options first. :+1:

On the PR, I wrote:

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 :crossed_fingers:) to review.

3 Likes