revise 'Options' documentation by brihall · Pull Request #3192 · pallets/click

brihall · 2026-01-22T15:09:28Z

#3175

If #3191 is approved I'd be happy to go back and handle any merge conflicts caused by this PR's changes.

Clarity improvements

The "Option Decorator" section refers to "positional arguments" of the click.option() decorator and to the "function argument" of the decorated callback function. Using "positional arguments" as shorthand for "positional arguments passed to the option() decorator" introduces ambiguity, because the decorated function can also accept positional arguments (and in fact does in every provided example). Using "function" as shorthand for "decorated function" is also ambiguous. References to the positional arguments for click.option() are changed to "parameter declarations" (for consistency with the API docs), and "function argument" is replaced with the more specific "callback argument".
When describing the steps to infer the callback argument name from the parameter declarations, the following is misleading (possibly outdated?):
1. If a positional argument name does not have a prefix, it is chosen.
The actual criteria is that the argument is a valid identifier, i.e. str.isidentifier() returns True (see Option._parse_decls()). A string that is "prefixed" with _ would therefore be chosen. The step is updated to reflect this and links to Python's "Lexical analysis" documentation.
Several sections use "pass in" back-to-back when referencing option() arguments and command line usage. This makes it unclear when the command line usage is being referenced. When referring to option(), instead use "declare" for positional arguments or "set" for keyword arguments.

Consistency improvements

All instances of "underlying function" are replaced with "decorated function".
References to "dash(es)" are replaced with - or --. This establishes consistency with the "Other Prefix Characters" section and allows for several sentences to be reworded for concision.

Miscellaneous

Minor grammar and concision edits throughout.

Rowlando13 · 2026-01-31T07:00:19Z

I will have to take a closer look at this. At first glance you made some good grammatical fixes, but also made some changes that obscure what is meant. Sometimes it's best not to use the most technical terms available because people may not know what you mean.

brihall · 2026-01-31T19:07:35Z

I appreciate the feedback, and after re-reading I definitely agree that some of the changes need more work (particularly the Option Decorator section). I have some ideas for improvements that might be a nicer middle ground, but I'll wait for your closer review before making any changes.

Rowlando13 · 2026-02-01T08:07:17Z

docs/options.md


-Click expects you to pass at least two positional arguments to the option decorator. They are option name and function argument name.
+The {func}`option()` decorator accepts parameter declarations as positional arguments. Parameter declarations can consist of any number of option names and, optionally, a single identifier matching an argument name in the decorated callback function.



The {func}option() decorator is usually passed two positional arguments, the option name and the decorated function name.

Yes, this is much more concise than the initial change. I think it's also important to refer to an "argument name" rather than just "decorated function name". To me, the "decorated function name" in the example is echo, not string_to_echo.

Suggested change

The {func}`option()` decorator is usually passed two positional arguments: the option name and the argument name from the decorated function.

The {func}option() decorator is usually passed two positional arguments, the option name and the decorated function argument name.

Rowlando13 · 2026-02-01T08:13:42Z

docs/options.md


-However, if you don't pass in the function argument name, then Click will try to infer it. A simple way to name your option is by taking the function argument, adding two dashes to the front and converting underscores to dashes. In this case, Click will infer the function argument name correctly so you can add only the option name.
+If an identifier for the callback argument is not declared, then Click will try to infer it. A simple way to name an option is by prepending `--` to the callback argument name and converting underscores to `-`; this ensures that Click can correctly infer the callback argument name. Consequently, {func}`option()` only requires declarations for the option name(s).



However, if the decorated function name is not passed in, then Click will try to infer it. A simple way to name the option so that Click will infer it correctly is by taking the function argument, adding two dashes to the front and converting underscores to dashes

With the proposed change to line 27, is simply "argument name" clear enough? "Decorated function argument name" is more specific but also a bit of a mouthful.

Suggested change

However, if the argument name is not passed in, then Click will try to infer it from the option name. A simple way to name the option so that Click will infer it correctly is by taking the function argument, adding two dashes to the front and converting underscores to dashes.

However, if the decorated function argument name is not passed in, then Click will try to infer it. A simple way to name the option so that Click will infer it correctly is by taking the function argument, adding two dashes to the front and converting underscores to dashes

I prefer to be specific in this case since people jump in and out of the docs.

Rowlando13 · 2026-02-01T09:05:14Z

docs/options.md

@@ -24,7 +24,7 @@ Useful and often used kwargs are:



I generally avoid using callback unless I have to since a lot of python developers are not software engineers and so probably won't know what it means.

Agreed that "decorated function" is better than "callback function"

Rowlando13 · 2026-02-01T09:06:10Z

docs/options.md


-More formally, Click will try to infer the function argument name by:
+More formally, Click will try to infer the callback argument name as follows:



More formally, Click will try to infer the decorated function name as follows:

Suggested change

More formally, Click will try to infer the argument name as follows:

More formally, Click will try to infer the decorated function argument name as follows:

Rowlando13 · 2026-02-01T09:08:41Z

@brihall I will got through some of the PR. Will hopefully get to the rest sometime soon. Don't be put off by the lots of changes, I like what I see so far!

brihall · 2026-02-01T18:47:28Z

@Rowlando13 Not put off at all. I really appreciate you taking the time to give feedback, and the changes were definitely necessary. I applied some small changes in the unreviewed sections so that they're more aligned with your first round of suggestions.

Rowlando13 · 2026-02-05T09:12:26Z

docs/options.md

-1. If a positional argument name does not have a prefix, it is chosen.
-2. If a positional argument name starts with with two dashes, the first one given is chosen.
-3. The first positional argument prefixed with one dash is chosen otherwise.
+1. If a positional argument is a valid [Python identifier], it is chosen.


If a positional argument is a valid [Python identifier] (and thus does not have dashes), it is chosen.

Rowlando13 · 2026-02-05T09:15:14Z

docs/options.md

-2. If a positional argument name starts with with two dashes, the first one given is chosen.
-3. The first positional argument prefixed with one dash is chosen otherwise.
+1. If a positional argument is a valid [Python identifier], it is chosen.
+2. If multiple positional arguments are prefixed with `--`, the one that was declared first is chosen.


If multiple positional arguments are prefixed with --, the first one declared is chosen.

Rowlando13 · 2026-02-05T09:15:47Z

docs/options.md

+3. Otherwise, the first positional argument prefixed with `-` is chosen.

-The chosen positional argument is converted to lower case, up to two dashes are removed from the beginning, and other dashes are converted to underscores to get the function argument name.
+[Python identifier]: https://docs.python.org/3/reference/lexical_analysis.html#identifiers


Inline this. Python identifier is not likely to be reused.

Rowlando13 · 2026-02-05T09:19:41Z

docs/options.md

 ```

-By using a tuple literal as type, `nargs` gets automatically set to the
+By using a tuple literal as `type`, `nargs` gets automatically set to the


By using a tuple literal as the type, nargs gets automatically set to the

Rowlando13 · 2026-02-05T09:23:25Z

docs/options.md

 ## Flag Value

-To have an flag pass a value to the underlying function set `flag_value`. This automatically sets `is_flag=True`. To mark the flag as default, set `default=True`. Setting flag values can be used to create patterns like this:
+To have a flag pass a value to the decorated function set `flag_value`. This automatically sets `is_flag=True`. To mark the flag as default, set `default=True`. Setting flag values can be used to create patterns like this:


Stopped reviewing here.

revise 'Options' documentation

5590ef4

Rowlando13 reviewed Feb 1, 2026

View reviewed changes

replace references to 'callback' and 'parameter declarations'

74e542e

Rowlando13 reviewed Feb 5, 2026

View reviewed changes


		Click expects you to pass at least two positional arguments to the option decorator. They are option name and function argument name.
		The {func}`option()` decorator accepts parameter declarations as positional arguments. Parameter declarations can consist of any number of option names and, optionally, a single identifier matching an argument name in the decorated callback function.


	The {func}`option()` decorator is usually passed two positional arguments: the option name and the argument name from the decorated function.


		However, if you don't pass in the function argument name, then Click will try to infer it. A simple way to name your option is by taking the function argument, adding two dashes to the front and converting underscores to dashes. In this case, Click will infer the function argument name correctly so you can add only the option name.
		If an identifier for the callback argument is not declared, then Click will try to infer it. A simple way to name an option is by prepending `--` to the callback argument name and converting underscores to `-`; this ensures that Click can correctly infer the callback argument name. Consequently, {func}`option()` only requires declarations for the option name(s).


	However, if the argument name is not passed in, then Click will try to infer it from the option name. A simple way to name the option so that Click will infer it correctly is by taking the function argument, adding two dashes to the front and converting underscores to dashes.

Uh oh!

Conversation

brihall commented Jan 22, 2026

Clarity improvements

Consistency improvements

Miscellaneous

Uh oh!

Rowlando13 commented Jan 31, 2026

Uh oh!

brihall commented Jan 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rowlando13 Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rowlando13 commented Feb 1, 2026

Uh oh!

brihall commented Feb 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Rowlando13 Feb 1, 2026 •

edited

Loading