How create an option with an optional argument (e.g. a flag with an optional value)

[taranlu-houzz]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the Typer documentation, with the integrated search.
• I already searched in Google "How to X in Typer" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to Typer but to Click.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from pprint import pprint as pp
from typing import Optional
import typer


APP = typer.Typer(
    rich_markup_mode="markdown",
    pretty_exceptions_show_locals=False,
)


@APP.command()
def test(
    opt_1: Optional[float] = typer.Option(
        None,
        "--opt-1",
        is_flag=False,
        flag_value=3.14,
        help="blah blah",
    ),
) -> None:
    pp(locals())


if __name__ == "__main__":
    APP()

Description

In click, it is possible to create an option with an optional value: https://click.palletsprojects.com/en/8.1.x/options/#optional-value

I'm wondering if it is possible to do this in typer?

For the example given above, I would expect the following:

• No --opt-1 flag passed: None
• --opt-1 flag is passed with no value: 3.14 (default value)
• --opt-1 flag is passed with a value (99): 99 (value that was passed)

Operating System

macOS

Operating System Details

No response

Typer Version

0.9.0

Python Version

3.10.10

Additional Context

No response

[e-sr]

some hints? how to do this?
I tried like in clik docs:

@app.command()
def test_flag(flag: Optional[str] = typer.Option(None, is_flag=False, flag_value='default')):
    if flag is not None:
        print(f"{flag=}")
    else:
        print("flag unset")

calling
app test-flag is ok
app test-flag --flag is ok
app test-flag --flag=nodefault raise an exception

Option '--flag' does not take a value.                                                                                           │

what is the purpose of parameter is_flag

[MartinSoto]

Any appropriate answers to this question? This kind of behavior is common in CLI programs, which is the reason why Click supports it.

This kind of thing makes Typer inadequate for everything but the simplest CLI programs. Really sad given that the general concept of it is very good.

[davidwaroquiers]

Also wondering how to do this. I've been trying different ways and none of them worked.

[MatthieuDartiailh]

I am interested in this too.

[0zitro]

Kinda a shame, I tried MyEnumName | bool | None and tuple[MyEnumName | None] even trying to achieve optional ... options. Seems like this really is not supported.

[phalberg]

Hey,
I have done some investigation work, a little too much, but now i think I have some better context to give around this problem:

Summary

• Typer is now vendoring Click, meaning that some functionality might be deprecated from this (and some might be added of course)
• 🗑️ Deprecate support for is_flag and flag_value parameters #987 Deprecates the is_flag and flag_value params, meaning this option will not be possible
• Until then, if this get's replaced by some other solution then that could work, if not a more "ugly" workaround will probably be used ( I propose one down below)

Thanks @svlandeg for correction of newer events

Example code:

import typer
from typing import Optional

app = typer.Typer()

@app.command()
def test(
    opt_1: bool = typer.Option(False, "--opt-1", help="Enable the option (defaults to 3.14)"),
    opt_1_val: Optional[float] = typer.Option(None, "--opt-1-val", help="Explicitly override the 3.14 value")
):
   # A more manual approach...
    if opt_1_val is not None:
        final_val = opt_1_val
    elif opt_1:
        final_val = 3.14
    else:
        final_val = None
        
    print(f"Result: {final_val}")

if __name__ == "__main__":
    app()

This gives the following:

• python cli.py => None
• python cli.py --opt-1 => 3.14
• python cli.py --opt-1-val 99 => 99.0

I must admit, this solution is not pretty, but it is somewhat the best I can provide for now in the meantime - as work is being done to handle it accordingly internally in the codebase(ses). As I see it, in the meantime, not so many solutions will work, since these things seem to be deprecating soon anyways...

[svlandeg]

We have now vendored Click and aren't using UNSET anymore, so unsure how much of the above is still relevant?

[phalberg]

Aha, I think I might have missed some newer events 😅. Still I see TODO's in the codebase mentioning to remove the is_flag and flag_value, ultimately this is final nail in the coffin: #987. Where support for the functions were deprecated. Meaning two things:

• Another solution will be developed in the future and thereby can be used or
• A smart workaround can be used without using any of these params - maybe something to what i have proposed above...

( I updated my original answer to try to align more correctly then 😄)
Perhaps this discussion could be closed then, as the original parameters are being deprecated anyways...

[MaxFreedomPollard]

Short version: on current Typer you can't do this as a single option anymore. "Optional value" is a Click feature, and the copy of Click that Typer now bundles has dropped the parser support for it. Here's what's actually going on, plus two things that do work today.

Why is_flag=False, flag_value=... no longer works in Typer

That pattern is Click's "optional value" feature, and it still works in standalone Click 8.x:

# pip install "click>=8,<9"
import click

@click.command()
@click.option("--opt-1", is_flag=False, flag_value=3.14, type=float, default=None)
def cli(opt_1):
    click.echo(f"opt_1={opt_1!r}")

(no flag)   -> opt_1=None
--opt-1     -> opt_1=3.14      # bare flag gives flag_value
--opt-1 99  -> opt_1=99.0
--opt-1=99  -> opt_1=99.0

Recent Typer (0.26.x here) bundles its own copy of Click, and that copy no longer has the machinery. If you introspect the Click option Typer builds from typer.Option(None, "--opt-1", is_flag=False, flag_value=3.14), the flag_value is gone and nargs is 1:

cmd = typer.main.get_command(app)
p = next(x for x in cmd.params if x.name == "opt_1")
# is_flag=False, nargs=1, no flag_value (it lands in a dead `_depr_flag_value` slot)

In standalone Click, the parser decides "consume the next token, or not" from an internal attribute _flag_needs_value (see click/parser.py). That attribute, and the parser branch that reads it, isn't present in Typer's bundled Click at all, so the option is just an ordinary value-taking option (nargs=1). That's why bare --opt-1 fails with "Option '--opt-1' requires an argument." As phalberg pointed out above, is_flag and flag_value are deprecated (#987), so this path isn't coming back.

Option A: pure Typer, two options (works today)

Not a single flag, but it reproduces the exact three-way behavior and doesn't lean on anything deprecated:

from typing import Optional
import typer

app = typer.Typer()
DEFAULT = 3.14

@app.command()
def main(
    opt_1: bool = typer.Option(False, "--opt-1", help=f"Use {DEFAULT} unless --opt-1-value is given"),
    opt_1_value: Optional[float] = typer.Option(None, "--opt-1-value"),
):
    value = opt_1_value if opt_1_value is not None else (DEFAULT if opt_1 else None)
    typer.echo(f"value={value!r}")

(nothing)         -> value=None
--opt-1           -> value=3.14
--opt-1-value 99  -> value=99.0

Option B: drop to raw Click for just this command (works today, single flag)

If you specifically need the single-flag UX, define that one command in Click directly (the first snippet) and keep Typer for the rest of the app. They compose fine. Since the bundled Click has already dropped optional value, this relies on standalone Click, so pin click<9 and treat it as a stopgap.

Given the deprecation, Option A is the one I'd ship.

Tested on Typer 0.26.8 / Click 8.4.2, Python 3.11. The outputs above are real.