mtangle 0.1.0__py3-none-any.whl

mtangle/__init__.py

@@ -0,0 +1,3 @@
+from mtangle.core import tangle, parse_markdown, CodeBlock, TangleError, TangleWarning
+
+__all__ = ["tangle", "parse_markdown", "CodeBlock", "TangleError", "TangleWarning"]

mtangle/cli.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from mtangle.core import TangleError, tangle
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="mtangle",
+        description="Tangle codeblocks out of markdown files into source files.",
+    )
+    parser.add_argument(
+        "sources",
+        nargs="*",
+        help="Markdown files or directories to scan. Defaults to '.'",
+    )
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        default=".",
+        help="Directory to write tangled sources into (default: cwd)",
+    )
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        help="Parse and resolve everything but don't write any files",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Print progress details to stderr",
+    )
+    parser.add_argument(
+        "--disable-path-safety",
+        action="store_true",
+        help=(
+            "Allow file= targets to be absolute or resolve outside the output "
+            "directory. Off by default; such targets are warned and skipped."
+        ),
+    )
+    parser.add_argument(
+        "-i",
+        "--ignore",
+        action="append",
+        default=[],
+        metavar="PATTERN",
+        help=(
+            "Gitignore-style pattern to skip during directory walks. "
+            "May be given multiple times."
+        ),
+    )
+    parser.add_argument(
+        "--disable-ignore-dotfiles",
+        action="store_true",
+        help="Include dotfiles/dotdirs in directory walks (default: skipped).",
+    )
+    parser.add_argument(
+        "--respect-gitignore",
+        action="store_true",
+        help="Also apply .gitignore patterns at each walk root (default: off).",
+    )
+    args = parser.parse_args(argv)
+
+    sources = args.sources or ["."]
+    inputs = [Path(s) for s in sources]
+    output_dir = Path(args.output_dir)
+
+    def info(msg: str) -> None:
+        if args.verbose:
+            print(msg, file=sys.stderr)
+
+    try:
+        results = tangle(
+            inputs,
+            output_dir,
+            on_info=info,
+            dry_run=args.dry_run,
+            path_safety=not args.disable_path_safety,
+            ignore_dotfiles=not args.disable_ignore_dotfiles,
+            ignore_patterns=args.ignore,
+            respect_gitignore=args.respect_gitignore,
+        )
+    except TangleError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    verb = "would write" if args.dry_run else "wrote"
+    for path in sorted(results):
+        print(f"{verb} {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mtangle/core.py

@@ -0,0 +1,417 @@
+from __future__ import annotations
+
+import os
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Iterable
+
+import pathspec
+
+
+class TangleError(Exception):
+    pass
+
+
+class TangleWarning(UserWarning):
+    pass
+
+
+FENCE_RE = re.compile(r"^(?P<indent>[ \t]*)(?P<fence>`{3,})(?P<info>.*)$")
+ATTR_RE = re.compile(r'([A-Za-z_][A-Za-z0-9_.-]*)=("([^"]*)"|(\S+))')
+IDENT_RE = re.compile(r"([A-Za-z_][A-Za-z0-9_-]*)>>")
+
+
+@dataclass
+class CodeBlock:
+    lang: str | None
+    file: str | None
+    id: str | None
+    lines: list[str]
+    source: str
+    line_no: int
+
+
+def _parse_info(info: str) -> tuple[str | None, dict[str, str]]:
+    info = info.strip()
+    if not info:
+        return None, {}
+    parts = info.split(None, 1)
+    first = parts[0]
+    attrs: dict[str, str] = {}
+    if "=" in first:
+        lang = None
+        rest = info
+    else:
+        lang = first
+        rest = parts[1] if len(parts) > 1 else ""
+    for m in ATTR_RE.finditer(rest):
+        key = m.group(1)
+        val = m.group(3) if m.group(3) is not None else m.group(4)
+        attrs[key] = val
+    return lang, attrs
+
+
+def _left_align(lines: list[str]) -> list[str]:
+    non_blank = [ln for ln in lines if ln.strip()]
+    if not non_blank:
+        return ["" for _ in lines]
+    min_indent = min(len(ln) - len(ln.lstrip(" \t")) for ln in non_blank)
+    result: list[str] = []
+    for ln in lines:
+        if not ln.strip():
+            result.append("")
+        else:
+            result.append(ln[min_indent:])
+    return result
+
+
+def parse_markdown(text: str, source: str = "<string>") -> list[CodeBlock]:
+    lines = text.splitlines()
+    blocks: list[CodeBlock] = []
+    i = 0
+    while i < len(lines):
+        m = FENCE_RE.match(lines[i])
+        if not m:
+            i += 1
+            continue
+        fence = m.group("fence")
+        info = m.group("info")
+        lang, attrs = _parse_info(info)
+        start = i
+        i += 1
+        body: list[str] = []
+        closed = False
+        close_re = re.compile(rf"^[ \t]*`{{{len(fence)},}}\s*$")
+        while i < len(lines):
+            if close_re.match(lines[i]):
+                closed = True
+                i += 1
+                break
+            body.append(lines[i])
+            i += 1
+        if not closed:
+            raise TangleError(f"{source}:{start+1}: unclosed fenced code block")
+        file_attr = attrs.get("file")
+        id_attr = attrs.get("id")
+        if file_attr or id_attr:
+            aligned = _left_align(body)
+            blocks.append(
+                CodeBlock(
+                    lang=lang,
+                    file=file_attr,
+                    id=id_attr,
+                    lines=aligned,
+                    source=source,
+                    line_no=start + 1,
+                )
+            )
+    return blocks
+
+
+def _scan_line(line: str) -> tuple[str, tuple[int, int, str] | None, str]:
+    """Scan a line for at most one active marker.
+
+    Escape rules:
+    - `\\\\` → literal backslash
+    - `\\<<` → literal `<<` (marker suppressed)
+    - `<<IDENT>>` (no whitespace inside) → marker
+    - `<< IDENT >>` or any non-identifier content between `<<` and `>>` → literal
+
+    Returns (rendered_before, marker_or_None, rendered_after).
+    `marker_or_None` is `(start_col_in_rendered, end_col, ident)` where
+    start/end refer to positions in the fully-rendered line (before + placeholder + after).
+    If there is more than one marker on the line, raises AssertionError-style —
+    the caller detects multi-marker via a second scan.
+    """
+    out: list[str] = []
+    marker: tuple[int, int, str] | None = None
+    i = 0
+    n = len(line)
+    while i < n:
+        c = line[i]
+        if c == "\\":
+            if i + 1 < n and line[i + 1] == "\\":
+                out.append("\\")
+                i += 2
+                continue
+            if line.startswith("<<", i + 1):
+                out.append("<<")
+                i += 3
+                continue
+            out.append("\\")
+            i += 1
+            continue
+        if line.startswith("<<", i):
+            m = IDENT_RE.match(line, i + 2)
+            if m:
+                if marker is not None:
+                    marker = (-1, -1, "__MULTI__")
+                    out.append(line[i : m.end()])
+                else:
+                    ident = m.group(1)
+                    start = len("".join(out))
+                    marker = (start, start, ident)
+                i = m.end()
+                continue
+        out.append(c)
+        i += 1
+    rendered = "".join(out)
+    if marker is None:
+        return rendered, None, ""
+    start, _, ident = marker
+    return rendered[:start], marker, rendered[start:]
+
+
+def _count_markers(line: str) -> int:
+    """Count active markers on a line (for multi-marker detection)."""
+    count = 0
+    i = 0
+    n = len(line)
+    while i < n:
+        c = line[i]
+        if c == "\\":
+            if i + 1 < n and line[i + 1] == "\\":
+                i += 2
+                continue
+            if line.startswith("<<", i + 1):
+                i += 3
+                continue
+            i += 1
+            continue
+        if line.startswith("<<", i):
+            m = IDENT_RE.match(line, i + 2)
+            if m:
+                count += 1
+                i = m.end()
+                continue
+        i += 1
+    return count
+
+
+def _expand(
+    block: CodeBlock,
+    id_map: dict[str, CodeBlock],
+    on_warning: Callable[[str], None],
+    stack: tuple[str, ...] = (),
+) -> list[str]:
+    out: list[str] = []
+    for line_idx, line in enumerate(block.lines):
+        n_markers = _count_markers(line)
+        if n_markers == 0:
+            before, _, _ = _scan_line(line)
+            out.append(before)
+            continue
+        if n_markers > 1:
+            raise TangleError(
+                f"{block.source}:{block.line_no}: line {line_idx + 1} of block "
+                f"has multiple substitution markers: {line!r}"
+            )
+        before, marker, after = _scan_line(line)
+        assert marker is not None
+        _, _, marker_id = marker
+        if before.strip() != "" or after.strip() != "":
+            on_warning(
+                f"{block.source}:{block.line_no}: substitution marker "
+                f"<<{marker_id}>> has non-whitespace neighbors "
+                f"(line {line_idx + 1}): {line!r}"
+            )
+        if before.strip() == "":
+            indent = before
+        else:
+            lead = re.match(r"[ \t]*", before)
+            indent = lead.group(0) if lead else ""
+        if marker_id not in id_map:
+            raise TangleError(
+                f"{block.source}:{block.line_no}: unknown id "
+                f"'<<{marker_id}>>' referenced"
+            )
+        if marker_id in stack:
+            cycle = " -> ".join(stack + (marker_id,))
+            raise TangleError(f"cyclic substitution: {cycle}")
+        sub_lines = _expand(id_map[marker_id], id_map, on_warning, stack + (marker_id,))
+        for sl in sub_lines:
+            out.append(indent + sl if sl else "")
+    return out
+
+
+DOTFILE_PATTERNS = [".*", ".*/"]
+MTANGLEIGNORE = ".mtangleignore"
+GITIGNORE = ".gitignore"
+
+
+def _read_pattern_file(path: Path) -> list[str]:
+    if not path.is_file():
+        return []
+    patterns: list[str] = []
+    for raw in path.read_text().splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        patterns.append(line)
+    return patterns
+
+
+def _build_spec(patterns: Iterable[str]) -> pathspec.PathSpec:
+    return pathspec.PathSpec.from_lines("gitignore", list(patterns))
+
+
+def _walk_dir(
+    root: Path,
+    ignore_dotfiles: bool,
+    cli_patterns: list[str],
+    respect_gitignore: bool,
+) -> list[Path]:
+    patterns: list[str] = []
+    if ignore_dotfiles:
+        patterns.extend(DOTFILE_PATTERNS)
+    patterns.extend(cli_patterns)
+    patterns.extend(_read_pattern_file(root / MTANGLEIGNORE))
+    if respect_gitignore:
+        patterns.extend(_read_pattern_file(root / GITIGNORE))
+    spec = _build_spec(patterns)
+
+    result: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        rel_dir = Path(dirpath).relative_to(root)
+        kept_dirs: list[str] = []
+        for d in dirnames:
+            rel = (rel_dir / d).as_posix() + "/"
+            if spec.match_file(rel):
+                continue
+            kept_dirs.append(d)
+        dirnames[:] = kept_dirs
+        for f in filenames:
+            if not f.endswith(".md"):
+                continue
+            rel = (rel_dir / f).as_posix()
+            if spec.match_file(rel):
+                continue
+            result.append(Path(dirpath) / f)
+    return result
+
+
+def _collect_md_files(
+    inputs: Iterable[Path],
+    ignore_dotfiles: bool = True,
+    cli_patterns: list[str] | None = None,
+    respect_gitignore: bool = False,
+) -> list[Path]:
+    cli_patterns = cli_patterns or []
+    result: list[Path] = []
+    seen: set[Path] = set()
+    for p in inputs:
+        if p.is_dir():
+            for md in _walk_dir(p, ignore_dotfiles, cli_patterns, respect_gitignore):
+                rp = md.resolve()
+                if rp not in seen:
+                    seen.add(rp)
+                    result.append(md)
+        elif p.suffix == ".md":
+            rp = p.resolve()
+            if rp not in seen:
+                seen.add(rp)
+                result.append(p)
+    return result
+
+
+def _default_warn(msg: str) -> None:
+    print(f"warning: {msg}", file=sys.stderr)
+
+
+def _noop(_msg: str) -> None:
+    pass
+
+
+def _is_safe_target(target: str, output_dir: Path) -> tuple[bool, Path, str]:
+    """Return (ok, resolved_path, reason_if_not_ok)."""
+    if Path(target).is_absolute():
+        return False, output_dir / target, "absolute path"
+    combined = (output_dir / target).resolve()
+    base = output_dir.resolve()
+    try:
+        combined.relative_to(base)
+    except ValueError:
+        return False, combined, f"escapes output directory {base}"
+    return True, combined, ""
+
+
+def tangle(
+    inputs: Iterable[Path],
+    output_dir: Path,
+    on_warning: Callable[[str], None] | None = None,
+    on_info: Callable[[str], None] | None = None,
+    dry_run: bool = False,
+    path_safety: bool = True,
+    ignore_dotfiles: bool = True,
+    ignore_patterns: list[str] | None = None,
+    respect_gitignore: bool = False,
+) -> dict[Path, str]:
+    warn = on_warning if on_warning is not None else _default_warn
+    info = on_info if on_info is not None else _noop
+
+    md_files = sorted(
+        _collect_md_files(
+            inputs,
+            ignore_dotfiles=ignore_dotfiles,
+            cli_patterns=ignore_patterns or [],
+            respect_gitignore=respect_gitignore,
+        ),
+        key=lambda p: str(p),
+    )
+    for md in md_files:
+        info(f"reading {md}")
+
+    all_blocks: list[CodeBlock] = []
+    for md in md_files:
+        text = md.read_text()
+        all_blocks.extend(parse_markdown(text, source=str(md)))
+
+    id_map: dict[str, CodeBlock] = {}
+    for b in all_blocks:
+        if b.id:
+            if b.id in id_map:
+                prev = id_map[b.id]
+                raise TangleError(
+                    f"{b.source}:{b.line_no}: duplicate id '{b.id}' "
+                    f"(also at {prev.source}:{prev.line_no})"
+                )
+            id_map[b.id] = b
+            info(f"registered id '{b.id}' from {b.source}:{b.line_no}")
+
+    file_groups: dict[str, list[CodeBlock]] = {}
+    for b in all_blocks:
+        if b.file:
+            file_groups.setdefault(b.file, []).append(b)
+
+    results: dict[Path, str] = {}
+    for target, blocks in file_groups.items():
+        if path_safety:
+            ok, resolved, reason = _is_safe_target(target, output_dir)
+            if not ok:
+                locs = ", ".join(f"{b.source}:{b.line_no}" for b in blocks)
+                warn(
+                    f"refusing to write '{target}' ({reason}); "
+                    f"skipping. from: {locs}"
+                )
+                continue
+            out_path = resolved
+        else:
+            out_path = output_dir / target
+        if len(blocks) > 1:
+            locs = ", ".join(f"{b.source}:{b.line_no}" for b in blocks)
+            warn(f"multiple codeblocks target '{target}' — concatenating: {locs}")
+        chunks: list[str] = []
+        for b in blocks:
+            expanded = _expand(b, id_map, warn)
+            chunks.append("\n".join(expanded) + "\n")
+        content = "".join(chunks)
+        results[out_path] = content
+        if dry_run:
+            info(f"would write {out_path} ({len(content)} bytes)")
+        else:
+            out_path.parent.mkdir(parents=True, exist_ok=True)
+            out_path.write_text(content)
+            info(f"wrote {out_path} ({len(content)} bytes)")
+    return results

mtangle-0.1.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: mtangle
+Version: 0.1.0
+Summary: A simple literate programming utility for markdown
+Project-URL: Homepage, https://github.com/usergenic/mtangle
+Project-URL: Repository, https://github.com/usergenic/mtangle
+Author: Brendan Baldwin
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pathspec>=0.12
+Description-Content-Type: text/markdown
+
+# mtangle
+
+A simple literate-programming utility that extracts codeblocks from markdown
+files and writes them to source files.
+
+## What it does
+
+Given a markdown file:
+
+~~~markdown
+```python file=src/something.py
+def cool():
+    return 0
+```
+~~~
+
+Running `mtangle` writes the block's contents to `src/something.py`.
+
+Codeblocks are recognized by attributes on the info string:
+
+- `file=PATH` — write this block's contents to `PATH` (relative to the output
+  directory).
+- `id=NAME` — register this block under a name so it can be referenced from
+  another block.
+
+Blocks without either attribute are ignored.
+
+## Composition via `<<name>>`
+
+Blocks with `file=` can reference `id=` blocks using `<<name>>` markers on their
+own line:
+
+~~~markdown
+```python id=cool_func
+def cool():
+    return 0
+```
+
+```python id=neat_func
+def neat():
+    return cool()
+```
+
+```python file=src/my_funcs.py
+<<cool_func>>
+
+
+<<neat_func>>
+```
+~~~
+
+Produces `src/my_funcs.py`:
+
+```python
+def cool():
+    return 0
+
+
+def neat():
+    return cool()
+```
+
+### Indentation
+
+mtangle is language-agnostic. When a codeblock is parsed, its non-blank lines
+are left-aligned against the block's least-indented line. When a `<<marker>>`
+is substituted, the substituted content is re-indented to match the marker's
+column. This handles the common case of embedding a snippet inside an already-
+indented body.
+
+### Escaping
+
+- `<< name >>` (spaces inside) is not a marker — emitted literally.
+- `\<<name>>` emits `<<name>>` literally (no substitution).
+- `\\` emits a literal backslash.
+- To emit a literal `\<<name>>`: use `\\\<<name>>`.
+
+## Merging into the same file
+
+Multiple codeblocks targeting the same `file=` are concatenated in the order
+they are encountered (across all input markdown files, sorted by path).
+mtangle warns when this happens.
+
+## CLI
+
+```
+mtangle [SOURCES...] [-o OUTPUT_DIR] [OPTIONS]
+```
+
+With no arguments, `mtangle` is equivalent to `mtangle . -o .` — it recursively
+scans the current directory for `.md` files and writes tangled output to the
+current directory.
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-o`, `--output-dir DIR` | Where to write files (default: cwd) |
+| `-n`, `--dry-run` | Parse and resolve everything but write nothing |
+| `-v`, `--verbose` | Print progress to stderr |
+| `-i`, `--ignore PATTERN` | Gitignore-style skip pattern (repeatable) |
+| `--disable-ignore-dotfiles` | Include dotfiles/dotdirs (default: skipped) |
+| `--respect-gitignore` | Also apply `.gitignore` at each input-dir root |
+| `--disable-path-safety` | Permit `file=` targets outside the output dir |
+
+### Ignore behavior
+
+- Dotfiles and dotdirs (`.git`, `.venv`, etc.) are skipped by default.
+- A `.mtangleignore` file at the root of each input directory is respected;
+  every non-empty, non-`#` line is treated like an `-i` pattern
+  (gitignore syntax).
+- `.gitignore` is **not** consulted unless `--respect-gitignore` is set.
+- Explicitly-named files (e.g. `mtangle README.md`) bypass all ignore rules.
+
+### Path safety
+
+By default, `file=` targets that are absolute or that resolve outside the
+output directory are warned and skipped. Use `--disable-path-safety` to opt
+out.
+
+## Install
+
+```
+uv pip install git+https://github.com/usergenic/mtangle.git
+```
+
+Or add to your project:
+
+```
+uv add git+https://github.com/usergenic/mtangle.git
+```
+
+## Development
+
+```
+uv sync
+uv run pytest
+```

mtangle-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mtangle/__init__.py,sha256=yQ5LbKTcTcYC88fnG8ceUUcKfwPx7aqtObF15HQH8ok,172
+mtangle/cli.py,sha256=TUUcmYxuljMigoVNL_JrDPwRiUPXzeRw3Zuec3eL1xs,2741
+mtangle/core.py,sha256=wHMstu7s-lQPUoMoYd7EUV00Fd0wDAfZuPFZpSFXAQU,12798
+mtangle-0.1.0.dist-info/METADATA,sha256=Txm-8rIG1wpZBdK87VQM3qQB8H0dWEZ2zeH2QfBbnok,3791
+mtangle-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+mtangle-0.1.0.dist-info/entry_points.txt,sha256=4gSRi9I7qYMMEHh0yIfyxDqXqhBLUWZEZLn90UDX_ZA,45
+mtangle-0.1.0.dist-info/licenses/LICENSE,sha256=q7JWdDPDSH_-CFwtCtYp7AtUmMYDdMMrd-jO_vdcxWE,1072
+mtangle-0.1.0.dist-info/RECORD,,

mtangle-0.1.0.dist-info/WHEEL

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

mtangle-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mtangle = mtangle.cli:main

mtangle-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brendan Baldwin
+
+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.