classification
Title: python --help output is too long
Type: enhancement Stage: patch review
Components: Interpreter Core Versions: Python 3.11
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: barry, eric.araujo, eryksun, serhiy.storchaka, vstinner
Priority: normal Keywords: patch

Created on 2021-12-20 23:43 by eric.araujo, last changed 2022-01-12 01:45 by eric.araujo.

Pull Requests
URL Status Linked Edit
PR 30331 open eric.araujo, 2022-01-02 05:58
Messages (15)
msg408981 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2021-12-20 23:43
From Serhiy in https://mail.python.org/archives/list/python-dev@python.org/thread/QUUBM7DGSXYWBOLZNWOSCQUDALWJIYZF/ :

    The output of "python -h" is 104 lines long now. It was only 51 lines in
    3.6. 35% of it is about the -X option, and 30% about environment
    variables. Also some lines in the -X option description are too long
    (102 columns). Both topics are "advanced" and mostly interested for
    debugging. I suggest to move them out of the main help output.  […]

Guido:

    -X opt : implementation-specific option; use -X help to list options.

    We could also see if we can put the help text for each of the supported -X
    flags in the table defining these flags […]

GvR again:

    --help-env […] prints info about env vars (new flag)


I would enjoy trying to make a patch around next week!
msg408982 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2021-12-20 23:44
Forgot to quote  -X help  to print help about X options.
msg409449 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-01-01 04:40
Do people think the man page should be shortened too?
msg409450 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2022-01-01 06:58
I think that the man page should contain all details related to the CLI (and may be even some examples).
msg409470 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-01-01 18:47
Question about the implementation:
I’ve found the parsing of command-line params in Python/initconfig.c and Python/preconfig.c.
Help is handled in initconfig, X options in preconfig.

A) could add a value to the right struct for "-X help", set it in preconfig, handle it in initconfig (by printing X options help and exiting, maybe reusing the existing print help function or writing a very similar one next to it)
B) or detect the option in preconfig, print and exit right there

Which option is best?
msg409483 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-01-02 01:15
It seems that preconfig is only for some options that change fundamental behaviour (isolated mode, default encoding), so I should be able to detect and handle '-X help' in initconfig.
msg409738 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2022-01-05 09:09
initconfig.c parses all -X options. preconfig.c also checks for a few specific -X options which are also checked in initconfig.c.

My notes on parsing command line options:
https://pythondev.readthedocs.io/pyconfig.html#add-a-new-command-line-option
msg409890 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-01-06 17:51
Victor said on github that he would prefer `--help-xoptions` to `-X help`.  It would align with `--help` and `--help-env`, but not with other `-X abc` options.  I think that `--help-X` may be better, as it uses the same form (`X`) rather than the non-word `xoptions`.

What do people think?
msg409928 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2022-01-06 21:08
"xoptions" name comes from sys._xoptions (Python) and PyConfig.xoptions (C). Oh, sys._xoptions is a private API... but it's mentioned in the -X documentation:
https://docs.python.org/3/using/cmdline.html#cmdoption-X
msg410052 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-01-07 22:45
I hard forgotten this bit in the email thread:

Serhiy: What do you think about -hh (and maybe —help-full) printing full help?

Guidp: Is there enough of a use case for this to bother?

Barry: Maybe not.  I’d say if it was easy to implement, why not, but if it’s a pain, don't bother.


The option parsing code is easy to edit, and the function would only need to call the other usage functions with a blank line inbetween.  Should I add it?
msg410203 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2022-01-10 11:45
> Serhiy: What do you think about -hh (and maybe —help-full) printing full help?

Do you know other projects which dump the full help into stdout when asking for the "full help"?

For me, the best CLI is "git help", "git help init", etc. "git help init" opens "man git-init". I don't know its behaviour on platforms without manpage support, like Windows.
msg410207 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2022-01-10 12:30
> Do you know other projects which dump the full help into stdout 
> when asking for the "full help"?

`ps --help` lists sections "<simple|list|output|threads|misc|all>". The "--help all" output is all sections, but truly all help is only available via `man ps`.

> For me, the best CLI is "git help", "git help init", etc. "git help 
> init" opens "man git-init". I don't know its behaviour on platforms 
> without manpage support, like Windows.

With Git for Windows, `git help <command>` opens an HTML formatted manual page in a web browser. It should use a new tab in an existing browser window.
msg410238 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-01-10 18:19
> For me, the best CLI is "git help", "git help init", etc.

I don’t think that prior art applies here, as python does not have subcommands.  `--help` and `--help-env` are straightforward, `-X help` is a bit unusual but at least it’s part of the optional `-X` options, `--help-full` or `-all` would be way to preserve the behaviour of printing full usage with one option.
msg410239 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-01-10 18:20
BTW on the PR I am asking for help with string formatting, to print an invalid X option (a wchar_t string) using the PyStatus API (needs char).  Help from a proper C programmer would be appreciated :)
msg410378 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-01-12 01:45
The PR now has --help-env, --help-xoptions and --help-all !
History
Date User Action Args
2022-01-12 01:45:18eric.araujosetmessages: + msg410378
2022-01-10 18:20:57eric.araujosetmessages: + msg410239
2022-01-10 18:19:31eric.araujosetmessages: + msg410238
2022-01-10 12:30:17eryksunsetnosy: + eryksun
messages: + msg410207
2022-01-10 11:45:59vstinnersetmessages: + msg410203
2022-01-07 22:45:48eric.araujosetmessages: + msg410052
2022-01-06 21:08:09vstinnersetmessages: + msg409928
2022-01-06 17:51:02eric.araujosetmessages: + msg409890
2022-01-05 09:09:29vstinnersetmessages: + msg409738
2022-01-02 05:58:27eric.araujosetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request28546
2022-01-02 01:15:00eric.araujosetmessages: + msg409483
2022-01-01 18:47:28eric.araujosetnosy: + vstinner
messages: + msg409470
2022-01-01 06:58:46serhiy.storchakasetmessages: + msg409450
2022-01-01 04:40:17eric.araujosetmessages: + msg409449
2021-12-21 00:24:46barrysetnosy: + barry
2021-12-20 23:44:11eric.araujosetmessages: + msg408982
components: + Interpreter Core
2021-12-20 23:43:15eric.araujocreate