termrender 0.1.0__tar.gz

termrender-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

termrender-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.eggs/
+*.egg
+.sisyphus/

termrender-0.1.0/LICENSE

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

termrender-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: termrender
+Version: 0.1.0
+Summary: Rich terminal rendering of directive-flavored markdown
+Project-URL: Homepage, https://github.com/CaptainCrouton89/termrender
+Project-URL: Repository, https://github.com/CaptainCrouton89/termrender
+Project-URL: Issues, https://github.com/CaptainCrouton89/termrender/issues
+Author: Silas Rhyneer
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ansi,cli,markdown,rendering,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Requires-Dist: mermaid-ascii>=1.0
+Requires-Dist: mistune>=3.0
+Requires-Dist: pygments>=2.0

termrender-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "termrender"
+version = "0.1.0"
+description = "Rich terminal rendering of directive-flavored markdown"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Silas Rhyneer" },
+]
+keywords = ["terminal", "markdown", "ansi", "cli", "rendering"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Topic :: Terminals",
+]
+dependencies = [
+    "mistune>=3.0",
+    "mermaid-ascii>=1.0",
+    "pygments>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/CaptainCrouton89/termrender"
+Repository = "https://github.com/CaptainCrouton89/termrender"
+Issues = "https://github.com/CaptainCrouton89/termrender/issues"
+
+[project.scripts]
+termrender = "termrender.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/termrender"]

termrender-0.1.0/src/termrender/__init__.py

@@ -0,0 +1,43 @@
+"""termrender — render Markdown to ANSI terminal output."""
+
+import os
+import shutil
+from termrender.parser import parse
+from termrender.layout import layout
+from termrender.emit import emit
+
+
+class TerminalError(Exception):
+    """Raised when the terminal does not support required capabilities."""
+
+
+def render(source: str, width: int | None = None, color: bool = True) -> str:
+    """Render directive-flavored markdown to ANSI terminal output.
+
+    Args:
+        source: Markdown string with optional directives
+        width: Terminal width in columns (auto-detected if None)
+        color: Enable ANSI color codes (respects NO_COLOR env var)
+
+    Returns:
+        Rendered string with ANSI escape sequences
+
+    Raises:
+        TerminalError: If terminal is unsupported (TERM=dumb)
+    """
+    # REQ-011: Check terminal capability
+    if os.environ.get("TERM") == "dumb":
+        raise TerminalError("Terminal type 'dumb' does not support Unicode rendering")
+
+    # Respect NO_COLOR convention (https://no-color.org/)
+    if os.environ.get("NO_COLOR") is not None:
+        color = False
+
+    # Auto-detect width
+    if width is None:
+        width = shutil.get_terminal_size().columns
+
+    # Pipeline: parse → layout → emit
+    doc = parse(source)
+    layout(doc, width)
+    return emit(doc, color)

termrender-0.1.0/src/termrender/__main__.py

@@ -0,0 +1,46 @@
+"""CLI entry point for termrender."""
+
+import argparse
+import sys
+
+from termrender import render, TerminalError
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="termrender",
+        description="Render Markdown to ANSI terminal output",
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        type=argparse.FileType("r"),
+        default=sys.stdin,
+        help="Markdown file to render (reads stdin if omitted)",
+    )
+    parser.add_argument(
+        "--width",
+        type=int,
+        default=None,
+        help="Terminal width in columns (auto-detected if omitted)",
+    )
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable ANSI color output",
+    )
+    args = parser.parse_args()
+
+    source = args.file.read()
+
+    try:
+        output = render(source, width=args.width, color=not args.no_color)
+    except TerminalError as e:
+        print(f"termrender: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    sys.stdout.write(output)
+
+
+if __name__ == "__main__":
+    main()

termrender-0.1.0/src/termrender/blocks.py

@@ -0,0 +1,48 @@
+"""Core block data model for termrender."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class BlockType(Enum):
+    """Types of renderable blocks."""
+
+    DOCUMENT = "document"
+    PARAGRAPH = "paragraph"
+    HEADING = "heading"
+    PANEL = "panel"
+    COLUMNS = "columns"
+    COL = "col"
+    TREE = "tree"
+    CALLOUT = "callout"
+    QUOTE = "quote"
+    CODE = "code"
+    DIVIDER = "divider"
+    MERMAID = "mermaid"
+    LIST = "list"
+    LIST_ITEM = "list_item"
+
+
+@dataclass
+class InlineSpan:
+    """A span of inline text with optional formatting."""
+
+    text: str
+    bold: bool = False
+    italic: bool = False
+    code: bool = False
+
+
+@dataclass
+class Block:
+    """A renderable block element with optional children and inline text."""
+
+    type: BlockType
+    children: list[Block] = field(default_factory=list)
+    text: list[InlineSpan] = field(default_factory=list)
+    attrs: dict[str, Any] = field(default_factory=dict)
+    width: int | None = None
+    height: int | None = None

termrender-0.1.0/src/termrender/emit.py

@@ -0,0 +1,52 @@
+"""AST walker that dispatches laid-out blocks to renderers."""
+
+from __future__ import annotations
+
+from termrender.blocks import Block, BlockType
+from termrender.renderers import panel, columns, tree, code, text, divider, quote, mermaid
+
+
+def emit_block(block: Block, color: bool) -> list[str]:
+    """Render a single block and its children, returning output lines."""
+    match block.type:
+        case BlockType.DOCUMENT | BlockType.COL:
+            lines: list[str] = []
+            for child in block.children:
+                lines.extend(emit_block(child, color))
+            return lines
+
+        case BlockType.PANEL:
+            return panel.render(block, color, render_child=emit_block)
+
+        case BlockType.CALLOUT:
+            return panel.render_callout(block, color, render_child=emit_block)
+
+        case BlockType.COLUMNS:
+            return columns.render(block, color, render_child=emit_block)
+
+        case BlockType.QUOTE:
+            return quote.render(block, color, render_child=emit_block)
+
+        case BlockType.CODE:
+            return code.render(block, color, render_child=emit_block)
+
+        case BlockType.PARAGRAPH | BlockType.HEADING | BlockType.LIST | BlockType.LIST_ITEM:
+            return text.render(block, color)
+
+        case BlockType.TREE:
+            return tree.render(block, color)
+
+        case BlockType.MERMAID:
+            return mermaid.render(block, color)
+
+        case BlockType.DIVIDER:
+            return divider.render(block, color)
+
+        case _:
+            return []
+
+
+def emit(doc: Block, color: bool) -> str:
+    """Walk the block tree and return the fully rendered string."""
+    lines = emit_block(doc, color)
+    return "\n".join(lines)

termrender-0.1.0/src/termrender/layout.py

@@ -0,0 +1,134 @@
+"""Two-pass layout engine: resolve widths top-down, heights bottom-up."""
+
+from __future__ import annotations
+
+import subprocess
+
+from termrender.blocks import Block, BlockType
+from termrender.style import wrap_text
+
+
+def _plain_text(spans: list) -> str:
+    return "".join(s.text for s in spans)
+
+
+def resolve_width(block: Block, available: int) -> None:
+    block.width = available
+
+    bt = block.type
+    if bt in (BlockType.PANEL, BlockType.CALLOUT, BlockType.CODE, BlockType.QUOTE):
+        inner = max(available - 4, 1)
+        for child in block.children:
+            resolve_width(child, inner)
+
+    elif bt == BlockType.COLUMNS:
+        n = len(block.children)
+        if n == 0:
+            return
+        gaps = n - 1
+        inner = available
+
+        # Separate children into explicit-width and auto-width
+        explicit: dict[int, int] = {}
+        for i, col in enumerate(block.children):
+            w = col.attrs.get("width")
+            if w is not None:
+                w_str = str(w)
+                try:
+                    if w_str.endswith("%"):
+                        explicit[i] = max(int(inner * float(w_str[:-1]) / 100), 1)
+                    else:
+                        explicit[i] = max(int(w_str), 1)
+                except ValueError:
+                    pass
+
+        used = sum(explicit.values()) + gaps
+        remaining = max(inner - used, 0)
+        auto_count = n - len(explicit)
+
+        for i, col in enumerate(block.children):
+            if i in explicit:
+                col_w = explicit[i]
+            elif auto_count > 0:
+                col_w = max(remaining // auto_count, 1)
+            else:
+                col_w = 1
+            resolve_width(col, col_w)
+
+    else:
+        for child in block.children:
+            resolve_width(child, available)
+
+
+def resolve_height(block: Block) -> None:
+    # Recurse children first (bottom-up)
+    for child in block.children:
+        resolve_height(child)
+
+    bt = block.type
+    width = block.width or 1
+
+    if bt == BlockType.PARAGRAPH:
+        text = _plain_text(block.text)
+        lines = wrap_text(text, width)
+        block.height = len(lines)
+
+    elif bt == BlockType.HEADING:
+        block.height = 1
+
+    elif bt == BlockType.DIVIDER:
+        block.height = 1
+
+    elif bt in (BlockType.PANEL, BlockType.CALLOUT):
+        block.height = sum(c.height or 0 for c in block.children) + 2
+
+    elif bt == BlockType.CODE:
+        source = block.attrs.get("source") or _plain_text(block.text)
+        code_lines = source.split("\n") if source else [""]
+        block.height = len(code_lines) + 2
+
+    elif bt == BlockType.COLUMNS:
+        block.height = max((c.height or 0 for c in block.children), default=0)
+
+    elif bt in (BlockType.COL, BlockType.DOCUMENT, BlockType.LIST):
+        block.height = sum(c.height or 0 for c in block.children)
+
+    elif bt == BlockType.LIST_ITEM:
+        text_height = 0
+        if block.text:
+            text_lines = wrap_text(_plain_text(block.text), max(width - 2, 1))
+            text_height = len(text_lines)
+        block.height = text_height + sum(c.height or 0 for c in block.children)
+
+    elif bt == BlockType.TREE:
+        source = block.attrs.get("source", "")
+        block.height = len(source.split("\n")) if source else 1
+
+    elif bt == BlockType.MERMAID:
+        source = block.attrs.get("source", "") or _plain_text(block.text)
+        rendered = source  # fallback
+        try:
+            result = subprocess.run(
+                ["mermaid-ascii", "-f", "-"],
+                input=source,
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=30,
+            )
+            rendered = result.stdout
+        except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+            pass
+        block.attrs["_rendered"] = rendered
+        block.height = len(rendered.split("\n")) if rendered else 1
+
+    elif bt == BlockType.QUOTE:
+        block.height = sum(c.height or 0 for c in block.children) + (1 if block.attrs.get("by") else 0)
+
+    else:
+        block.height = sum(c.height or 0 for c in block.children)
+
+
+def layout(doc: Block, width: int) -> None:
+    resolve_width(doc, width)
+    resolve_height(doc)