Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

python --help output is too long #90300

Open
merwok opened this issue Dec 20, 2021 · 18 comments · Fixed by #30331 or #93413
Open

python --help output is too long #90300

merwok opened this issue Dec 20, 2021 · 18 comments · Fixed by #30331 or #93413
Labels
3.11 bug and security fixes 3.12 bugs and security fixes 3.13 new features, bugs and security fixes interpreter-core (Objects, Python, Grammar, and Parser dirs) type-feature A feature request or enhancement

Comments

@merwok
Copy link
Member

merwok commented Dec 20, 2021

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:

    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
    Copy link
    Member Author

    merwok commented Dec 20, 2021

    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 merwok added 3.11 bug and security fixes type-feature A feature request or enhancement labels Dec 20, 2021
    @merwok
    Copy link
    Member Author

    merwok commented Dec 20, 2021

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

    @merwok merwok added interpreter-core (Objects, Python, Grammar, and Parser dirs) labels Dec 20, 2021
    @merwok
    Copy link
    Member Author

    merwok commented Jan 1, 2022

    Do people think the man page should be shortened too?

    @serhiy-storchaka
    Copy link
    Member

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

    @merwok
    Copy link
    Member Author

    merwok commented Jan 1, 2022

    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
    Copy link
    Member Author

    merwok commented Jan 2, 2022

    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
    Copy link
    Member

    vstinner commented Jan 5, 2022

    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
    Copy link
    Member Author

    merwok commented Jan 6, 2022

    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
    Copy link
    Member

    vstinner commented Jan 6, 2022

    "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
    Copy link
    Member Author

    merwok commented Jan 7, 2022

    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
    Copy link
    Member

    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
    Copy link
    Contributor

    eryksun commented Jan 10, 2022

    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.

    @merwok
    Copy link
    Member Author

    merwok commented Jan 10, 2022

    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
    Copy link
    Member Author

    merwok commented Jan 10, 2022

    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
    Copy link
    Member Author

    merwok commented Jan 12, 2022

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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @merwok merwok added the 3.12 bugs and security fixes label May 25, 2022
    @merwok merwok linked a pull request May 25, 2022 that will close this issue
    @merwok
    Copy link
    Member Author

    merwok commented May 25, 2022

    I have extracted some bugfixes to ticket #93217

    merwok added a commit that referenced this issue Jun 1, 2022
    Make --help output shorter and add new help options.
    
    --help-env, --help-xoptions and --help-all command-line options are
    added to complement --help.
    miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jun 1, 2022
    …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>
    @merwok merwok reopened this Jun 1, 2022
    serhiy-storchaka added a commit to serhiy-storchaka/cpython that referenced this issue Jun 1, 2022
    * All lines are now shorter than 80 columns
    * All wrapped lines use the same identation
    * Remove empty lines between -X options
    * Output only one empty line between sections in --help-all
    miss-islington added a commit that referenced this issue Jun 14, 2022
    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>
    ambv added a commit that referenced this issue Aug 12, 2022
    @erlend-aasland erlend-aasland added the 3.13 new features, bugs and security fixes label Jan 5, 2024
    @erlend-aasland
    Copy link
    Contributor

    @merwok, you reopened this in 2022; what is the remaining actionable items?

    @merwok
    Copy link
    Member Author

    merwok commented Jan 5, 2024

    There is an open PR from Serhiy with some discussion / disagreement on reformatting IIRC.

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.11 bug and security fixes 3.12 bugs and security fixes 3.13 new features, bugs and security fixes interpreter-core (Objects, Python, Grammar, and Parser dirs) type-feature A feature request or enhancement
    Projects
    None yet
    5 participants