From 421468c04c83e9c41174ffde5a8a1c4238bef0dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Sun, 5 Jan 2020 21:52:46 +0100 Subject: [PATCH] :memo: Add/extend docs and examples for param types. bool, int. --- docs/src/parameter_types/bool/__init__.py | 0 docs/src/parameter_types/bool/tutorial001.py | 12 ++ docs/src/parameter_types/bool/tutorial002.py | 14 ++ docs/src/parameter_types/bool/tutorial003.py | 12 ++ docs/src/parameter_types/bool/tutorial004.py | 12 ++ .../src/parameter_types/number/tutorial003.py | 9 + docs/tutorial/parameter-types/bool.md | 190 ++++++++++++++++++ docs/tutorial/parameter-types/number.md | 48 +++++ 8 files changed, 297 insertions(+) create mode 100644 docs/src/parameter_types/bool/__init__.py create mode 100644 docs/src/parameter_types/bool/tutorial001.py create mode 100644 docs/src/parameter_types/bool/tutorial002.py create mode 100644 docs/src/parameter_types/bool/tutorial003.py create mode 100644 docs/src/parameter_types/bool/tutorial004.py create mode 100644 docs/src/parameter_types/number/tutorial003.py create mode 100644 docs/tutorial/parameter-types/bool.md diff --git a/docs/src/parameter_types/bool/__init__.py b/docs/src/parameter_types/bool/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/docs/src/parameter_types/bool/tutorial001.py b/docs/src/parameter_types/bool/tutorial001.py new file mode 100644 index 0000000..46f6335 --- /dev/null +++ b/docs/src/parameter_types/bool/tutorial001.py @@ -0,0 +1,12 @@ +import typer + + +def main(force: bool = typer.Option(False, "--force")): + if force: + typer.echo("Forcing operation") + else: + typer.echo("Not forcing") + + +if __name__ == "__main__": + typer.run(main) diff --git a/docs/src/parameter_types/bool/tutorial002.py b/docs/src/parameter_types/bool/tutorial002.py new file mode 100644 index 0000000..e887e14 --- /dev/null +++ b/docs/src/parameter_types/bool/tutorial002.py @@ -0,0 +1,14 @@ +import typer + + +def main(accept: bool = typer.Option(None, "--accept/--reject")): + if accept is None: + typer.echo("I don't know what you want yet") + elif accept: + typer.echo("Accepting!") + else: + typer.echo("Rejecting!") + + +if __name__ == "__main__": + typer.run(main) diff --git a/docs/src/parameter_types/bool/tutorial003.py b/docs/src/parameter_types/bool/tutorial003.py new file mode 100644 index 0000000..fda717e --- /dev/null +++ b/docs/src/parameter_types/bool/tutorial003.py @@ -0,0 +1,12 @@ +import typer + + +def main(force: bool = typer.Option(False, "--force/--no-force", "-f/-F")): + if force: + typer.echo("Forcing operation") + else: + typer.echo("Not forcing") + + +if __name__ == "__main__": + typer.run(main) diff --git a/docs/src/parameter_types/bool/tutorial004.py b/docs/src/parameter_types/bool/tutorial004.py new file mode 100644 index 0000000..8c7f47c --- /dev/null +++ b/docs/src/parameter_types/bool/tutorial004.py @@ -0,0 +1,12 @@ +import typer + + +def main(in_prod: bool = typer.Option(True, " /--demo", " /-d")): + if in_prod: + typer.echo("Running in production") + else: + typer.echo("Running demo") + + +if __name__ == "__main__": + typer.run(main) diff --git a/docs/src/parameter_types/number/tutorial003.py b/docs/src/parameter_types/number/tutorial003.py new file mode 100644 index 0000000..95737d0 --- /dev/null +++ b/docs/src/parameter_types/number/tutorial003.py @@ -0,0 +1,9 @@ +import typer + + +def main(verbose: int = typer.Option(0, "--verbose", "-v", count=True)): + typer.echo(f"Verbose level is {verbose}") + + +if __name__ == "__main__": + typer.run(main) diff --git a/docs/tutorial/parameter-types/bool.md b/docs/tutorial/parameter-types/bool.md new file mode 100644 index 0000000..cb7c56d --- /dev/null +++ b/docs/tutorial/parameter-types/bool.md @@ -0,0 +1,190 @@ +We have seen some examples of *CLI options* with `bool`, and how **Typer** creates `--something` and `--no-something` automatically. + +But we can customize those names. + +## Only `--force` + +Let's say that we want a `--force` *CLI option* only, we want to discard `--no-force`. + +We can do that by specifying the exact name we want: + +```Python hl_lines="4" +{!./src/parameter_types/bool/tutorial001.py!} +``` + +Now there's only a `--force` *CLI option*: + +
+ +```console +// Check the help +$ python main.py --help + +// Notice there's only --force, we no longer have --no-force +Usage: main.py [OPTIONS] + +Options: + --force + --install-completion Install completion for the current shell. + --show-completion Show completion for the current shell, to copy it or customize the installation. + --help Show this message and exit. + +// Try it: +$ python main.py + +Not forcing + +// Now add --force +$ python main.py --force + +Forcing operation + +// And --no-force no longer exists ⛔️ +$ python main.py --no-force + +Usage: main.py [OPTIONS] +Try "main.py --help" for help. + +Error: no such option: --no-force +``` + +
+ +## Alternative names + +Now let's imagine we have a *CLI option* `--accept`. + +And we want to allow setting `--accept` or the contrary, but `--no-accept` looks ugly. + +We might want to instead have `--accept` and `--reject`. + +We can do that by passing a single `str` with the 2 names for the `bool` *CLI option* separated by `/`: + +```Python hl_lines="4" +{!./src/parameter_types/bool/tutorial002.py!} +``` + +Check it: + +
+ +```console +// Check the help +$ python main.py --help + +// Notice the --accept / --reject +Usage: main.py [OPTIONS] + +Options: + --accept / --reject + --install-completion Install completion for the current shell. + --show-completion Show completion for the current shell, to copy it or customize the installation. + --help Show this message and exit. + +// Try it +$ python main.py + +I don't know what you want yet + +// Now pass --accept +$ python main.py --accept + +Accepting! + +// And --reject +$ python main.py --reject + +Rejecting! +``` + +
+ +## Short names + +The same way, you can declare short versions of the names for these *CLI options*. + +For example, let's say we want `-f` for `--force` and `-F` for `--no-force`: + +```Python hl_lines="4" +{!./src/parameter_types/bool/tutorial003.py!} +``` + +Check it: + +
+ +```console +// Check the help +$ python main.py --help + +// Notice the -f, --force / -F, --no-force +Usage: main.py [OPTIONS] + +Options: + -f, --force / -F, --no-force + --install-completion Install completion for the current shell. + --show-completion Show completion for the current shell, to copy it or customize the installation. + --help Show this message and exit. + +// Try with the short name -f +$ python main.py -f + +Forcing operation + +// Try with the short name -F +$ python main.py -F + +Not forcing +``` + +
+ +## Only names for `False` + +If you want to (although it might not be a good idea), you can declare only *CLI option* names to set the `False` value. + +To do that, use a space and a single `/` and pass the negative name after: + +```Python hl_lines="4" +{!./src/parameter_types/bool/tutorial004.py!} +``` + +!!! tip + Have in mind that it's a string with a preceding space and then a `/`. + + So, it's `" /-S"` not `"/-S"`. + +Check it: + +
+ +```console +// Check the help +$ python main.py --help + +// Notice the / -d, --demo +Usage: main.py [OPTIONS] + +Options: + / -d, --demo + --install-completion Install completion for the current shell. + --show-completion Show completion for the current shell, to copy it or customize the installation. + --help Show this message and exit. + +// Try it +$ python main.py + +Running in production + +// Now pass --demo +$ python main.py --demo + +Running demo + +// And the short version +$ python main.py -d + +Running demo +``` + +
diff --git a/docs/tutorial/parameter-types/number.md b/docs/tutorial/parameter-types/number.md index fc70ca7..adaba25 100644 --- a/docs/tutorial/parameter-types/number.md +++ b/docs/tutorial/parameter-types/number.md @@ -98,3 +98,51 @@ ID is 5 ``` + +## Counter *CLI options* + +You can make a *CLI option* work as a counter with the `counter` parameter: + +```Python hl_lines="4" +{!./src/parameter_types/number/tutorial003.py!} +``` + +It means that the *CLI option* will be like a boolean flag, e.g. `--verbose`. + +And the value you receive in the function will be the amount of times that `--verbose` was added: + +
+ +```console +// Check it +$ python main.py + +Verbose level is 0 + +// Now use one --verbose +$ python main.py --verbose + +Verbose level is 1 + +// Now 3 --verbose +$ python main.py --verbose --verbose --verbose + +Verbose level is 3 + +// And with the short name +$ python main.py -v + +Verbose level is 1 + +// And with the short name 3 times +$ python main.py -v -v -v + +Verbose level is 3 + +// As short names can be put together, this also works +$ python main.py -vvv + +Verbose level is 3 +``` + +
\ No newline at end of file