📚 Update docs for Option's optional value

docs/tutorial/options/optional_value.md

@@ -0,0 +1,65 @@
+# Optional value for CLI Options
+
+As in Click, providing a value to a *CLI option* can be made optional, in which case a default value will be used instead.
+
+To make a *CLI option*'s value optional, you can annotate it as a *Union* of types *bool* and the parameter type.
+
+/// info
+
+You can create a type <a href="https://docs.python.org/3/library/typing.html#typing.Union" class="external-link" target="_blank">Union</a> by importing *Union* from the typing module.
+
+For example `Union[bool, str]` represents a type that is either a boolean or a string.
+
+You can also use the equivalent notation `bool | str`
+
+///
+
+Let's add a *CLI option* `--tone` with optional value:
+
+{* docs_src/options/optional_value/tutorial001_an.py hl[5] *}
+
+Now, there are three possible configurations:
+
+* `--greeting` is not used, the parameter will receive a value of `False`.
+```
+python main.py
+```
+
+* `--greeting` is supplied with a value, the parameter will receive the string representation of that value.
+```
+python main.py --greeting <value>
+```
+
+* `--greeting` is used with no value, the parameter will receive the default `formal` value.
+```
+python main.py --greeting
+```
+
+
+And test it:
+
+<div class="termy">
+
+```console
+$ python main.py Camila Gutiérrez
+
+// We didn't pass the greeting CLI option, we get no greeting
+
+
+// Now update it to pass the --greeting CLI option with default value
+$ python main.py Camila Gutiérrez --greeting
+
+Hello Camila Gutiérrez
+
+// The above is equivalent to passing the --greeting CLI option with value `formal`
+$ python main.py Camila Gutiérrez --greeting formal
+
+Hi Camila !
+
+// But you can select another value
+$ python main.py Camila Gutiérrez --greeting casual
+
+Hi Camila !
+```
+
+</div>

docs_src/options/optional_value/tutorial001.py

@@ -0,0 +1,19 @@
+import typer
+
+
+def main(name: str, lastname: str, greeting: bool | str = "formal"):
+    if not greeting:
+        return
+
+    if greeting == "formal":
+        print(f"Hello {name} {lastname}")
+
+    elif greeting == "casual":
+        print(f"Hi {name} !")
+
+    else:
+        raise ValueError(f"Invalid greeting '{greeting}'")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/options/optional_value/tutorial001_an.py

@@ -0,0 +1,22 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(
+    name: str, lastname: str, greeting: Annotated[bool | str, typer.Option()] = "formal"
+):
+    if not greeting:
+        return
+
+    if greeting == "formal":
+        print(f"Hello {name} {lastname}")
+
+    elif greeting == "casual":
+        print(f"Hi {name} !")
+
+    else:
+        raise ValueError(f"Invalid greeting '{greeting}'")
+
+
+if __name__ == "__main__":
+    typer.run(main)

mkdocs.yml

@@ -89,6 +89,7 @@ nav:
           - tutorial/options/index.md
           - tutorial/options/help.md
           - tutorial/options/required.md
+          - tutorial/options/optional_value.md
           - tutorial/options/prompt.md
           - tutorial/options/password.md
           - tutorial/options/name.md