md-babel-py 0.1.0__tar.gz

md_babel_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ivan Nikolic
+
+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.

md_babel_py-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: md-babel-py
+Version: 0.1.0
+Summary: Execute code blocks in markdown files with session support
+Author-email: Ivan Nikolic <lesh@mm.st>
+License-Expression: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: matplotlib
+Requires-Dist: matplotlib; extra == "matplotlib"
+Requires-Dist: numpy; extra == "matplotlib"
+Dynamic: license-file

md_babel_py-0.1.0/README.md

@@ -0,0 +1,406 @@
+# md-babel-py
+
+Execute code blocks in markdown files and insert the results.
+
+**Use cases:**
+- Keep documentation examples up-to-date automatically
+- Validate code snippets in docs actually work
+- Generate diagrams and charts from code in markdown
+- Literate programming with executable documentation
+
+## Languages
+
+### Shell
+
+```sh
+echo "cwd: $(pwd)"
+```
+
+<!--Result:-->
+```
+cwd: /work
+```
+
+### Python
+
+```python session=example
+a = "hello world"
+print(a)
+```
+
+<!--Result:-->
+```
+hello world
+```
+
+Sessions preserve state between code blocks:
+
+```python session=example
+print(a, "again")
+```
+
+<!--Result:-->
+```
+hello world again
+```
+
+### Node.js
+
+```node
+console.log("Hello from Node.js");
+console.log(`Node version: ${process.version}`);
+```
+
+<!--Result:-->
+```
+Hello from Node.js
+Node version: v22.21.1
+```
+
+### Matplotlib
+
+```python output=assets/matplotlib-demo.svg
+import matplotlib.pyplot as plt
+import numpy as np
+plt.style.use('dark_background')
+x = np.linspace(0, 4 * np.pi, 200)
+plt.figure(figsize=(8, 4))
+plt.plot(x, np.sin(x), label='sin(x)', linewidth=2)
+plt.plot(x, np.cos(x), label='cos(x)', linewidth=2)
+plt.xlabel('x')
+plt.ylabel('y')
+plt.legend()
+plt.grid(alpha=0.3)
+plt.savefig('{output}', transparent=True)
+```
+
+<!--Result:-->
+![output](assets/matplotlib-demo.svg)
+
+### Pikchr
+
+SQLite's diagram language:
+
+```pikchr output=assets/pikchr-demo.svg
+color = white
+fill = none
+linewid = 0.4in
+
+# Input file
+In: file "README.md" fit
+arrow
+
+# Processing
+Parse: box "Parse" rad 5px fit
+arrow
+Exec: box "Execute" rad 5px fit
+
+# Fan out to languages
+arrow from Exec.e right 0.3in then up 0.4in then right 0.3in
+Sh: oval "Shell" fit
+arrow from Exec.e right 0.3in then right 0.3in
+Node: oval "Node" fit
+arrow from Exec.e right 0.3in then down 0.4in then right 0.3in
+Py: oval "Python" fit
+
+# Merge back
+arrow from Sh.e right 0.3in then down 0.4in then right 0.3in
+arrow from Node.e right 0.6in
+Out: file "README.md" fit with .w at last arrow.e
+arrow from Py.e right 0.3in then up 0.4in then to Out.w
+```
+
+<!--Result:-->
+![output](assets/pikchr-demo.svg)
+
+### Asymptote
+
+Vector graphics:
+
+```asymptote output=assets/histogram.svg
+import graph;
+import stats;
+
+size(400,200,IgnoreAspect);
+defaultpen(white);
+
+int n=10000;
+real[] a=new real[n];
+for(int i=0; i < n; ++i) a[i]=Gaussrand();
+
+draw(graph(Gaussian,min(a),max(a)),orange);
+
+int N=bins(a);
+
+histogram(a,min(a),max(a),N,normalize=true,low=0,rgb(0.4,0.6,0.8),rgb(0.2,0.4,0.6),bars=true);
+
+xaxis("$x$",BottomTop,LeftTicks,p=white);
+yaxis("$dP/dx$",LeftRight,RightTicks(trailingzero),p=white);
+```
+
+<!--Result:-->
+![output](assets/histogram.svg)
+
+### Graphviz
+
+```dot output=assets/graph.svg
+A -> B -> C
+A -> C
+```
+
+<!--Result:-->
+![output](assets/graph.svg)
+
+### OpenSCAD
+
+```openscad output=assets/cube-sphere.png
+cube([10, 10, 10]);
+sphere(r=7);
+```
+
+<!--Result:-->
+![output](assets/cube-sphere.png)
+
+### Diagon
+
+ASCII art diagrams:
+
+```diagon mode=Math
+1 + 1/2 + sum(i,0,10)
+```
+
+<!--Result:-->
+```
+        10   
+        ___  
+    1   ╲    
+1 + ─ + ╱   i
+    2   ‾‾‾  
+         0
+```
+
+```diagon mode=GraphDAG
+A -> B -> C
+A -> C
+```
+
+<!--Result:-->
+```
+┌───┐
+│A  │
+└┬─┬┘
+ │┌▽┐
+ ││B│
+ │└┬┘
+┌▽─▽┐
+│C  │
+└───┘
+```
+
+## Install
+
+### Nix (recommended)
+
+```sh skip
+# Run directly from GitHub
+nix run github:leshy/md-babel-py -- run README.md --stdout
+
+# Or clone and run locally
+nix run . -- run README.md --stdout
+```
+
+### Docker
+
+```sh skip
+# Pull from Docker Hub
+docker run -v $(pwd):/work lesh/md-babel-py:main run /work/README.md --stdout
+
+# Or build locally via Nix
+nix build .#docker     # builds tarball to ./result
+docker load < result   # loads image from tarball
+docker run -v $(pwd):/work md-babel-py:latest run /work/file.md --stdout
+```
+
+### pipx
+
+```sh skip
+pipx install md-babel-py
+# or: uv pip install md-babel-py
+md-babel-py run README.md --stdout
+```
+
+If not using nix or docker, evaluators require system dependencies:
+
+| Language  | System packages             |
+|-----------|-----------------------------|
+| python    | python3                     |
+| node      | nodejs                      |
+| dot       | graphviz                    |
+| asymptote | asymptote, texlive, dvisvgm |
+| pikchr    | pikchr                      |
+| openscad  | openscad, xvfb, imagemagick |
+| diagon    | diagon                      |
+
+```sh skip
+# Arch Linux
+sudo pacman -S python nodejs graphviz asymptote texlive-basic openscad xorg-server-xvfb imagemagick
+
+# Debian/Ubuntu
+sudo apt-get install python3 nodejs graphviz asymptote texlive xvfb imagemagick openscad
+```
+
+Note: pikchr and diagon may need to be built from source. Use Docker or Nix for full evaluator support.
+
+## Usage
+
+```sh skip
+# Edit file in-place
+md-babel-py run document.md
+
+# Output to separate file
+md-babel-py run document.md --output result.md
+
+# Print to stdout
+md-babel-py run document.md --stdout
+
+# Only run specific languages
+md-babel-py run document.md --lang python,sh
+
+# Dry run - show what would execute
+md-babel-py run document.md --dry-run
+```
+
+## Code Block Syntax
+
+````markdown
+```python session=main
+x = 42
+```
+````
+
+### Flags
+
+| Flag             | Description                                               |
+|------------------|-----------------------------------------------------------|
+| `session=NAME`   | Share state with other blocks using the same session name |
+| `output=PATH`    | Write output to file (for images/diagrams)                |
+| `expected-error` | Expect this block to fail; test fails if it succeeds      |
+| `skip`           | Don't execute this block                                  |
+| `no-result`      | Execute but don't insert result block                     |
+
+### Custom Parameters
+
+Any `key=value` pair becomes a parameter for the evaluator command:
+
+````markdown
+```diagon mode=GraphDAG
+A -> B
+```
+````
+
+With config `"defaultArguments": ["{mode}"]`, the `{mode}` placeholder is replaced with `GraphDAG`.
+
+## GitHub Action
+
+```yaml skip
+- uses: leshy/md-babel-py@main
+  with:
+    files: 'README.md docs/*.md'
+```
+
+| Input            | Description                               | Default  |
+|------------------|-------------------------------------------|----------|
+| `files`          | Markdown files to process (glob patterns) | required |
+| `args`           | Additional arguments                      | `''`     |
+| `fail-on-change` | Fail if files were modified (CI check)    | `false`  |
+
+Example with auto-commit:
+
+```yaml skip
+- uses: leshy/md-babel-py@main
+  with:
+    files: '*.md docs/**/*.md'
+
+- uses: stefanzweifel/git-auto-commit-action@v5
+  with:
+    commit_message: 'Update markdown code block results'
+```
+
+## Configuration
+
+Create `config.json` in your project or `~/.config/md-babel/config.json`:
+
+```json skip
+{
+  "evaluators": {
+    "codeBlock": {
+      "python": {
+        "path": "/usr/bin/env",
+        "defaultArguments": ["python3"],
+        "session": {
+          "command": ["python3", "-i"],
+          "prompts": [">>> ", "... "]
+        }
+      }
+    }
+  }
+}
+```
+
+### File-based Evaluators
+
+For tools that use input/output files:
+
+```json skip
+{
+  "openscad": {
+    "path": "xvfb-run",
+    "defaultArguments": ["-a", "openscad", "-o", "{output_file}", "{input_file}"],
+    "inputExtension": ".scad"
+  }
+}
+```
+
+## Development
+
+### direnv Setup
+
+Two `.envrc` files are provided:
+
+| File          | Description                                     |
+|---------------|-------------------------------------------------|
+| `.envrc.nix`  | Nix flake devShell (all evaluators + dev tools) |
+| `.envrc.venv` | Python venv only                                |
+
+```sh skip
+ln -s .envrc.nix .envrc
+direnv allow
+```
+
+### Nix Development Shell
+
+```sh skip
+nix develop
+# Provides: md-babel-py, pytest, mypy, ruff, and all evaluators
+```
+
+### Manual Setup
+
+```sh skip
+pip install -e ".[dev]"
+pytest tests/ -v
+mypy md_babel_py/
+ruff check md_babel_py/
+```
+
+### Nix Packages
+
+| Package   | Description                                |
+|-----------|--------------------------------------------|
+| `default` | Full package with all evaluators in PATH   |
+| `minimal` | Just Python package, no bundled evaluators |
+| `docker`  | Docker image tarball                       |
+
+## License
+
+MIT

md_babel_py-0.1.0/md_babel_py/__init__.py

@@ -0,0 +1,3 @@
+"""md-babel-py: Execute code blocks in markdown files with session support."""
+
+__version__ = "0.1.0"

md_babel_py-0.1.0/md_babel_py/cli.py

@@ -0,0 +1,262 @@
+"""Command-line interface for md-babel-py."""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from .config import load_config, get_evaluator, Config
+from .exceptions import ConfigError, MdBabelError
+from .executor import Executor
+from .parser import find_code_blocks, CodeBlock
+from .types import ExecutionResult
+from .writer import apply_results, BlockResult
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> int:
+    """Main entry point for md-babel-py CLI."""
+    parser = argparse.ArgumentParser(
+        prog="md-babel-py",
+        description="Execute code blocks in markdown files",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Enable verbose/debug output",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # run command
+    run_parser = subparsers.add_parser("run", help="Execute code blocks in a markdown file")
+    run_parser.add_argument("file", type=Path, help="Markdown file to process")
+    run_parser.add_argument("--output", "-o", type=Path, help="Output file (default: edit in-place)")
+    run_parser.add_argument("--stdout", action="store_true", help="Print result to stdout instead of writing file")
+    run_parser.add_argument("--config", "-c", type=Path, help="Config file path")
+    run_parser.add_argument("--lang", help="Only execute these languages (comma-separated)")
+    run_parser.add_argument("--dry-run", action="store_true", help="Show what would be executed")
+
+    args = parser.parse_args()
+
+    # Setup logging
+    setup_logging(verbose=args.verbose)
+
+    try:
+        if args.command == "run":
+            return cmd_run(args)
+        return 0
+    except ConfigError as e:
+        logger.error(f"Configuration error: {e}")
+        return 1
+    except MdBabelError as e:
+        logger.error(f"Error: {e}")
+        return 1
+
+
+def setup_logging(verbose: bool = False) -> None:
+    """Configure logging for the application.
+
+    Args:
+        verbose: If True, enable DEBUG level logging.
+    """
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(message)s",
+        stream=sys.stderr,
+    )
+    # Quieter format for non-verbose
+    if not verbose:
+        logging.getLogger("md_babel_py").setLevel(logging.INFO)
+
+
+def format_block_flags(block: CodeBlock) -> str:
+    """Format block flags for display.
+
+    Args:
+        block: The code block to format flags for.
+
+    Returns:
+        A formatted string like " [session=main, expected-error]" or empty string.
+    """
+    flags = []
+    if block.session:
+        flags.append(f"session={block.session}")
+    if block.expected_error:
+        flags.append("expected-error")
+    if block.no_result:
+        flags.append("no-result")
+    return f" [{', '.join(flags)}]" if flags else ""
+
+
+def filter_blocks(
+    blocks: list[CodeBlock],
+    config: Config,
+    lang_filter: set[str] | None,
+) -> tuple[list[CodeBlock], set[str]]:
+    """Filter blocks by language and configuration.
+
+    Args:
+        blocks: All parsed code blocks.
+        config: The loaded configuration.
+        lang_filter: Optional set of languages to include.
+
+    Returns:
+        Tuple of (configured_blocks, unconfigured_languages).
+    """
+    # Filter by language if specified
+    if lang_filter:
+        blocks = [b for b in blocks if b.language in lang_filter]
+
+    # Separate configured from unconfigured
+    unconfigured: set[str] = set()
+    configured: list[CodeBlock] = []
+
+    for block in blocks:
+        if get_evaluator(config, block.language):
+            configured.append(block)
+        else:
+            unconfigured.add(block.language)
+
+    return configured, unconfigured
+
+
+def execute_blocks(
+    executor: Executor,
+    blocks: list[CodeBlock],
+) -> tuple[list[BlockResult], list[str], bool]:
+    """Execute code blocks and collect results.
+
+    Args:
+        executor: The executor instance.
+        blocks: The blocks to execute.
+
+    Returns:
+        Tuple of (results, test_failures, stopped_early).
+    """
+    results: list[BlockResult] = []
+    test_failures: list[str] = []
+    stopped_early = False
+
+    for i, block in enumerate(blocks, 1):
+        flags_str = format_block_flags(block)
+        logger.info(f"[{i}/{len(blocks)}] Executing {block.language}{flags_str} block at line {block.start_line}...")
+
+        result = executor.execute(block)
+
+        # Only add to results if we want to write output (not no-result)
+        if not block.no_result:
+            results.append(BlockResult(block=block, result=result))
+
+        # Check expected-error logic
+        if block.expected_error:
+            if result.success:
+                msg = f"Line {block.start_line}: expected error but block succeeded"
+                test_failures.append(msg)
+                logger.error(f"FAIL: {msg}")
+            # Don't stop on expected errors
+        else:
+            if not result.success:
+                msg = f"Line {block.start_line}: {result.error_message or 'Execution failed'}"
+                test_failures.append(msg)
+                logger.error(f"Error: {result.error_message or 'Execution failed'}")
+                if result.stderr:
+                    logger.error(result.stderr)
+                # Stop on first unexpected error
+                stopped_early = True
+                break
+
+    return results, test_failures, stopped_early
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    """Execute the run command.
+
+    Args:
+        args: Parsed command-line arguments.
+
+    Returns:
+        Exit code (0 for success, non-zero for failure).
+    """
+    # Load config
+    config = load_config(args.config)
+
+    # Read input file
+    if not args.file.exists():
+        logger.error(f"Error: File not found: {args.file}")
+        return 1
+
+    content = args.file.read_text()
+
+    # Parse code blocks
+    blocks = find_code_blocks(content)
+
+    if not blocks:
+        logger.info("No code blocks found.")
+        return 0
+
+    # Parse language filter
+    lang_filter = set(args.lang.split(",")) if args.lang else None
+
+    # Filter blocks
+    configured_blocks, unconfigured = filter_blocks(blocks, config, lang_filter)
+
+    if unconfigured:
+        logger.warning(f"Warning: No evaluators configured for: {', '.join(sorted(unconfigured))}")
+
+    if not configured_blocks:
+        logger.info("No executable code blocks found.")
+        return 0
+
+    # Filter out skipped blocks
+    executable_blocks = [b for b in configured_blocks if not b.skip]
+    skipped_count = len(configured_blocks) - len(executable_blocks)
+
+    # Dry run - just show what would execute
+    if args.dry_run:
+        logger.info(f"Would execute {len(executable_blocks)} code block(s):\n")
+        for i, block in enumerate(executable_blocks, 1):
+            flags_str = format_block_flags(block)
+            logger.info(f"{i}. {block.language}{flags_str} (lines {block.start_line}-{block.end_line})")
+            logger.info(f"   {block.code[:50]}{'...' if len(block.code) > 50 else ''}")
+            logger.info("")
+        if skipped_count:
+            logger.info(f"({skipped_count} block(s) marked as skip)")
+        return 0
+
+    # Execute blocks
+    executor = Executor(config)
+    try:
+        results, test_failures, _ = execute_blocks(executor, executable_blocks)
+    finally:
+        executor.cleanup()
+
+    # Apply results to content
+    new_content = apply_results(content, results)
+
+    # Write output
+    if args.stdout:
+        print(new_content)
+    else:
+        output_path = args.output or args.file
+        output_path.write_text(new_content)
+
+    success_count = sum(1 for r in results if r.result.success)
+    logger.info(f"\nDone: {success_count}/{len(results)} blocks executed successfully.")
+
+    if not args.stdout and args.output and args.output != args.file:
+        logger.info(f"Output written to: {args.output}")
+
+    if test_failures:
+        logger.error(f"\n{len(test_failures)} test failure(s):")
+        for f in test_failures:
+            logger.error(f"  - {f}")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())