md-demo 0.1.0__tar.gz

md_demo-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.2
+Name: md-demo
+Version: 0.1.0
+Summary: A lightweight Markdown demo runner.
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# md-demo
+
+`md-demo` is a lightweight Markdown demo runner. It executes explicitly marked code blocks, captures stdout and stderr, and writes generated output back into the Markdown file.
+
+It is meant for readable demo documents that stay useful as plain Markdown. It is not a notebook system, a sandbox, or a runner for untrusted code.
+
+Warning: `md-demo` executes code from the document. Run only trusted files.
+
+## Install
+
+From a source checkout:
+
+```bash
+python -m pip install -e ".[test]"
+```
+
+Verify the checkout:
+
+```bash
+python -m compileall -q src
+pytest
+```
+
+## Quick start
+
+Create a Markdown file with one runtime and one executable block.
+
+````markdown
+---
+md-demo:
+  runtime: python
+---
+
+```python exe
+print("hello")
+```
+````
+
+Run:
+
+```bash
+md-demo demo.md
+```
+
+`md-demo` updates the file in place by default and inserts a generated result block:
+
+````markdown
+```python exe
+print("hello")
+```
+
+<!-- md-demo: result start. Do not edit; this block is overwritten. -->
+```text
+hello
+```
+<!-- md-demo: result end -->
+````
+
+Do not edit generated result blocks. They are cleared and recreated on normal runs.
+
+## Document config
+
+Every runnable document needs config with one runtime. There are two supported forms.
+
+Use YAML front matter by default:
+
+```yaml
+---
+md-demo:
+  runtime: python
+---
+```
+
+If your Markdown renderer shows front matter as visible page content, use hidden HTML comment config instead:
+
+````markdown
+<!-- md-demo
+runtime: python
+-->
+````
+
+Both forms are parsed only at the top of the document. `md-demo` preserves whichever form the document already uses by default.
+
+To convert config style while running or clearing a document, use `--config-style`:
+
+```bash
+md-demo demo.md --config-style preserve
+md-demo demo.md --config-style front-matter
+md-demo demo.md --config-style hidden
+```
+
+`preserve` is the default and does not rewrite the config style. `front-matter` rewrites the document's `md-demo` config as YAML front matter. `hidden` rewrites the document's `md-demo` config as an HTML comment. Only the `md-demo` config is converted; unrelated front matter is preserved when practical.
+
+Supported runtime values:
+
+- `python`
+- `python3`
+- `bash`
+- `shell`
+
+`python3` is an alias for the Python runner. `shell` is an alias for the bash runner, not `/bin/sh`.
+
+## Output labels
+
+You can optionally add visible text before every generated output block with `preface-text`.
+
+YAML front matter:
+
+```yaml
+---
+md-demo:
+  runtime: python
+  preface-text: "Output:"
+---
+```
+
+Hidden HTML comment config:
+
+````markdown
+<!-- md-demo
+runtime: python
+preface-text: "Output:"
+-->
+````
+
+If `preface-text` is missing, empty, or `null`, no label is inserted. The label is generated inside the result region, so changing `preface-text` updates existing results the next time `md-demo` runs.
+
+## Executable blocks
+
+Only matching-language fenced code blocks marked with `exe` run.
+
+````markdown
+```python exe
+print("runs")
+```
+````
+
+Ordinary code blocks are examples only:
+
+````markdown
+```python
+print("shown, not run")
+```
+````
+
+Executable blocks run top-to-bottom in one persistent runtime. Python variables, imports, functions, shell variables, and shell directory changes can carry forward to later executable blocks.
+
+`md-demo` captures stdout and stderr. Python blocks should use `print` for values that should appear in the document. Python last-expression display is not part of v1.
+
+## CLI
+
+Update a document in place:
+
+```bash
+md-demo demo.md
+```
+
+Write the updated Markdown elsewhere:
+
+```bash
+md-demo demo.md --output rendered.md
+```
+
+Write the updated Markdown to stdout:
+
+```bash
+md-demo demo.md --output -
+```
+
+Clear generated result blocks without executing code:
+
+```bash
+md-demo demo.md --clear
+```
+
+Rewrite config style without executing code:
+
+```bash
+md-demo demo.md --clear --config-style hidden
+```
+
+Print concise help:
+
+```bash
+md-demo --help
+```
+
+Print the detailed manual:
+
+```bash
+md-demo --manual
+```
+
+## Failure behavior
+
+A normal run behaves like clear and execute:
+
+1. Old generated results are cleared.
+2. Executable blocks run top-to-bottom.
+3. Fresh result blocks are inserted for blocks that actually ran.
+
+If a block fails, `md-demo` writes output through the failed block, stops before later executable blocks, and exits nonzero. Later executable blocks are left without result blocks because they did not run.
+
+Intentional failures should be handled inside the demo code:
+
+```python
+try:
+    validate("")
+except ValueError as exc:
+    print(type(exc).__name__, exc)
+```
+
+## Converting existing documents
+
+- See [docs/markdown-conversion.md](docs/markdown-conversion.md) for converting ordinary Markdown documents.
+- See [docs/jupyter-conversion.md](docs/jupyter-conversion.md) for converting Jupyter notebooks, usually by exporting to Markdown first.
+- See [docs/design.md](docs/design.md) for the design.
+
+
+## AI Disclosure
+
+This tool was primarily generated with assistance from ChatGPT Codex, guided and directed by a human developer. Human involvement included requirements definition, some implementation direction, and cursory code review. The code has not undergone a comprehensive human audit or formal security review.

md_demo-0.1.0/README.md

@@ -0,0 +1,222 @@
+# md-demo
+
+`md-demo` is a lightweight Markdown demo runner. It executes explicitly marked code blocks, captures stdout and stderr, and writes generated output back into the Markdown file.
+
+It is meant for readable demo documents that stay useful as plain Markdown. It is not a notebook system, a sandbox, or a runner for untrusted code.
+
+Warning: `md-demo` executes code from the document. Run only trusted files.
+
+## Install
+
+From a source checkout:
+
+```bash
+python -m pip install -e ".[test]"
+```
+
+Verify the checkout:
+
+```bash
+python -m compileall -q src
+pytest
+```
+
+## Quick start
+
+Create a Markdown file with one runtime and one executable block.
+
+````markdown
+---
+md-demo:
+  runtime: python
+---
+
+```python exe
+print("hello")
+```
+````
+
+Run:
+
+```bash
+md-demo demo.md
+```
+
+`md-demo` updates the file in place by default and inserts a generated result block:
+
+````markdown
+```python exe
+print("hello")
+```
+
+<!-- md-demo: result start. Do not edit; this block is overwritten. -->
+```text
+hello
+```
+<!-- md-demo: result end -->
+````
+
+Do not edit generated result blocks. They are cleared and recreated on normal runs.
+
+## Document config
+
+Every runnable document needs config with one runtime. There are two supported forms.
+
+Use YAML front matter by default:
+
+```yaml
+---
+md-demo:
+  runtime: python
+---
+```
+
+If your Markdown renderer shows front matter as visible page content, use hidden HTML comment config instead:
+
+````markdown
+<!-- md-demo
+runtime: python
+-->
+````
+
+Both forms are parsed only at the top of the document. `md-demo` preserves whichever form the document already uses by default.
+
+To convert config style while running or clearing a document, use `--config-style`:
+
+```bash
+md-demo demo.md --config-style preserve
+md-demo demo.md --config-style front-matter
+md-demo demo.md --config-style hidden
+```
+
+`preserve` is the default and does not rewrite the config style. `front-matter` rewrites the document's `md-demo` config as YAML front matter. `hidden` rewrites the document's `md-demo` config as an HTML comment. Only the `md-demo` config is converted; unrelated front matter is preserved when practical.
+
+Supported runtime values:
+
+- `python`
+- `python3`
+- `bash`
+- `shell`
+
+`python3` is an alias for the Python runner. `shell` is an alias for the bash runner, not `/bin/sh`.
+
+## Output labels
+
+You can optionally add visible text before every generated output block with `preface-text`.
+
+YAML front matter:
+
+```yaml
+---
+md-demo:
+  runtime: python
+  preface-text: "Output:"
+---
+```
+
+Hidden HTML comment config:
+
+````markdown
+<!-- md-demo
+runtime: python
+preface-text: "Output:"
+-->
+````
+
+If `preface-text` is missing, empty, or `null`, no label is inserted. The label is generated inside the result region, so changing `preface-text` updates existing results the next time `md-demo` runs.
+
+## Executable blocks
+
+Only matching-language fenced code blocks marked with `exe` run.
+
+````markdown
+```python exe
+print("runs")
+```
+````
+
+Ordinary code blocks are examples only:
+
+````markdown
+```python
+print("shown, not run")
+```
+````
+
+Executable blocks run top-to-bottom in one persistent runtime. Python variables, imports, functions, shell variables, and shell directory changes can carry forward to later executable blocks.
+
+`md-demo` captures stdout and stderr. Python blocks should use `print` for values that should appear in the document. Python last-expression display is not part of v1.
+
+## CLI
+
+Update a document in place:
+
+```bash
+md-demo demo.md
+```
+
+Write the updated Markdown elsewhere:
+
+```bash
+md-demo demo.md --output rendered.md
+```
+
+Write the updated Markdown to stdout:
+
+```bash
+md-demo demo.md --output -
+```
+
+Clear generated result blocks without executing code:
+
+```bash
+md-demo demo.md --clear
+```
+
+Rewrite config style without executing code:
+
+```bash
+md-demo demo.md --clear --config-style hidden
+```
+
+Print concise help:
+
+```bash
+md-demo --help
+```
+
+Print the detailed manual:
+
+```bash
+md-demo --manual
+```
+
+## Failure behavior
+
+A normal run behaves like clear and execute:
+
+1. Old generated results are cleared.
+2. Executable blocks run top-to-bottom.
+3. Fresh result blocks are inserted for blocks that actually ran.
+
+If a block fails, `md-demo` writes output through the failed block, stops before later executable blocks, and exits nonzero. Later executable blocks are left without result blocks because they did not run.
+
+Intentional failures should be handled inside the demo code:
+
+```python
+try:
+    validate("")
+except ValueError as exc:
+    print(type(exc).__name__, exc)
+```
+
+## Converting existing documents
+
+- See [docs/markdown-conversion.md](docs/markdown-conversion.md) for converting ordinary Markdown documents.
+- See [docs/jupyter-conversion.md](docs/jupyter-conversion.md) for converting Jupyter notebooks, usually by exporting to Markdown first.
+- See [docs/design.md](docs/design.md) for the design.
+
+
+## AI Disclosure
+
+This tool was primarily generated with assistance from ChatGPT Codex, guided and directed by a human developer. Human involvement included requirements definition, some implementation direction, and cursory code review. The code has not undergone a comprehensive human audit or formal security review.

md_demo-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68,<77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "md-demo"
+description = "A lightweight Markdown demo runner."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+dependencies = ["PyYAML>=6"]
+dynamic = ["version"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.scripts]
+md-demo = "md_demo.cli:main"
+
+[tool.setuptools]
+license-files = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "md_demo.__version__"}
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310"]
+
+[tool.isort]
+profile = "black"
+line_length = 100

md_demo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

md_demo-0.1.0/src/md_demo/__init__.py

@@ -0,0 +1,3 @@
+"""Lightweight Markdown demo runner."""
+
+__version__ = "0.1.0"

md_demo-0.1.0/src/md_demo/cli.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .document import process_file, write_output
+from .errors import ExecutionFailed, MdDemoError
+from .manual import MANUAL
+
+HELP_DESCRIPTION = """A lightweight Markdown demo runner.
+
+By default, md-demo updates FILE in place.
+Use --output PATH to write elsewhere, or --output - to write to stdout.
+
+Warning: md-demo executes code from the document. Run only trusted files.
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="md-demo",
+        description=HELP_DESCRIPTION,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("file", nargs="?", help="Markdown file to process")
+    parser.add_argument(
+        "--clear", action="store_true", help="remove generated result blocks without executing code"
+    )
+    parser.add_argument(
+        "--config-style",
+        choices=["preserve", "front-matter", "hidden"],
+        default="preserve",
+        help="config rewrite style; default preserve keeps the existing style",
+    )
+    parser.add_argument("--output", help="write updated Markdown to PATH; use - for stdout")
+    parser.add_argument(
+        "--manual", action="store_true", help="print the detailed authoring and usage guide"
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.manual:
+        print(MANUAL, end="")
+        return 0
+    if not args.file:
+        parser.error("FILE is required unless --manual is used")
+    path = Path(args.file)
+    try:
+        result = process_file(path, clear=args.clear, config_style=args.config_style)
+        write_output(path, result.text, args.output)
+        for warning in result.warnings:
+            print(warning, file=sys.stderr)
+        if args.output is None:
+            print(f"updated {path}", file=sys.stderr)
+        return 0
+    except ExecutionFailed as exc:
+        write_output(path, exc.document, args.output)
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except MdDemoError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except OSError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

md_demo-0.1.0/src/md_demo/config.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import dataclasses
+from typing import Literal
+
+import yaml
+
+from .errors import MdDemoError
+
+ConfigStyle = Literal["preserve", "front-matter", "hidden"]
+
+
+@dataclasses.dataclass(frozen=True)
+class ConfigBlock:
+    config: dict
+    body_start: int
+    style: str
+    front_matter: dict
+
+
+def parse_config(lines: list[str]) -> ConfigBlock:
+    if not lines:
+        raise MdDemoError("missing md-demo.runtime")
+    first = lines[0].strip()
+    if first == "---":
+        end_index = _find_end(lines, start=1, marker="---", error="unterminated YAML front matter")
+        data = load_yaml_config("".join(lines[1:end_index]), "front matter")
+        config = data.get("md-demo")
+        if not isinstance(config, dict):
+            raise MdDemoError("missing md-demo.runtime in front matter")
+        return ConfigBlock(
+            config=config, body_start=end_index + 1, style="front-matter", front_matter=data
+        )
+    if first.startswith("<!-- md-demo") and first[len("<!-- md-demo") :].strip() in {"", "-->"}:
+        if first.endswith("-->"):
+            raise MdDemoError("missing md-demo.runtime")
+        end_index = _find_end(
+            lines,
+            start=1,
+            marker="-->",
+            error="unterminated md-demo HTML comment config",
+        )
+        data = load_yaml_config("".join(lines[1:end_index]), "md-demo HTML comment config")
+        config = data.get("md-demo") if isinstance(data.get("md-demo"), dict) else data
+        if not isinstance(config, dict):
+            raise MdDemoError("md-demo HTML comment config must be a mapping")
+        body_start = end_index + 1
+        front_matter: dict = {}
+        front_matter_start = body_start
+        while front_matter_start < len(lines) and lines[front_matter_start].strip() == "":
+            front_matter_start += 1
+        if front_matter_start < len(lines) and lines[front_matter_start].strip() == "---":
+            fm_end = _find_end(
+                lines,
+                start=front_matter_start + 1,
+                marker="---",
+                error="unterminated YAML front matter",
+            )
+            front_matter = load_yaml_config(
+                "".join(lines[front_matter_start + 1 : fm_end]), "front matter"
+            )
+            body_start = fm_end + 1
+        return ConfigBlock(
+            config=config, body_start=body_start, style="hidden", front_matter=front_matter
+        )
+    raise MdDemoError("missing md-demo.runtime")
+
+
+def render_config(block: ConfigBlock, newline: str, style: ConfigStyle) -> list[str]:
+    if style == "preserve":
+        return []
+    if style == "front-matter":
+        data = dict(block.front_matter)
+        data["md-demo"] = dict(block.config)
+        return ["---" + newline, dump_yaml(data, newline), "---" + newline]
+    if style == "hidden":
+        front_matter = dict(block.front_matter)
+        front_matter.pop("md-demo", None)
+        lines = ["<!-- md-demo" + newline, dump_yaml(block.config, newline), "-->" + newline]
+        if front_matter:
+            lines.extend(
+                [newline, "---" + newline, dump_yaml(front_matter, newline), "---" + newline]
+            )
+        return lines
+    raise MdDemoError(f"unsupported config style: {style}")
+
+
+def load_yaml_config(text: str, label: str) -> dict:
+    try:
+        data = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        raise MdDemoError(f"invalid YAML {label}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise MdDemoError(f"YAML {label} must be a mapping")
+    return data
+
+
+def dump_yaml(data: dict, newline: str) -> str:
+    text = yaml.safe_dump(data, sort_keys=False, default_flow_style=False)
+    return text.replace("\n", newline)
+
+
+def _find_end(lines: list[str], *, start: int, marker: str, error: str) -> int:
+    for index in range(start, len(lines)):
+        if lines[index].strip() == marker:
+            return index
+    raise MdDemoError(error)