By default Typer will create a CLI option name from the function parameter.
So, if you have a function with:
def main(user_name: Optional[str] = None):
pass
or
def main(user_name: Annotated[Optional[str], typer.Option()] = None):
pass
Typer will create a CLI option:
--user-name
But you can customize it if you want to.
Let's say the function parameter name is user_name
as above, but you want the CLI option to be just --name
.
You can pass the CLI option name that you want to have in the following positional argument passed to typer.Option()
:
=== "Python 3.6+"
```Python hl_lines="5"
{!> ../docs_src/options/name/tutorial001_an.py!}
```
Here you are passing the string `"--name"` as the first positional argument to `typer.Option()`.
=== "Python 3.6+ non-Annotated"
!!! tip
Prefer to use the `Annotated` version if possible.
```Python hl_lines="4"
{!> ../docs_src/options/name/tutorial001.py!}
```
Here you are passing the string `"--name"` as the second positional argument to `typer.Option()`, as the first argument is `...` to mark it as required.
!!! info "Positional" means that it's not a function argument with a keyword name.
For example `show_default=True` is a keyword argument. "`show_default`" is the keyword.
But in `"--name"` there's no `option_name="--name"` or something similar, it's just the string value `"--name"` that goes in `typer.Option()`.
That's a "positional argument" in a function.
Check it:
$ python main.py --help
// Notice the --name instead of --user-name
Usage: main.py [OPTIONS]
Options:
--name TEXT [required]
--help Show this message and exit.
// Try it
$ python --name Camila
Hello Camila
A short name is a CLI option name with a single dash (-
) instead of 2 (--
) and a single letter, like -n
instead of --name
.
For example, the ls
program has a CLI option named --size
, and the same CLI option also has a short name -s
:
// With the long name --size
$ ls ./myproject --size
12 first-steps.md 4 intro.md
// With the short name -s
$ ls ./myproject -s
12 first-steps.md 4 intro.md
// Both CLI option names do the same
Short names have another feature, when they have a single letter, as in -s
, you can put several of these CLI options together, with a single dash.
For example, the ls
program has these 2 CLI options (among others):
--size
: show the sizes of the listed files.--human
: show a human-readable format, like1MB
instead of just1024
.
And these 2 CLI options have short versions too:
--size
: short version-s
.--human
: short version-h
.
So, you can put them together with -sh
or -hs
:
// Call ls with long CLI options
$ ls --size --human
12K first-steps.md 4.0K intro.md
// Now with short versions
$ ls -s -h
12K first-steps.md 4.0K intro.md
// And with short versions together
$ ls -sh
12K first-steps.md 4.0K intro.md
// Order in short versions doesn't matter
$ ls -hs
12K first-steps.md 4.0K intro.md
// They all work the same 🎉
When you use CLI options with short names, you can put them together if they are just boolean flags, like --size
or --human
.
But if you have a CLI option --file
with a short name -f
that takes a value, if you put it with other short names for CLI options, you have to put it as the last letter, so that it can receive the value that comes right after.
For example, let's say you are decompressing/extracting a file myproject.tar.gz
with the program tar
.
You can pass these CLI option short names to tar
:
-x
: means "eX
tract", to decompress and extract the contents.-v
: means "V
erbose", to print on the screen what it is doing, so you can know that it's decompressing each file and can entertain yourself while you wait.-f
: means "F
ile", this one requires a value, the compressed file to extract (in our example, this ismyproject.tar.gz
).- So if you use all the short names together, this
-f
has to come last, to receive the value that comes next to it.
- So if you use all the short names together, this
For example:
$ tar -xvf myproject.tar.gz
myproject/
myproject/first-steps.md
myproject/intro.md
// But if you put the -f before
$ tar -fxv myproject.tar.gz
// You get an ugly error
tar: You must specify one of the blah, blah, error, error
In Typer you can also define CLI option short names the same way you can customize the long names.
You can pass positional arguments to typer.Option()
to define the CLI option name(s).
!!! tip Remember the positional function arguments are those that don't have a keyword.
All the other function arguments/parameters you pass to `typer.Option()` like `prompt=True` and `help="This option blah, blah"` require the keyword.
You can overwrite the CLI option name to use as in the previous example, but you can also declare extra alternatives, including short names.
For example, extending the previous example, let's add a CLI option short name -n
:
=== "Python 3.6+"
```Python hl_lines="5"
{!> ../docs_src/options/name/tutorial002_an.py!}
```
=== "Python 3.6+ non-Annotated"
!!! tip
Prefer to use the `Annotated` version if possible.
```Python hl_lines="4"
{!> ../docs_src/options/name/tutorial002.py!}
```
Here we are overwriting the CLI option name that by default would be --user-name
, and we are defining it to be --name
. And we are also declaring a CLI option short name of -n
.
Check it:
// Check the help
$ python main.py --help
// Notice the two CLI option names -n and --name
Usage: main.py [OPTIONS]
Options:
-n, --name TEXT [required]
--help Show this message and exit.
// Try the short version
$ python main.py -n Camila
Hello Camila
If you only declare a short name like -n
then that will be the only CLI option name. And neither --name
nor --user-name
will be available.
=== "Python 3.6+"
```Python hl_lines="5"
{!> ../docs_src/options/name/tutorial003_an.py!}
```
=== "Python 3.6+ non-Annotated"
!!! tip
Prefer to use the `Annotated` version if possible.
```Python hl_lines="4"
{!> ../docs_src/options/name/tutorial003.py!}
```
Check it:
$ python main.py --help
// Notice there's no --name nor --user-name, only -n
Usage: main.py [OPTIONS]
Options:
-n TEXT [required]
--help Show this message and exit.
// Try it
$ python main.py -n Camila
Hello Camila
Continuing with the example above, as Typer allows you to declare a CLI option as having only a short name, if you want to have the default long name plus a short name, you have to declare both explicitly:
=== "Python 3.6+"
```Python hl_lines="5"
{!> ../docs_src/options/name/tutorial004_an.py!}
```
=== "Python 3.6+ non-Annotated"
!!! tip
Prefer to use the `Annotated` version if possible.
```Python hl_lines="4"
{!> ../docs_src/options/name/tutorial004.py!}
```
Check it:
$ python main.py --help
// Notice that we have the long version --user-name back
// and we also have the short version -n
Usage: main.py [OPTIONS]
Options:
-n, --user-name TEXT [required]
--help Show this message and exit.
// Try it
$ python main.py --user-name Camila
Hello Camila
// And try the short version
$ python main.py -n Camila
You can create multiple short names and use them together.
You don't have to do anything special for it to work (apart from declaring those short versions):
=== "Python 3.6+"
```Python hl_lines="6-7"
{!> ../docs_src/options/name/tutorial005_an.py!}
```
=== "Python 3.6+ non-Annotated"
!!! tip
Prefer to use the `Annotated` version if possible.
```Python hl_lines="5-6"
{!> ../docs_src/options/name/tutorial005.py!}
```
!!! tip Notice that, again, we are declaring the long and short version of the CLI option names.
Check it:
$ python main.py --help
// We now have short versions -n and -f
// And also long versions --name and --formal
Usage: main.py [OPTIONS]
Options:
-n, --name TEXT [required]
-f, --formal
--help Show this message and exit.
// Try the short versions
$ python main.py -n Camila -f
Good day Ms. Camila.
// And try the 2 short versions together
// See how -n has to go last, to be able to get the value
$ python main.py -fn Camila
Good day Ms. Camila.