mtangle 0.1.0__tar.gz

mtangle-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.claude/*
+__pycache__
+.venv/

mtangle-0.1.0/.mtangleignore

@@ -0,0 +1 @@
+tests/

mtangle-0.1.0/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.

mtangle-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,138 @@
+# 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/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-0.1.0/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())