add ability to prompt the user

Author: mathiasertl

docs/quickstart.rst

@@ -129,3 +129,30 @@ split between option argument and value.
 Single-character options will not be split from their respective value:
 
 .. structured-tutorial-part::
+
+*************************
+Ask the user for feedback
+*************************
+
+When running a tutorial, you can prompt the user to inspect the current state. You can ask the user to just
+press "enter" or even to confirm that the current state looks okay (with answering "yes" or "now").
+
+When rendering a tutorial, prompt parts are simply skipped.
+
+As an example:
+
+.. literalinclude:: /tutorials/interactive-prompt/tutorial.yaml
+    :caption: docs/tutorials/interactive-prompt/tutorial.yaml
+    :language: yaml
+
+.. structured-tutorial:: interactive-prompt/tutorial.yaml
+
+In Sphinx, you can call ``structured-tutorial-part`` only twice, as prompts are simply skipped. The first
+part just creates a file. Since ``temporary_directory: true`` in the configuration, this will run in
+a temporary directory that is removed after running the tutorial:
+
+.. structured-tutorial-part::
+
+When running the tutorial, the user will now be prompted to confirm the current state. The prompt would
+contain the current working directory. Presumably, the user would check the contents of ``test.txt`` in that
+directory.

docs/tutorials/interactive-prompt/tutorial.yaml

@@ -0,0 +1,20 @@
+configuration:
+  run:
+    # Switch to temporary directory before running the tutorial
+    temporary_directory: true
+parts:
+  - commands:
+      - command: echo "some content" > test.txt
+      - command: echo "About to give you two prompts..."
+  # Just prompt the user to hit 'enter' at this point:
+  - prompt: "Hit enter to continue... "
+  # Ask the user to confirm the current state - if they answer "no", the tutorial will abort.
+  # In this case, we output the current working directory and ask the user to confirm:
+  - prompt: |-
+      Current working directory is {{ cwd }} ...
+      Is the current state satisfactory (y/n)?
+    type: confirm
+    # Set to false to also raise an error if the user just presses enter:
+    #default: true
+    # You can also overwrite the error message the user will get:
+    #error: Custom error encountered.

structured_tutorials/models.py

@@ -262,6 +262,23 @@ def set_default_context(self) -> Self:
         return self
 
 
+class PromptModel(BaseModel):
+    """Allows you to inspect the current state of the tutorial manually."""
+
+    model_config = ConfigDict(extra="forbid", title="Prompt Configuration")
+    prompt: str = Field(description=f"The prompt text. {TEMPLATE_DESCRIPTION}")
+    type: Literal["enter", "confirm"] = "enter"
+    default: bool = Field(
+        default=True, description="For type=`confirm`, the default if the user just presses enter."
+    )
+    error: str = Field(
+        default="State was not confirmed.",
+        description="For `type=confirm`, the error message if the user does not confirm the current state. "
+        "{TEMPLATE_DESCRIPTION} The context will also include the `response` variable, representing the user "
+        "response.",
+    )
+
+
 class ConfigurationModel(BaseModel):
     """Initial configuration of a tutorial."""
 
@@ -285,7 +302,7 @@ class TutorialModel(BaseModel):
         description="Directory from which relative file paths are resolved. Defaults to the path of the "
         "tutorial file.",
     )  # absolute path (input: relative to path)
-    parts: tuple[CommandsPartModel | FilePartModel, ...] = Field(
+    parts: tuple[CommandsPartModel | FilePartModel | PromptModel, ...] = Field(
         description="The individual parts of this tutorial."
     )
     configuration: ConfigurationModel = Field(default=ConfigurationModel())

structured_tutorials/runners/local.py

@@ -11,13 +11,15 @@
 import time
 from copy import deepcopy
 from pathlib import Path
+from typing import Any
 
 from jinja2 import Environment
 
 from structured_tutorials.models import (
     CleanupCommandModel,
     CommandsPartModel,
     FilePartModel,
+    PromptModel,
     TestCommandModel,
     TestPortModel,
     TutorialModel,
@@ -34,8 +36,8 @@ def __init__(self, tutorial: TutorialModel):
         self.env = Environment(keep_trailing_newline=True)
         self.cleanup: list[CleanupCommandModel] = []
 
-    def render(self, value: str) -> str:
-        return self.env.from_string(value).render(self.context)
+    def render(self, value: str, **context: Any) -> str:
+        return self.env.from_string(value).render({**self.context, **context})
 
     def run_test(self, test: TestCommandModel | TestPortModel) -> None:
         # If an initial delay is configured, wait that long
@@ -136,8 +138,26 @@ def write_file(self, part: FilePartModel) -> None:
         with open(destination, "w") as destination_stream:
             destination_stream.write(contents)
 
+    def run_prompt(self, part: PromptModel) -> None:
+        prompt = self.render(part.prompt).strip() + " "
+
+        if part.type == "enter":
+            input(prompt)
+        else:  # type == confirm
+            valid_inputs = ("n", "no", "yes", "y", "")
+            while (response := input(prompt).strip().lower()) not in valid_inputs:
+                print(f"Please enter a valid value ({'/'.join(valid_inputs)}).")
+
+            if response in ("n", "no") or (response == "" and not part.default):
+                error = self.render(part.error, response=response)
+                raise RuntimeError(error)
+
     def run_parts(self) -> None:
         for part in self.tutorial.parts:
+            if isinstance(part, PromptModel):
+                self.run_prompt(part)
+                continue
+
             if part.run.skip:
                 continue
 

structured_tutorials/sphinx/utils.py

@@ -13,7 +13,7 @@
 from sphinx.errors import ConfigError, ExtensionError
 
 from structured_tutorials import templates
-from structured_tutorials.models import CommandsPartModel, FilePartModel, TutorialModel
+from structured_tutorials.models import CommandsPartModel, FilePartModel, PromptModel, TutorialModel
 from structured_tutorials.textwrap import wrap_command_filter
 
 TEMPLATE_DIR = resources.files(templates)
@@ -135,6 +135,12 @@ def render_part(self) -> str:
         # Find the next part that is not skipped
         for part in self.tutorial.parts[self.next_part :]:
             self.next_part += 1
+
+            # Ignore prompt models when rendering tutorials.
+            if isinstance(part, PromptModel):
+                continue
+
+            # If the part is not configured to be skipped for docs, use it.
             if not part.doc.skip:
                 break
         else:

structured_tutorials/textwrap.py

@@ -81,7 +81,6 @@ def wrap_command_filter(command: str, prompt: str, text_width: int) -> str:
         command_line = re.sub(r"\s*\n\s*", " ", command_line).strip()
         if not command_line:
             continue
-        print(0, line_no, command_line)
 
         wrapper = CommandLineTextWrapper(width=text_width)
         if line_no == 1:

tests/runners/test_local.py

@@ -5,6 +5,7 @@
 
 from pathlib import Path
 from unittest import mock
+from unittest.mock import call
 
 import pytest
 from pytest_subprocess import FakeProcess
@@ -255,6 +256,111 @@ def test_file_part_with_contents_with_destination_template(tmp_path: Path) -> No
         runner.run()
 
 
+@pytest.mark.parametrize("prompt", ("test", "test    "))
+@pytest.mark.parametrize("answer", ("", "yes", "y", "no", "n", "foobar"))
+def test_enter_prompt(prompt: str, answer: str) -> None:
+    """Test enter function."""
+    configuration = TutorialModel.model_validate({"path": "/dummy.yaml", "parts": [{"prompt": prompt}]})
+    runner = LocalTutorialRunner(configuration)
+    with mock.patch("builtins.input", return_value=answer, autospec=True) as mock_input:
+        runner.run()
+    mock_input.assert_called_once_with(f"{prompt.strip()} ")
+
+
+@pytest.mark.parametrize("answer", ("", "y", "yes"))
+def test_confirm_prompt_confirms(answer: str) -> None:
+    """Test confirm prompt where empty answer passes."""
+    configuration = TutorialModel.model_validate(
+        {"path": "/dummy.yaml", "parts": [{"prompt": "example:", "type": "confirm"}]}
+    )
+    runner = LocalTutorialRunner(configuration)
+    with mock.patch("builtins.input", return_value=answer, autospec=True) as mock_input:
+        runner.run()
+    mock_input.assert_called_once_with("example: ")
+
+
+@pytest.mark.parametrize("answer", ("y", "yes"))
+def test_confirm_prompt_confirms_with_default_false(answer: str) -> None:
+    """Test confirm prompt where answer passes with default=False."""
+    configuration = TutorialModel.model_validate(
+        {"path": "/dummy.yaml", "parts": [{"prompt": "example:", "type": "confirm", "default": False}]}
+    )
+    runner = LocalTutorialRunner(configuration)
+    with mock.patch("builtins.input", return_value=answer, autospec=True) as mock_input:
+        runner.run()
+    mock_input.assert_called_once_with("example: ")
+
+
+@pytest.mark.parametrize("answer", ("", "n", "no"))
+def test_confirm_prompt_does_not_confirm_with_default_false(answer: str) -> None:
+    """Test confirm prompt where answer does not confirm with default=False."""
+    configuration = TutorialModel.model_validate(
+        {
+            "path": "/dummy.yaml",
+            "parts": [{"prompt": "example:", "type": "confirm", "default": False}],
+        }
+    )
+    runner = LocalTutorialRunner(configuration)
+    with mock.patch("builtins.input", return_value=answer, autospec=True) as mock_input:
+        with pytest.raises(RuntimeError, match=r"^State was not confirmed\.$"):
+            runner.run()
+    mock_input.assert_called_once_with("example: ")
+
+
+def test_confirm_prompt_with_invalid_response() -> None:
+    """Test confirm prompt where we first give an invalid response."""
+    configuration = TutorialModel.model_validate(
+        {
+            "path": "/dummy.yaml",
+            "parts": [{"prompt": "example:", "type": "confirm", "default": False}],
+        }
+    )
+    runner = LocalTutorialRunner(configuration)
+    with mock.patch("builtins.input", side_effect=["foobar", "y"], autospec=True) as mock_input:
+        runner.run()
+    mock_input.assert_has_calls([call("example: "), call("example: ")])
+
+
+def test_confirm_prompt_does_not_confirm_error_template() -> None:
+    """Test confirm prompt where answer does not confirm with default=False."""
+    answer = "no"
+    value = "example value"
+    configuration = TutorialModel.model_validate(
+        {
+            "path": "/dummy.yaml",
+            "configuration": {"run": {"context": {"example": value}}},
+            "parts": [
+                {
+                    "prompt": "example:",
+                    "type": "confirm",
+                    "default": False,
+                    "error": "{{ response }}: {{ example }}: This is wrong.",
+                }
+            ],
+        }
+    )
+    runner = LocalTutorialRunner(configuration)
+    with mock.patch("builtins.input", return_value=answer, autospec=True) as mock_input:
+        with pytest.raises(RuntimeError, match=rf"^{answer}: {value}: This is wrong\.$"):
+            runner.run()
+    mock_input.assert_called_once_with("example: ")
+
+
+def test_prompt_template() -> None:
+    """Test that the prompt is rendered as a template."""
+    configuration = TutorialModel.model_validate(
+        {
+            "path": "/dummy.yaml",
+            "configuration": {"run": {"context": {"example": "dest/"}}},
+            "parts": [{"prompt": "Go to {{ example }}"}],
+        }
+    )
+    runner = LocalTutorialRunner(configuration)
+    with mock.patch("builtins.input", return_value="", autospec=True) as mock_input:
+        runner.run()
+    mock_input.assert_called_once_with("Go to dest/ ")
+
+
 def test_temporary_directory(tmp_path: Path, fp: FakeProcess) -> None:
     """Test running in temporary directory."""
     fp.register("pwd")

tests/sphinx/test_wrapper.py

@@ -195,3 +195,26 @@ def test_multiple_parts_with_index_error() -> None:
     assert wrapper.render_part() == expected
     with pytest.raises(ExtensionError, match=r"No more parts left in tutorial\."):
         wrapper.render_part()
+
+
+@pytest.mark.parametrize(
+    ("parts", "expected"),
+    (
+        (
+            [
+                {"commands": [{"command": "true 1"}]},
+                {"prompt": "test"},
+                {"commands": [{"command": "true 2"}]},
+                {"commands": [{"command": "true 3"}]},
+            ],
+            ["user@host:~$ true 1\n", "user@host:~$ true 2\n", "user@host:~$ true 3\n"],
+        ),
+    ),
+)
+def test_prompt(parts: tuple[str, ...], expected: list[str]) -> None:
+    """Test rendering a code block that is preceded by a prompt. First rendered part is code block."""
+    tutorial = TutorialModel.model_validate({"path": Path.cwd(), "parts": parts})
+    wrapper = TutorialWrapper(tutorial)
+    assert wrapper.render_part() == f".. code-block:: console\n\n{textwrap.indent(expected[0], '    ')}"
+    assert wrapper.render_part() == f".. code-block:: console\n\n{textwrap.indent(expected[1], '    ')}"
+    assert wrapper.render_part() == f".. code-block:: console\n\n{textwrap.indent(expected[2], '    ')}"