Metadata-Version: 2.4
Name: pytorial
Version: 0.6
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

# pytorial

A Python library for interactive command-line tutorials.

## Install

```
pipx install pytorial
# or
uv tool install pytorial
```

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 code

```
tutorial run --allow-shell <id>
```

A tutorial step may declare `pre_command`, `check_command`, or
`post_command`. Those fields run author-supplied shell code, so they are
opt-in: pass `--allow-shell` 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`, `pre_command`, `check_command`,
  `post_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`.
- `pre_command`, `check_command`, and `post_command` only run when the
  reader passes `--allow-shell`.
- Use one YAML string for each shell field. Multi-line shell scripts
  should use YAML `|` so one bash process sees the whole script and keeps
  `cd`, `export`, and shell options across lines.
- Do not use YAML `>` for shell fields: it folds newlines into spaces and
  can break shell syntax.

### 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/pytorial/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).

