pytorial 0.1__py3-none-any.whl

pytorial-0.1.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: pytorial
+Version: 0.1
+Summary: Interactive command-line tutorials with PTY-backed steps
+License-Expression: MIT
+License-File: LICENSE
+Author: Daniel Bosk
+Author-email: daniel@bosk.se
+Maintainer: Daniel Bosk
+Maintainer-email: dbosk@kth.se
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Education
+Requires-Dist: PyYAML (>=6)
+Requires-Dist: platformdirs (>=4)
+Requires-Dist: rich (>=12.3.0)
+Requires-Dist: typer (>=0.9.0)
+Project-URL: Bug Tracker, https://github.com/dbosk/tutorial/issues
+Project-URL: Repository, https://github.com/dbosk/tutorial
+Description-Content-Type: text/markdown
+
+# tutorial
+
+A Python library for interactive command-line tutorials.
+
+## Install
+
+```
+pipx install tutorial
+# or
+uv tool install tutorial
+```
+
+To run from a clone instead of an installed copy, see
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Usage
+
+The package ships with three built-in tutorials. The first one is a
+self-guided tour of the tool itself:
+
+```
+tutorial run using-tutorials
+```
+
+Companion tours: `tutorial run shell-basics` (shell and editor skills)
+and `tutorial run writing-tutorials` (authoring tutorials of your own).
+
+### Discover what's available
+
+```
+tutorial list
+```
+
+Pipe the same command into a script to get tab-separated rows instead
+of the rich table.
+
+### Run or resume
+
+```
+tutorial run <id>              # start or resume saved progress
+tutorial run --restart <id>    # discard saved progress and start over
+```
+
+### Review past runs
+
+```
+tutorial review <id>
+tutorial review <id> --step 2
+tutorial review <id> --run-id <run-id>
+```
+
+### Trust author-supplied shell checks
+
+```
+tutorial run --allow-shell-checks <id>
+```
+
+A tutorial step may declare a `check_command` that runs in your shell
+to validate the step. This validation is opt-in: pass
+`--allow-shell-checks` only when you trust the tutorial author.
+
+## Writing tutorials
+
+Take the interactive walkthrough first:
+
+```
+tutorial run writing-tutorials
+```
+
+### File format
+
+A tutorial is a single Markdown file beginning with YAML front matter:
+
+````markdown
+---
+id: my-tutorial
+title: My Tutorial
+summary: One-line description shown by `tutorial list`.
+---
+
+# First step
+
+```tutorial-step
+required_patterns:
+  - some-command
+hint: Try running `some-command`.
+```
+
+Step body in Markdown.
+````
+
+- Required front-matter fields: `id`, `title`, `summary`.
+- Each top-level `# Heading` becomes one step.
+- A step may begin with a fenced `tutorial-step` YAML block. Recognised
+  fields are `required_patterns`, `check_command`, `hint`, `edit_file`,
+  `kind`, `options`, and `answers`.
+- Without `kind` or `edit_file`, a step opens an interactive shell.
+- `edit_file` opens a workspace-relative file in `$EDITOR`, falling
+  back to `vim`, `vi`, or `nano` when `$EDITOR` is unset.
+- `kind: input`, `kind: single_select`, and `kind: multi_select` prompt
+  directly in the CLI instead of opening a shell or editor. `input`
+  answers use the same string-or-`{mode, pattern}` format as
+  `required_patterns`; select questions use literal option text in
+  `options` and `answers`.
+- `check_command` only runs when the reader passes
+  `--allow-shell-checks`.
+
+### Share and install
+
+Install a tutorial Markdown file or URL into the user's tutorial
+directory:
+
+```
+tutorial install path/to/tutorial.md
+tutorial install https://example.com/tutorial.md
+tutorial install --force path/to/tutorial.md
+```
+
+Use `--force` to overwrite an installed tutorial with the same `id`.
+The standalone CLI auto-loads installed tutorials alongside the
+built-ins.
+
+### Load ad hoc
+
+To use a tutorial without installing it, point at the file or directory
+on the command line:
+
+```
+tutorial list --tutorial-path some/dir
+tutorial run --tutorial-path some/dir <id>
+```
+
+`--tutorial-path` may be repeated and is appended after the built-ins.
+
+## Embedding the CLI
+
+The package can be mounted as a subcommand inside another Typer or
+argparse application via `add_typer_subcommand` and
+`add_argparse_subcommand` in `src/tutorial/cli.py`. Embedded hosts
+prepend the `using-tutorials` lesson before host-specific tutorials, do
+not load the user's installed tutorial directory, and hide the
+standalone-only `install` command.
+
+## Contributing
+
+For the literate sources, the `make` build, and the repo layout, see
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+

pytorial-0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+tutorial/__init__.py,sha256=eatCRqULsgRlm2__7DBJ3ki0YqWoffIVQcFT6-CYAic,1175
+tutorial/catalog.py,sha256=3zUnKaIgkkOMVYLJXjcRtmGEg2sHxAJBjBY1VQeDYIQ,17643
+tutorial/cli.py,sha256=K-q28ptUeXkPKlQXrdC_YBT077FEyQkmI8tUAqIK5iU,52421
+tutorial/model.py,sha256=_cDPIfcZTT131abiUAAUZ8nXbxsQ8N-pCsXS0iqiMZM,1815
+tutorial/run.py,sha256=jH1_UZUJ-p1JnA3o6zMJ3ryZmYKn4UgPeeR5a9k9BE0,21499
+tutorial/shell.py,sha256=ed6tVBkEI_duJfGx5LItTu1QWO-RrnmWmn_2aeiDWF4,8867
+tutorial/state.py,sha256=CGfO5UGzo0zWKLG0ZgGth6ljiUAH2rwpgzNtJRqekTA,6309
+tutorial/tutorials/shell-basics.md,sha256=fpIwJ2YajzvOYzAeTm-yFF8-1k6GjFfD7AhOUwR0Ge8,2246
+tutorial/tutorials/using-tutorials.md,sha256=qV4U3UgDErk02GB1aIWPlB6au8KfoatRx3rR25628Vw,6191
+tutorial/tutorials/writing-tutorials.md,sha256=pkmwADpD6zAj2YPMnO9U3F63Gw78BNAuyclpKZF6bYg,10321
+pytorial-0.1.dist-info/METADATA,sha256=t0NEy4ewqnKE4CDK6C4HWSEHWq1lw4KzM-OxErOMKe8,4495
+pytorial-0.1.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
+pytorial-0.1.dist-info/entry_points.txt,sha256=sOFyYbyaassv0DyP9PS2I0LliYiImMPJsXYOYt3yGpQ,71
+pytorial-0.1.dist-info/licenses/LICENSE,sha256=2Y2JY4tRQJtG0jXHpd6cYgeA-ce_JQ6lk8szzRanmU8,1068
+pytorial-0.1.dist-info/RECORD,,

pytorial-0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.2
+Root-Is-Purelib: true
+Tag: py3-none-any

pytorial-0.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+pytorial=tutorial.cli:app
+tutorial=tutorial.cli:app
+

pytorial-0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Daniel Bosk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tutorial/__init__.py

@@ -0,0 +1,41 @@
+"""Public package surface for ``tutorial``."""
+
+from tutorial.cli import add_argparse_subcommand
+from tutorial.cli import add_typer_subcommand
+from tutorial.cli import app
+from tutorial.cli import create_app
+from tutorial.catalog import TutorialCatalog
+from tutorial.catalog import get_tutorial
+from tutorial.catalog import get_tutorials
+from tutorial.model import StepTranscript
+from tutorial.model import TextMatch
+from tutorial.model import Tutorial
+from tutorial.model import TutorialRun
+from tutorial.model import TutorialStep
+from tutorial.run import RunResult
+from tutorial.run import TutorialRunner
+from tutorial.shell import run_interactive_shell
+from tutorial.shell import run_scripted_shell
+from tutorial.state import ProgressState
+from tutorial.state import StateStore
+
+__all__ = [
+    "ProgressState",
+    "RunResult",
+    "StateStore",
+    "StepTranscript",
+    "TextMatch",
+    "Tutorial",
+    "TutorialCatalog",
+    "TutorialRun",
+    "TutorialRunner",
+    "TutorialStep",
+    "add_argparse_subcommand",
+    "add_typer_subcommand",
+    "app",
+    "create_app",
+    "get_tutorial",
+    "get_tutorials",
+    "run_interactive_shell",
+    "run_scripted_shell",
+]