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

Documentation: mention required=True for options #514

Closed
gibiansky opened this Issue Feb 4, 2016 · 12 comments

Comments

Projects
None yet
@gibiansky

gibiansky commented Feb 4, 2016

This is never mentioned as a possibility for click.option anywhere in the docs as far as I can tell (or at least it should be more prominent, maybe a section). (it talks about it in click.argument, but its unclear that it exists for both)

Someone just came to me saying, "we have to stop using click, i checked everywhere in their documentation, they don't support required options, which is important!"

Thanks :)

@gibiansky gibiansky changed the title from Documentation: mention required=True to Documentation: mention required=True for options Feb 4, 2016

@rsiemens

This comment has been minimized.

Contributor

rsiemens commented Feb 5, 2016

I think its intentional that it is not mentioned. Per the doc here

As its name indicates, an option is optional. While arguments can be optional within reason, they are much more restricted in how optional they can be.

While you can have required options, the nature of an option is that it is not required. Perhaps using the default=value would be better.

@pmdarrow

This comment has been minimized.

pmdarrow commented Feb 5, 2016

@Nudies by why provide the option if it's not intended to be used? IMO it should be removed from the public API or documented.

@gibiansky

This comment has been minimized.

gibiansky commented Feb 8, 2016

I don't know if this is an intended usecase, or maybe we are misusing click, but for us, all our command line parameters are options. Arguments do not provide the --name syntax, and for our CLIs we want every single thing to be prefixed with --what-it-is, in the style of keyword arguments in Python. As a result we use click.option almost exclusively, except for when we need nargs=-1; but that means that we need required=True sometimes for click.option.

Please don't remove remove this functionality; we would be very sad if our use case were deprecated for purely aesthetic reasons

@pmdarrow

This comment has been minimized.

pmdarrow commented Feb 8, 2016

I should have mentioned I'm in favour of documenting & supporting it as well, not removing it (I realize it didn't sound like that from my comment).

@ariscn

This comment has been minimized.

ariscn commented Mar 22, 2016

Big +1 for all the reasons stated. Options are self-documenting (--my-whatever foo), and are sometimes (often!) required.

@fleipold

This comment has been minimized.

fleipold commented Sep 13, 2016

I have also switched to using named options as named arguments. This seems to be a widely used practice.

@rr326

This comment has been minimized.

rr326 commented Jan 10, 2017

+1 as well. I KNEW there must be a "required" field - and this issue is where I found the documentation!

@marcinpraczko

This comment has been minimized.

marcinpraczko commented Apr 7, 2017

+1 to document this - still seems be not documented.
And in multiple arguments having required option is happening more quite often. For example writing something for search (as I am doing now).
So need following syntax:

app command --search 'string'
# --search is required at this moment

So I would ask for updating documentation as well.

@davidvhill

This comment has been minimized.

davidvhill commented Jul 20, 2017

+1 Named in lieu of positional parameters are pretty important for us to help prevent coding errors. In our case the named parameters are not optional.

@davoscollective

This comment has been minimized.

davoscollective commented Feb 28, 2018

The main reason I prefer a required option over an argument is not just that they are self-documenting via their name as @ariscn pointed out, but can be explicitly documented by using the help parameter in the @click.option() decorator, and listed with the inbuilt --help option. @click.argument doesn't take a help parameter so needs to be pretty obvious or otherwise documented in the function doc-string. It (argument usage) mimics bash and other shells, sure, and supporting that style makes total sense for continuity and consistency reasons, but for new cli users it's not great. I'd probably use argument if there were a help parameter for it, although that might not be consistent either. So yeah, add required=True to the docs, I also discovered it here on this issue thread first, thanks @gibiansky

@burakalver

This comment has been minimized.

burakalver commented Apr 8, 2018

also useful for "if option a is provided than option b is required"; otherwise b is optional.

rpgraham84 added a commit to rpgraham84/click that referenced this issue May 15, 2018

Fixes issue pallets#514
Honored to fix the most +1'ed issue in click history, documenting the fact that
options may be required=True.

davidism added a commit that referenced this issue May 18, 2018

Fixes issue #514
Honored to fix the most +1'ed issue in click history, documenting the fact that
options may be required=True.

@davidism davidism closed this May 18, 2018

@gibiansky

This comment has been minimized.

gibiansky commented May 18, 2018

Two years later I am delighted :) Thank you! (For fixing the issue and for an awesome library I've been using for years now!)

@pallets pallets deleted a comment from BrianHVB Jul 17, 2018

@pallets pallets deleted a comment from Trepix Jul 17, 2018

@pallets pallets deleted a comment from acompanys Jul 17, 2018

@pallets pallets deleted a comment from starplanet Jul 17, 2018

@pallets pallets deleted a comment from khunafin Jul 17, 2018

@pallets pallets deleted a comment from Kak3n Jul 17, 2018

@pallets pallets deleted a comment from niothiel Jul 17, 2018

@pallets pallets deleted a comment from demarlik01 Jul 17, 2018

@pallets pallets deleted a comment from quasiben Jul 17, 2018

@pallets pallets locked as resolved and limited conversation to collaborators Jul 17, 2018

@davidism davidism added this to the 7.0 milestone Sep 10, 2018

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.