structured-tutorials 0.1.0__py3-none-any.whl

structured_tutorials/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2025 Mathias Ertl
+# Licensed under the MIT License. See LICENSE file for details.
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("structured-tutorials")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "not-installed"

structured_tutorials/cli.py

@@ -0,0 +1,83 @@
+# Copyright (c) 2025 Mathias Ertl
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""Main CLI entrypoint."""
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+import yaml
+
+from structured_tutorials import __version__
+from structured_tutorials.errors import InvalidAlternativesSelectedError
+from structured_tutorials.models import TutorialModel
+from structured_tutorials.output import error, setup_logging
+from structured_tutorials.runners.local import LocalTutorialRunner
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Main entry function for the command-line."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument("path", type=Path)
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("-a", "--alternative", dest="alternatives", action="append", default=[])
+    parser.add_argument("--no-colors", action="store_true", default=False)
+    parser.add_argument(
+        "-n",
+        "--non-interactive",
+        dest="interactive",
+        action="store_false",
+        default=True,
+        help="Never prompt for any user input.",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        default="INFO",
+        help="Override root log level",
+    )
+    parser.add_argument(
+        "--hide-commands",
+        dest="show_commands",
+        action="store_false",
+        default=True,
+        help="Do not show commands that are run by the tutorial.",
+    )
+    parser.add_argument(
+        "--hide-command-output",
+        dest="show_command_output",
+        action="store_false",
+        default=True,
+        help="Do not show the output of commands that are run on the terminal.",
+    )
+    args = parser.parse_args(argv)
+
+    setup_logging(level=args.log_level, no_colors=args.no_colors, show_commands=args.show_commands)
+
+    try:
+        tutorial = TutorialModel.from_file(args.path)
+    except yaml.YAMLError as exc:  # an invalid YAML file
+        error(f"{args.path}: Invalid YAML file:")
+        print(exc, file=sys.stderr)
+        sys.exit(1)
+    except ValueError as ex:  # thrown by Pydantic model loading
+        error(f"{args.path}: File is not a valid Tutorial:")
+        print(ex, file=sys.stderr)
+        sys.exit(1)
+
+    runner = LocalTutorialRunner(
+        tutorial,
+        alternatives=tuple(args.alternatives),
+        show_command_output=args.show_command_output,
+        interactive=args.interactive,
+    )
+
+    try:
+        runner.validate_alternatives()
+    except InvalidAlternativesSelectedError as ex:
+        error(str(ex))
+        sys.exit(1)
+
+    runner.run()

structured_tutorials/errors.py

@@ -0,0 +1,40 @@
+# Copyright (c) 2025 Mathias Ertl
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""Collection of errors thrown by this project."""
+
+
+class StructuredTutorialError(Exception):
+    """Base class for all exceptions thrown by this project."""
+
+
+class InvalidAlternativesSelectedError(StructuredTutorialError):
+    """Exception raised when an invalid alternative is selected."""
+
+
+class PartError(StructuredTutorialError):
+    """Base class for all errors happening in a specific part."""
+
+
+class CommandsPartError(PartError):
+    """Base class for all errors happening in a specific commands part."""
+
+
+class CommandTestError(CommandsPartError):
+    """Base class for exceptions when a test for a command fails."""
+
+
+class CommandOutputTestError(CommandTestError):
+    """Exception raised when an output test fails."""
+
+
+class FilePartError(PartError):
+    """Exception raised for errors in file parts."""
+
+
+class DestinationIsADirectoryError(FilePartError):
+    """Exception raised when a destination is a directory."""
+
+
+class PromptNotConfirmedError(PartError):
+    """Exception raised when a user does not confirm the current state in a prompt part."""

structured_tutorials/models/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2025 Mathias Ertl
+# Licensed under the MIT License. See LICENSE file for details.
+
+from structured_tutorials.models.parts import AlternativeModel, CommandsPartModel, FilePartModel, PromptModel
+from structured_tutorials.models.tutorial import TutorialModel
+
+__all__ = [
+    "AlternativeModel",
+    "AlternativeModel",
+    "CommandsPartModel",
+    "FilePartModel",
+    "PromptModel",
+    "TutorialModel",
+]

structured_tutorials/models/base.py

@@ -0,0 +1,97 @@
+# Copyright (c) 2025 Mathias Ertl
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""Base model classes."""
+
+from pathlib import Path
+from typing import Annotated, Any
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    NonNegativeFloat,
+    NonNegativeInt,
+    field_validator,
+    model_validator,
+)
+from pydantic.fields import FieldInfo
+
+from structured_tutorials.typing import Self
+
+# Type for commands to execute
+CommandType = str | tuple[str, ...]
+
+TEMPLATE_DESCRIPTION = "This value is rendered as a template with the current context."
+
+
+def default_tutorial_root_factory(data: dict[str, Any]) -> Path:
+    """Default factory for the tutorial_root variable."""
+    tutorial_root = data["path"].parent
+    assert isinstance(tutorial_root, Path)
+    return tutorial_root
+
+
+def template_field_title_generator(field_name: str, field_info: FieldInfo) -> str:
+    """Field title generator for template fields."""
+    return f"{field_name.title()} (template)"
+
+
+class CommandBaseModel(BaseModel):
+    """Base model for commands."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status_code: Annotated[int, Field(ge=0, le=255)] = 0
+    show_output: bool = Field(
+        default=True, description="Set to `False` to always hide the output of this command."
+    )
+
+
+class TestSpecificationMixin:
+    """Mixin for specifying tests."""
+
+    delay: Annotated[float, Field(ge=0)] = 0
+    retry: NonNegativeInt = 0
+    backoff_factor: NonNegativeFloat = 0  # {backoff factor} * (2 ** ({number of previous retries}))
+
+
+class ConfigurationMixin:
+    """Mixin for configuration models."""
+
+    skip: bool = Field(default=False, description="Skip this part.")
+    update_context: dict[str, Any] = Field(default_factory=dict)
+
+
+class FileMixin:
+    """Mixin for specifying a file (used in file part and for stdin of commands)."""
+
+    contents: str | None = Field(
+        default=None,
+        field_title_generator=template_field_title_generator,
+        description=f"Contents of the file. {TEMPLATE_DESCRIPTION}",
+    )
+    source: Path | None = Field(
+        default=None,
+        field_title_generator=template_field_title_generator,
+        description="The source path of the file to create. Unless `template` is `False`, the file is loaded "
+        "into memory and rendered as template.",
+    )
+    template: bool = Field(
+        default=True, description="Whether the file contents should be rendered in a template."
+    )
+
+    @field_validator("source", mode="after")
+    @classmethod
+    def validate_source(cls, value: Path) -> Path:
+        if value.is_absolute():
+            raise ValueError(f"{value}: Must be a relative path (relative to the current cwd).")
+        return value
+
+    @model_validator(mode="after")
+    def validate_contents_or_source(self) -> Self:
+        if self.contents is None and self.source is None:
+            raise ValueError("Either contents or source is required.")
+        if self.contents is not None and self.source is not None:
+            raise ValueError("Only one of contents or source is allowed.")
+        return self

structured_tutorials/models/parts.py

@@ -0,0 +1,227 @@
+# Copyright (c) 2025 Mathias Ertl
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""Basic tutorial structure."""
+
+import os
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Discriminator, Field, NonNegativeInt, Tag, model_validator
+
+from structured_tutorials.models.base import (
+    TEMPLATE_DESCRIPTION,
+    CommandBaseModel,
+    CommandType,
+    ConfigurationMixin,
+    FileMixin,
+    template_field_title_generator,
+)
+from structured_tutorials.models.tests import TestCommandModel, TestOutputModel, TestPortModel
+from structured_tutorials.typing import Self
+
+
+def part_discriminator(value: Any) -> str | None:
+    """Discriminator for parts."""
+    if isinstance(value, dict):
+        if typ := value.get("type"):
+            return typ  # type: ignore[no-any-return]
+        if "commands" in value:
+            return "commands"
+        if "destination" in value:
+            return "file"
+        if "prompt" in value:
+            return "prompt"
+        if "alternatives" in value:  # pragma: no branch  # all alternatives covered
+            return "alternatives"
+
+    elif isinstance(value, PartMixin):  # pragma: no cover  # not really sure how to trigger this
+        return value.type
+    return None  # pragma: no cover  # not really sure how to trigger this
+
+
+class PartMixin:
+    """Mixin used by all parts."""
+
+    type: str
+    id: str = Field(default="", description="ID that can be used to reference the specific part.")
+    index: int = Field(default=0, description="Index of the part in the tutorial.")
+    name: str = Field(default="", description="Human-readable name of the part.")
+
+
+class CleanupCommandModel(CommandBaseModel):
+    """Command to clean up artifacts created by the current part."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    command: CommandType = Field(description="Command that cleans up artifacts created by the main command.")
+
+
+class StdinCommandModel(FileMixin, BaseModel):
+    """Standard input for a command."""
+
+
+class CommandRuntimeConfigurationModel(ConfigurationMixin, CommandBaseModel):
+    """Model for runtime configuration when running a single command."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    chdir: Path | None = Field(default=None, description="Change working directory to this path.")
+    cleanup: tuple[CleanupCommandModel, ...] = tuple()
+    test: tuple[TestCommandModel | TestPortModel | TestOutputModel, ...] = tuple()
+    stdin: StdinCommandModel | None = None
+
+
+class CommandDocumentationConfigurationModel(ConfigurationMixin, BaseModel):
+    """Model for documenting a single command."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    output: str = ""
+
+
+class CommandModel(BaseModel):
+    """A single command to run in this part."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    command: CommandType = Field(description="The command to run.")
+    run: CommandRuntimeConfigurationModel = Field(
+        default=CommandRuntimeConfigurationModel(), description="The runtime configuration."
+    )
+    doc: CommandDocumentationConfigurationModel = Field(
+        default=CommandDocumentationConfigurationModel(), description="The documentation configuration."
+    )
+
+
+class CommandsRuntimeConfigurationModel(ConfigurationMixin, BaseModel):
+    """Runtime configuration for an entire commands part."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CommandsDocumentationConfigurationModel(ConfigurationMixin, BaseModel):
+    """Documentation configuration for an entire commands part."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CommandsPartModel(PartMixin, BaseModel):
+    """A tutorial part consisting of one or more commands."""
+
+    model_config = ConfigDict(extra="forbid", title="Command part")
+
+    type: Literal["commands"] = "commands"
+    commands: tuple[CommandModel, ...]
+
+    run: CommandsRuntimeConfigurationModel = CommandsRuntimeConfigurationModel()
+    doc: CommandsDocumentationConfigurationModel = CommandsDocumentationConfigurationModel()
+
+
+class FileRuntimeConfigurationModel(ConfigurationMixin, BaseModel):
+    """Configure a file part when running the tutorial."""
+
+    model_config = ConfigDict(extra="forbid", title="File part runtime configuration")
+
+
+class FileDocumentationConfigurationModel(ConfigurationMixin, BaseModel):
+    """Configure a file part when rendering it as documentation.
+
+    For the `language`, `caption`, `linenos`, `lineno_start`, `emphasize_lines` and `name` options, please
+    consult the [sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block).
+    """
+
+    model_config = ConfigDict(extra="forbid", title="File part documentation configuration")
+
+    # sphinx options:
+    language: str = Field(default="", description="The language used for the code block directive.")
+    caption: str | Literal[False] = Field(
+        default="",
+        description=f"The caption. Defaults to the `destination` of this part. {TEMPLATE_DESCRIPTION}",
+    )
+    linenos: bool = False
+    lineno_start: NonNegativeInt | Literal[False] = False
+    emphasize_lines: str = ""
+    name: str = ""
+    ignore_spelling: bool = Field(
+        default=False,
+        description="If true, wrap the caption in `:spelling:ignore:` (see"
+        " [sphinxcontrib.spelling](https://sphinxcontrib-spelling.readthedocs.io/en/latest/)).",
+    )
+
+
+class FilePartModel(PartMixin, FileMixin, BaseModel):
+    """A tutorial part for creating a file.
+
+    Note that exactly one of `contents` or `source` is required.
+    """
+
+    model_config = ConfigDict(extra="forbid", title="File part")
+
+    type: Literal["file"] = "file"
+
+    destination: str = Field(
+        field_title_generator=template_field_title_generator,
+        description=f"The destination path of the file. {TEMPLATE_DESCRIPTION}",
+    )
+
+    doc: FileDocumentationConfigurationModel = FileDocumentationConfigurationModel()
+    run: FileRuntimeConfigurationModel = FileRuntimeConfigurationModel()
+
+    @model_validator(mode="after")
+    def validate_destination(self) -> Self:
+        if not self.source and self.destination.endswith(os.sep):
+            raise ValueError(f"{self.destination}: Destination must not be a directory if contents is given.")
+        return self
+
+
+class PromptModel(PartMixin, BaseModel):
+    """Allows you to inspect the current state of the tutorial manually."""
+
+    model_config = ConfigDict(extra="forbid", title="Prompt Configuration")
+
+    type: Literal["prompt"] = "prompt"
+    prompt: str = Field(description=f"The prompt text. {TEMPLATE_DESCRIPTION}")
+    response: 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.",
+    )
+
+
+PartModels = Annotated[CommandsPartModel, Tag("commands")] | Annotated[FilePartModel, Tag("file")]
+
+
+class AlternativeRuntimeConfigurationModel(ConfigurationMixin, BaseModel):
+    """Configure an alternative part when running the tutorial."""
+
+    model_config = ConfigDict(extra="forbid", title="File part runtime configuration")
+
+
+class AlternativeDocumentationConfigurationModel(ConfigurationMixin, BaseModel):
+    """Configure an alternative part when documenting the tutorial."""
+
+    model_config = ConfigDict(extra="forbid", title="File part runtime configuration")
+
+
+class AlternativeModel(PartMixin, BaseModel):
+    """A tutorial part that has several different alternatives.
+
+    When rendering documentation, alternatives are rendered in tabs. When running a tutorial, the runner has
+    to specify exactly one (or at most one, if `required=False`) of the alternatives that should be run.
+
+    An alternative can contain parts for files or commands.
+    """
+
+    model_config = ConfigDict(extra="forbid", title="Alternatives")
+
+    type: Literal["alternatives"] = "alternatives"
+    alternatives: dict[str, Annotated[PartModels, Discriminator(part_discriminator)]]
+    required: bool = Field(default=True, description="Whether one of the alternatives is required.")
+    doc: AlternativeDocumentationConfigurationModel = AlternativeDocumentationConfigurationModel()
+    run: AlternativeRuntimeConfigurationModel = AlternativeRuntimeConfigurationModel()

structured_tutorials/models/tests.py

@@ -0,0 +1,40 @@
+# Copyright (c) 2025 Mathias Ertl
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""Test specifications for commands."""
+
+import re
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
+
+from structured_tutorials.models.base import CommandBaseModel, CommandType, TestSpecificationMixin
+from structured_tutorials.models.validators import validate_regex
+
+
+class TestCommandModel(TestSpecificationMixin, CommandBaseModel):
+    """Test a command by running another command."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    command: CommandType = Field(description="The command to run.")
+
+
+class TestPortModel(TestSpecificationMixin, BaseModel):
+    """Test a command by checking if a port is open."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    host: str = Field(description="The host to connect to.")
+    port: Annotated[int, Field(ge=0, le=65535)] = Field(description="The port to connect to.")
+
+
+class TestOutputModel(BaseModel):
+    """Test a command by checking the output of a command."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    stream: Literal["stdout", "stderr"] = Field(default="stdout", description="The output stream to use.")
+    regex: Annotated[re.Pattern[bytes], BeforeValidator(validate_regex)] = Field(
+        description="A regular expression to test."
+    )

structured_tutorials/models/tutorial.py

@@ -0,0 +1,150 @@
+# Copyright (c) 2025 Mathias Ertl
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""Module containing main tutorial model and global configuration models."""
+
+from pathlib import Path
+from typing import Annotated, Any
+
+from pydantic import BaseModel, ConfigDict, Discriminator, Field, Tag, field_validator, model_validator
+from pydantic_core.core_schema import ValidationInfo
+from yaml import safe_load
+
+from structured_tutorials.models.base import default_tutorial_root_factory
+from structured_tutorials.models.parts import AlternativeModel, PartModels, PromptModel, part_discriminator
+from structured_tutorials.typing import Self
+
+
+class DocumentationConfigurationModel(BaseModel):
+    """Initial configuration for rendering the tutorial as documentation."""
+
+    model_config = ConfigDict(extra="forbid", title="Documentation Configuration")
+
+    context: dict[str, Any] = Field(
+        default_factory=dict, description="Key/value pairs for the initial context when rendering templates."
+    )
+    alternative_names: dict[str, str] = Field(
+        default_factory=dict,
+        description="Names for alternative keys, used in tab titles. By default, the key itself is used.",
+    )
+
+    @model_validator(mode="after")
+    def set_default_context(self) -> Self:
+        self.context["run"] = False
+        self.context["doc"] = True
+        self.context.setdefault("user", "user")
+        self.context.setdefault("host", "host")
+        self.context.setdefault("cwd", "~")
+        self.context.setdefault(
+            "prompt_template",
+            "{{ user }}@{{ host }}:{{ cwd }}{% if user == 'root' %}#{% else %}${% endif %} ",
+        )
+        return self
+
+
+class RuntimeConfigurationModel(BaseModel):
+    """Initial configuration for running the tutorial."""
+
+    model_config = ConfigDict(extra="forbid", title="Runtime Configuration")
+
+    context: dict[str, Any] = Field(
+        default_factory=dict, description="Key/value pairs for the initial context when rendering templates."
+    )
+    temporary_directory: bool = Field(
+        default=False, description="Switch to an empty temporary directory before running the tutorial."
+    )
+    git_export: bool = Field(
+        default=False,
+        description="Export a git archive to a temporary directory before running the tutorial.",
+    )
+
+    @model_validator(mode="after")
+    def set_default_context(self) -> Self:
+        self.context["doc"] = False
+        self.context["run"] = True
+        self.context["cwd"] = Path.cwd()
+        return self
+
+
+class ConfigurationModel(BaseModel):
+    """Initial configuration of a tutorial."""
+
+    model_config = ConfigDict(extra="forbid", title="Tutorial Configuration")
+
+    run: RuntimeConfigurationModel = RuntimeConfigurationModel()
+    doc: DocumentationConfigurationModel = DocumentationConfigurationModel()
+    context: dict[str, Any] = Field(
+        default_factory=dict, description="Initial context for both documentation and runtime."
+    )
+
+
+class TutorialModel(BaseModel):
+    """Root structure for the entire tutorial."""
+
+    model_config = ConfigDict(extra="forbid", title="Tutorial")
+
+    # absolute path to YAML file
+    path: Path = Field(
+        description="Absolute path to the tutorial file. This field is populated automatically while loading the tutorial.",  # noqa: E501
+    )
+    tutorial_root: Path = Field(
+        default_factory=default_tutorial_root_factory,
+        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[
+        Annotated[
+            PartModels
+            | Annotated[PromptModel, Tag("prompt")]
+            | Annotated[AlternativeModel, Tag("alternatives")],
+            Discriminator(part_discriminator),
+        ],
+        ...,
+    ] = Field(description="The individual parts of this tutorial.")
+    configuration: ConfigurationModel = Field(default=ConfigurationModel())
+
+    @field_validator("path", mode="after")
+    @classmethod
+    def validate_path(cls, value: Path, info: ValidationInfo) -> Path:
+        if not value.is_absolute():
+            raise ValueError(f"{value}: Must be an absolute path.")
+        return value
+
+    @field_validator("tutorial_root", mode="after")
+    @classmethod
+    def resolve_tutorial_root(cls, value: Path, info: ValidationInfo) -> Path:
+        if value.is_absolute():
+            raise ValueError(f"{value}: Must be a relative path (relative to the tutorial file).")
+        path: Path = info.data["path"]
+
+        return (path.parent / value).resolve()
+
+    @model_validator(mode="after")
+    def update_context(self) -> Self:
+        self.configuration.run.context["tutorial_path"] = self.path
+        self.configuration.run.context["tutorial_dir"] = self.path.parent
+        self.configuration.doc.context["tutorial_path"] = self.path
+        self.configuration.doc.context["tutorial_dir"] = self.path.parent
+        return self
+
+    @model_validator(mode="after")
+    def update_part_data(self) -> Self:
+        for part_no, part in enumerate(self.parts):
+            part.index = part_no
+            if not part.id:
+                part.id = str(part_no)
+        return self
+
+    @classmethod
+    def from_file(cls, path: Path) -> "TutorialModel":
+        """Load a tutorial from a YAML file."""
+        with open(path) as stream:
+            tutorial_data = safe_load(stream)
+
+        # e.g. an empty YAML file will return None
+        if not isinstance(tutorial_data, dict):
+            raise ValueError("File does not contain a mapping at top level.")
+
+        tutorial_data["path"] = path.resolve()
+        tutorial = TutorialModel.model_validate(tutorial_data, context={"path": path})
+        return tutorial

structured_tutorials/models/validators.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2025 Mathias Ertl
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""Validators for various models."""
+
+import re
+from typing import Any
+
+
+def validate_regex(value: Any) -> Any:
+    """Validate and compile a regular expression."""
+    if isinstance(value, str):
+        return re.compile(value.encode())
+    return value  # pragma: no cover