📝 Add docs for interactive prompts.

docs/src/prompt/tutorial001.py

@@ -0,0 +1,10 @@
+import typer
+
+
+def main():
+    person_name = typer.prompt("What's your name?")
+    typer.echo(f"Hello {person_name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs/src/prompt/tutorial002.py

@@ -0,0 +1,13 @@
+import typer
+
+
+def main():
+    delete = typer.confirm("Are you sure you want to delete it?")
+    if not delete:
+        typer.echo("Not deleting")
+        raise typer.Abort()
+    typer.echo("Deleting it!")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs/src/prompt/tutorial003.py

@@ -0,0 +1,10 @@
+import typer
+
+
+def main():
+    delete = typer.confirm("Are you sure you want to delete it?", abort=True)
+    typer.echo("Deleting it!")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs/tutorial/prompt.md

@@ -0,0 +1,78 @@
+When you need to ask the user for info interactively you should normally use <a href="https://typer.tiangolo.com/tutorial/options/prompt/" target="_blank">*CLI Option*s with Prompt</a>, because they allow using the CLI program in a non-interactive way (for example, a Bash script could use it).
+
+But if you absolutely need to ask for interactive information without using a *CLI option*, you can use `typer.prompt()`:
+
+```Python hl_lines="5"
+{!./src/prompt/tutorial001.py!}
+```
+
+Check it:
+
+<div class="termy">
+
+```console
+$ python main.py
+
+# What's your name?:$ Camila
+
+Hello Camila
+```
+
+</div>
+
+## Confirm
+
+There's also an alternative to ask for confirmation. Again, if possible, you should use a <a href="https://typer.tiangolo.com/tutorial/options/prompt/" target="_blank">*CLI Option* with a confirmation prompt</a>:
+
+```Python hl_lines="5"
+{!./src/prompt/tutorial002.py!}
+```
+
+Check it:
+
+<div class="termy">
+
+```console
+$ python main.py
+
+# Are you sure you want to delete it? [y/N]:$ y
+
+Deleting it!
+
+// This time cancel it
+$ python main.py
+
+# Are you sure you want to delete it? [y/N]:$ n
+
+Not deleting
+Aborted!
+```
+
+</div>
+
+## Confirm or abort
+
+As it's very common to abort if the user doesn't confirm, there's an integrated parameter `abort` that does it automatically:
+
+```Python hl_lines="5"
+{!./src/prompt/tutorial003.py!}
+```
+
+<div class="termy">
+
+```console
+$ python main.py
+
+# Are you sure you want to delete it? [y/N]:$ y
+
+Deleting it!
+
+// This time cancel it
+$ python main.py
+
+# Are you sure you want to delete it? [y/N]:$ n
+
+Aborted!
+```
+
+</div>

mkdocs.yml

@@ -47,6 +47,7 @@ nav:
             - Enum - Choices: 'tutorial/parameter-types/enum.md'
             - Path: 'tutorial/parameter-types/path.md'
             - File: 'tutorial/parameter-types/file.md'
+        - Ask with Prompt: 'tutorial/prompt.md'
     - Alternatives, Inspiration and Comparisons: 'alternatives.md'
     - Help Typer - Get Help: 'help-typer.md'
     - Development - Contributing: 'contributing.md'

tests/test_tutorial/test_prompt/test_tutorial001.py

@@ -0,0 +1,28 @@
+import subprocess
+
+import typer
+from typer.testing import CliRunner
+
+from prompt import tutorial001 as mod
+
+runner = CliRunner()
+
+app = typer.Typer()
+app.command()(mod.main)
+
+
+def test_cli():
+    result = runner.invoke(app, input="Camila\n")
+    assert result.exit_code == 0
+    assert "What's your name?:" in result.output
+    assert "Hello Camila" in result.output
+
+
+def test_script():
+    result = subprocess.run(
+        ["coverage", "run", mod.__file__, "--help"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    assert "Usage" in result.stdout

tests/test_tutorial/test_prompt/test_tutorial002.py

@@ -0,0 +1,36 @@
+import subprocess
+
+import typer
+from typer.testing import CliRunner
+
+from prompt import tutorial002 as mod
+
+runner = CliRunner()
+
+app = typer.Typer()
+app.command()(mod.main)
+
+
+def test_cli():
+    result = runner.invoke(app, input="y\n")
+    assert result.exit_code == 0
+    assert "Are you sure you want to delete it? [y/N]:" in result.output
+    assert "Deleting it!" in result.output
+
+
+def test_no_confirm():
+    result = runner.invoke(app, input="n\n")
+    assert result.exit_code == 1
+    assert "Are you sure you want to delete it? [y/N]:" in result.output
+    assert "Not deleting" in result.output
+    assert "Aborted!" in result.output
+
+
+def test_script():
+    result = subprocess.run(
+        ["coverage", "run", mod.__file__, "--help"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    assert "Usage" in result.stdout

tests/test_tutorial/test_prompt/test_tutorial003.py

@@ -0,0 +1,35 @@
+import subprocess
+
+import typer
+from typer.testing import CliRunner
+
+from prompt import tutorial003 as mod
+
+runner = CliRunner()
+
+app = typer.Typer()
+app.command()(mod.main)
+
+
+def test_cli():
+    result = runner.invoke(app, input="y\n")
+    assert result.exit_code == 0
+    assert "Are you sure you want to delete it? [y/N]:" in result.output
+    assert "Deleting it!" in result.output
+
+
+def test_no_confirm():
+    result = runner.invoke(app, input="n\n")
+    assert result.exit_code == 1
+    assert "Are you sure you want to delete it? [y/N]:" in result.output
+    assert "Aborted!" in result.output
+
+
+def test_script():
+    result = subprocess.run(
+        ["coverage", "run", mod.__file__, "--help"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    assert "Usage" in result.stdout