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

Documentation: mention required=True for options #514

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

Documentation: mention required=True for options #514

gibiansky opened this issue Feb 4, 2016 · 12 comments

Comments

@gibiansky
Copy link

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 Documentation: mention required=True Documentation: mention required=True for options Feb 4, 2016
@rsiemens
Copy link
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
Copy link

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

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

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

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

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

@rr326
Copy link

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

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

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.

@ghost
Copy link

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

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

davidism pushed a commit that referenced this issue May 18, 2018
Honored to fix the most +1'ed issue in click history, documenting the fact that
options may be required=True.
@gibiansky
Copy link
Author

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 GrimzEcho 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 jmichalek132 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.
Projects
None yet
Development

No branches or pull requests