✨ Add support for optional values of CLI Options

[MatteoBouvier]

Click allows to make cli option values optional, using a default value when not provided (https://click.palletsprojects.com/en/stable/options/#optional-value).

This feature is not currently supported by Typer but there is interest from people (including myself) : cf #873, #608.
My use case was creating a --doc option for displaying a detailed documentation of a command, in english by default but in another language if passing a language name such as --doc fr.

To stick to the type annotation philosophy of Typer, this PR defines Options with optional values (with type T) by annotating them as bool | T :

def main(doc: Annotated[bool | str, typer.Option()] = "en"):
    if doc:
        print_doc(language=doc)

    # code ...

• when not passing --doc, the doc parameter gets a value of False
• when passing --doc <value> as usual, the doc parameter gets the value
• when passing only --doc with no value, the doc parameter gets the default value "en"

The help message for the Options is rendered as:

╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --doc             BOOLEAN|TEXT  [default: False (en)]                                                                                                              │
│ --help                          Show this message and exit.                                                                                                        │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

note : This PR does not implement type unions for Options, only bool | T is parsed

[github-actions]

📝 Docs preview for commit 37b74b4 at: https://24fe9493.typertiangolo.pages.dev

Modified Pages

• https://24fe9493.typertiangolo.pages.dev/tutorial/options/optional_value/

[github-actions]

This pull request has a merge conflict that needs to be resolved.

[YuriiMotov]

@MatteoBouvier, thanks for your interest and efforts!

I think this feature looks unintuitive in such implementation:

• BOOLEAN|TEXT [default: False (en)] in docs looks confusing..
• behavior is different from how it works in Click: in Click the default value is used if option is not used and flag_value is used if option is used without value

Anyway, I would wait for Sebastian to approve the idea of feature request first

[svlandeg]

As a quick drive-by comment, just noting here that if we do decide to progress with this PR, we'll need to cover the new tutorial files in a specific test in tests/test_tutorial/test_options/test_optional_value/