Click: Document how to show default values for options in helptext

[stevekuznetsov]

It would be nice if I defined an option:

@click.command(
    help='Command helptext'
)
@click.option(
    '--test',
    default='foobar'
    help='Option helptext
)
def cli(test):
    pass

I would get an output that defined the default value of options:

$ cli --help
Usage: cli [OPTIONS]

  Command helptext

Options:
  --test TEXT   Option helptext. Default: 'foobar'
  --help        Show this message and exit.

[stevekuznetsov]

After looking through the source code I found that that there is a show_defaults=True parameter I can add to the @click.option() decorator... this more-or-less does what I want. It should be documented, though, as it's missing from http://click.pocoo.org/6/options/

[untitaker]

http://click.pocoo.org/6/api/#click.Option mentions show_defaut. Not everything can be written in prose...

[stevekuznetsov]

@untitaker point taken, but:

• as a new user of Click, I could not find that part of the documentation easily at all -- I went to look at the source before thinking to look at the API!
• as a new user of Click, I am much more likely to go down the table of contents and look at the Options page before I look at the API specification
• in the higher-level Options document, defaults are _specifically_ mentioned and this is where I looked for this information

Feel free to close the issue, but I feel it would be more user-friendly to co-locate this option with the first mentions of default in the Options documentation.

[untitaker]

That's totally fair, as a more generic solution that doesn't just serve show_defaults we might link to the Options API doc more explicitly from the prose docs ("not all options are shown here, take a look here too: ...")

[alanjds]

Just to note, I would expect to be able to turn/switch this show_defaults on to all options at once as a command option

[reillysiemens]

I second @alanjds' comment. 👍

[cubranic]

@unittaker every other click.Option argument is mentioned in the guide. And, for the future readers of this issue who don't look at the API page, it's show_default!

[untitaker]

every other click.Option argument is mentioned in the guide.

No, that's not true, allow_from_autoenv is not documented there.

I suppose given that show_default appears to be popular, it should be added.

[untitaker]

every other click.Option argument is mentioned in the guide.

No, that's not true, allow_from_autoenv is not documented there.

I suppose given that show_default appears to be popular, it should be added.

[mchwalisz]

context_settings could be used as a global switch for show_default.

[tejas619]

I have an option like this:
@click.option('--password', prompt=True, required=True, hide_input=True)
When I do '--help' in the options section I can see '--password'. I don't want this option to be visible in '--help' and still prompt for a password. Is there a way to do this?

[Fjolnir-Dvorak]

@tejas619 That sounds like a new issue not having to do anything with show_default

[jmarkow]

Just bumping this thread. I'm also interested in turning on show_default for all options in my codebase and haven't (yet) found a straightforward way to do this. @mchwalisz how would I use context_settings to achieve this?

[jcrotts]

@jmarkow I might be misunderstanding you but you could pass show_default=True for all your option decorators. Or you could monkey patch the function here .

[mchwalisz]

My idea was to allow the following:

@click.command(
    help='Command helptext',
    context_settings=dict(show_default=True))
@click.option("--test", default="foobar", help="Option helptext")
def cli(test):
    pass

That would allow getting the discussed behavior working:

$ cli --help
Usage: cli [OPTIONS]

  Command helptext

Options:
  --test TEXT   Option helptext. Default: 'foobar'
  --help        Show this message and exit.

context_settings is already used to configure global settings anyway, in my understanding it fits.

[jcrotts]

Ahh I see, @mchwalisz could you actually make another issue for this, since it is an enhancement proposal, and the parent issue is now about documentation changes.

[jmarkow]

@jcrotts monkey patching worked fine for my needs. As a reference,

orig_init = click.core.Option.__init__


def new_init(self, *args, **kwargs):
    orig_init(self, *args, **kwargs)
    self.show_default = True


click.core.Option.__init__ = new_init

At the top of my script after the imports did the trick.

[truthdoug]

In a fix for a different issue (#996), I also added documentation for show_default in Option.

See this part of my commit.

Good to close?

[jcrotts]

Great, closing this issue, feel free to take the discussion on the enhancement to https://github.com/pallets/click/issues/1018

[alexmarco]

@jcrotts monkey patching worked fine for my needs. As a reference,

orig_init = click.core.Option.__init__


def new_init(self, *args, **kwargs):
    orig_init(self, *args, **kwargs)
    self.show_default = True


click.core.Option.__init__ = new_init

At the top of my script after the imports did the trick.

Great 👌, or this way...

from functools import partial

import click

click.option = partial(click.option, show_default=True)

[philipperemy]

Just for info it's show_default not show_defaults.