python --help output is too long #90300

merwok · 2021-12-20T23:43:16Z

BPO	46142
Nosy	@warsaw, @vstinner, @merwok, @serhiy-storchaka, @eryksun
PRs	gh-90300: split --help output into separate options #30331

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Linked PRs:

gh-90300: Reformat the Python CLI help output #93415

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-12-20.23:43:15.950>
labels = ['interpreter-core', 'type-feature', '3.11']
title = 'python --help output is too long'
updated_at = <Date 2022-01-12.01:45:18.299>
user = 'https://github.com/merwok'

bugs.python.org fields:

activity = <Date 2022-01-12.01:45:18.299>
actor = 'eric.araujo'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Interpreter Core']
creation = <Date 2021-12-20.23:43:15.950>
creator = 'eric.araujo'
dependencies = []
files = []
hgrepos = []
issue_num = 46142
keywords = ['patch']
message_count = 15.0
messages = ['408981', '408982', '409449', '409450', '409470', '409483', '409738', '409890', '409928', '410052', '410203', '410207', '410238', '410239', '410378']
nosy_count = 5.0
nosy_names = ['barry', 'vstinner', 'eric.araujo', 'serhiy.storchaka', 'eryksun']
pr_nums = ['30331']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue46142'
versions = ['Python 3.11']

Linked PRs

merwok · 2021-12-20T23:43:16Z

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!

merwok · 2021-12-20T23:44:11Z

Forgot to quote -X help to print help about X options.

merwok · 2022-01-01T04:40:17Z

Do people think the man page should be shortened too?

serhiy-storchaka · 2022-01-01T06:58:46Z

I think that the man page should contain all details related to the CLI (and may be even some examples).

merwok · 2022-01-01T18:47:28Z

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?

merwok · 2022-01-02T01:15:00Z

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.

vstinner · 2022-01-05T09:09:30Z

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

merwok · 2022-01-06T17:51:03Z

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?

vstinner · 2022-01-06T21:08:10Z

"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

merwok · 2022-01-07T22:45:48Z

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?

vstinner · 2022-01-10T11:45:59Z

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.

eryksun · 2022-01-10T12:30:18Z

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.

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.

merwok · 2022-01-10T18:19:31Z

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.

merwok · 2022-01-10T18:20:57Z

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 :)

merwok · 2022-01-12T01:45:18Z

The PR now has --help-env, --help-xoptions and --help-all !

merwok · 2022-05-25T13:26:24Z

I have extracted some bugfixes to ticket #93217

Make --help output shorter and add new help options. --help-env, --help-xoptions and --help-all command-line options are added to complement --help.

…0331) Make --help output shorter and add new help options. --help-env, --help-xoptions and --help-all command-line options are added to complement --help. (cherry picked from commit 8aa9d40) Co-authored-by: Éric <earaujo@caravan.coop>

…116765) (GH-116797) (GH-116803) (cherry picked from commit fc4d5fd) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> (cherry picked from commit 19ac28b)

* 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 * remove the ending period in single-sentence descriptions Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

…15853) * 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 * remove the ending period in single-sentence descriptions (cherry picked from commit b85572c) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

…17022) * 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 * remove the ending period in single-sentence descriptions (cherry picked from commit b85572c) Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

…honGH-115853) (pythonGH-117022) * 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 * remove the ending period in single-sentence descriptions (cherry picked from commit b85572c) (cherry picked from commit 4be9fa8) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

…ython CLI help Fix error introduced in 4be9fa8.

…CLI help (GH-117035) Fix error introduced in 4be9fa8.

…17022) (GH-117034) * 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 * remove the ending period in single-sentence descriptions (cherry picked from commit b85572c) (cherry picked from commit 4be9fa8) Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

* Fix the description of the "-b" option. * Add references to environment variables for "-s" and "-X dev" options.

…I help (pythonGH-116739)

…hon CLI help (pythonGH-116756)

…onGH-116765)

* 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 * remove the ending period in single-sentence descriptions Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

* Fix the description of the "-b" option. * Add references to environment variables for "-s" and "-X dev" options.

…I help (pythonGH-116739)

…hon CLI help (pythonGH-116756)

…onGH-116765)

* 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 * remove the ending period in single-sentence descriptions Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

* Fix the description of the "-b" option. * Add references to environment variables for "-s" and "-X dev" options.

…I help (pythonGH-116739)

…hon CLI help (pythonGH-116756)

…onGH-116765)

* 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 * remove the ending period in single-sentence descriptions Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

merwok added 3.11 only security fixes type-feature A feature request or enhancement labels Dec 20, 2021

merwok added interpreter-core (Objects, Python, Grammar, and Parser dirs) labels Dec 20, 2021

ezio-melotti transferred this issue from another repository Apr 10, 2022

merwok added the 3.12 bugs and security fixes label May 25, 2022

merwok linked a pull request May 25, 2022 that will close this issue

gh-90300: split --help output into separate options #30331

Merged

This was referenced May 25, 2022

gh-90300: split --help output into separate options #30331

Merged

Minor issues in python --help and man page #93217

Closed

merwok closed this as completed in #30331 Jun 1, 2022

merwok added a commit that referenced this issue Jun 1, 2022

gh-90300: split --help output into separate options (#30331)

8aa9d40

Make --help output shorter and add new help options. --help-env, --help-xoptions and --help-all command-line options are added to complement --help.

bedevere-app bot mentioned this issue Mar 14, 2024

[3.11] gh-90300: Fix undocumented envvars in the Python CLI help (GH-116765) (GH-116797) #116803

Merged

bedevere-app bot mentioned this issue Mar 19, 2024

[3.12] gh-90300: Improve the Python CLI help output (GH-115853) #117022

Merged

merwok assigned serhiy-storchaka Mar 19, 2024

bedevere-app bot mentioned this issue Mar 19, 2024

[3.11] gh-90300: Improve the Python CLI help output (GH-115853) (GH-117022) #117034

Merged

serhiy-storchaka added a commit to serhiy-storchaka/cpython that referenced this issue Mar 19, 2024

[3.12] pythongh-90300: Remove reference to PYTHON_FROZEN_MODULES in P…

100ff34

…ython CLI help Fix error introduced in 4be9fa8.

bedevere-app bot mentioned this issue Mar 19, 2024

[3.12] gh-90300: Remove reference to PYTHON_FROZEN_MODULES in Python CLI help #117035

Merged

serhiy-storchaka added a commit that referenced this issue Mar 19, 2024

[3.12] gh-90300: Remove reference to PYTHON_FROZEN_MODULES in Python …

0325a8a

…CLI help (GH-117035) Fix error introduced in 4be9fa8.

serhiy-storchaka closed this as completed Mar 19, 2024

vstinner pushed a commit to vstinner/cpython that referenced this issue Mar 20, 2024

pythongh-90300: Fix cmdline.rst (pythonGH-116721)

83ab92b

* Fix the description of the "-b" option. * Add references to environment variables for "-s" and "-X dev" options.

vstinner pushed a commit to vstinner/cpython that referenced this issue Mar 20, 2024

pythongh-90300: Sort the -X options and some envvars in the Python CL…

5877dc9

…I help (pythonGH-116739)

vstinner pushed a commit to vstinner/cpython that referenced this issue Mar 20, 2024

pythongh-90300: Document equivalent -X options for envvars in the Pyt…

f58f553

…hon CLI help (pythonGH-116756)

vstinner pushed a commit to vstinner/cpython that referenced this issue Mar 20, 2024

pythongh-90300: Fix undocumented envvars in the Python CLI help (pyth…

2a12032

…onGH-116765)

adorilson pushed a commit to adorilson/cpython that referenced this issue Mar 25, 2024

pythongh-90300: Fix cmdline.rst (pythonGH-116721)

12bfd4f

* Fix the description of the "-b" option. * Add references to environment variables for "-s" and "-X dev" options.

adorilson pushed a commit to adorilson/cpython that referenced this issue Mar 25, 2024

pythongh-90300: Sort the -X options and some envvars in the Python CL…

37f82b2

…I help (pythonGH-116739)

adorilson pushed a commit to adorilson/cpython that referenced this issue Mar 25, 2024

pythongh-90300: Document equivalent -X options for envvars in the Pyt…

0c1983b

…hon CLI help (pythonGH-116756)

adorilson pushed a commit to adorilson/cpython that referenced this issue Mar 25, 2024

pythongh-90300: Fix undocumented envvars in the Python CLI help (pyth…

bad4a74

…onGH-116765)

diegorusso pushed a commit to diegorusso/cpython that referenced this issue Apr 17, 2024

pythongh-90300: Reformat the Python CLI help output (pythonGH-93415)

58468b8

diegorusso pushed a commit to diegorusso/cpython that referenced this issue Apr 17, 2024

pythongh-90300: Fix cmdline.rst (pythonGH-116721)

de10c6d

* Fix the description of the "-b" option. * Add references to environment variables for "-s" and "-X dev" options.

diegorusso pushed a commit to diegorusso/cpython that referenced this issue Apr 17, 2024

pythongh-90300: Sort the -X options and some envvars in the Python CL…

ce7e8f7

…I help (pythonGH-116739)

diegorusso pushed a commit to diegorusso/cpython that referenced this issue Apr 17, 2024

pythongh-90300: Document equivalent -X options for envvars in the Pyt…

f00d12e

…hon CLI help (pythonGH-116756)

diegorusso pushed a commit to diegorusso/cpython that referenced this issue Apr 17, 2024

pythongh-90300: Fix undocumented envvars in the Python CLI help (pyth…

9156c6f

…onGH-116765)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

python --help output is too long #90300

python --help output is too long #90300

merwok commented Dec 20, 2021 •

edited by bedevere-app bot

merwok commented Dec 20, 2021

merwok commented Dec 20, 2021

merwok commented Jan 1, 2022

serhiy-storchaka commented Jan 1, 2022

merwok commented Jan 1, 2022

merwok commented Jan 2, 2022

vstinner commented Jan 5, 2022

merwok commented Jan 6, 2022

vstinner commented Jan 6, 2022

merwok commented Jan 7, 2022

vstinner commented Jan 10, 2022

eryksun commented Jan 10, 2022

merwok commented Jan 10, 2022

merwok commented Jan 10, 2022

merwok commented Jan 12, 2022

merwok commented May 25, 2022 •

edited

python --help output is too long #90300

python --help output is too long #90300

Comments

merwok commented Dec 20, 2021 • edited by bedevere-app bot

Linked PRs

merwok commented Dec 20, 2021

merwok commented Dec 20, 2021

merwok commented Jan 1, 2022

serhiy-storchaka commented Jan 1, 2022

merwok commented Jan 1, 2022

merwok commented Jan 2, 2022

vstinner commented Jan 5, 2022

merwok commented Jan 6, 2022

vstinner commented Jan 6, 2022

merwok commented Jan 7, 2022

vstinner commented Jan 10, 2022

eryksun commented Jan 10, 2022

merwok commented Jan 10, 2022

merwok commented Jan 10, 2022

merwok commented Jan 12, 2022

merwok commented May 25, 2022 • edited

merwok commented Dec 20, 2021 •

edited by bedevere-app bot

merwok commented May 25, 2022 •

edited