termflow-md 0.1.0__py3-none-any.whl

termflow/__init__.py

@@ -0,0 +1,58 @@
+"""termflow - A streaming markdown renderer for modern terminals.
+
+A Python port of streamdown-rs, providing beautiful markdown rendering
+directly in your terminal with streaming support, syntax highlighting,
+and rich formatting.
+
+Basic usage:
+    >>> from termflow import render_markdown
+    >>> render_markdown("# Hello World!")
+
+Streaming usage:
+    >>> from termflow import Parser, Renderer
+    >>> parser = Parser()
+    >>> renderer = Renderer(width=80)
+    >>>
+    >>> for line in markdown_lines:
+    ...     events = parser.parse_line(line)
+    ...     renderer.render_all(events)
+    >>>
+    >>> renderer.render_all(parser.finalize())
+
+With configuration:
+    >>> from termflow import Config, Renderer, RenderStyle
+    >>> config = Config.load()
+    >>> style = RenderStyle.dracula()
+    >>> renderer = Renderer(style=style, features=config.features)
+
+CLI usage:
+    $ cat README.md | tf
+    $ tf document.md
+    $ tf --style dracula README.md
+"""
+
+__version__ = "0.1.0"
+
+from termflow.config import Config
+from termflow.parser import Parser
+from termflow.parser.events import ParseEvent
+from termflow.render import Renderer, RenderFeatures, RenderStyle, render_markdown
+from termflow.syntax import Highlighter, highlight_code
+
+__all__ = [
+    # Core classes
+    "Config",
+    "Highlighter",
+    # Events
+    "ParseEvent",
+    "Parser",
+    # Style
+    "RenderFeatures",
+    "RenderStyle",
+    "Renderer",
+    # Version
+    "__version__",
+    # Convenience functions
+    "highlight_code",
+    "render_markdown",
+]

termflow/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m termflow."""
+
+from termflow.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

termflow/ansi/__init__.py

@@ -0,0 +1,103 @@
+"""ANSI module - terminal escape codes and styling.
+
+This module provides comprehensive ANSI escape code support for terminal
+rendering, including:
+
+- Raw escape code constants (codes.py)
+- Color conversion utilities (color.py)
+- Style pairs for easy toggling (style.py)
+- Text processing utilities (utils.py)
+
+Example:
+    >>> from termflow.ansi import BOLD, fg_color, visible_length
+    >>> styled = f"{BOLD[0]}{fg_color('#FF5500')}Orange Bold{BOLD[1]}"
+    >>> print(visible_length(styled))  # Returns 11, not counting ANSI codes
+"""
+
+from termflow.ansi.codes import (
+    BGRESET,
+    BOLD_OFF,
+    BOLD_ON,
+    DIM_OFF,
+    DIM_ON,
+    ITALIC_OFF,
+    ITALIC_ON,
+    RESET,
+    STRIKEOUT_OFF,
+    STRIKEOUT_ON,
+    SUPERSCRIPTS,
+    UNDERLINE_OFF,
+    UNDERLINE_ON,
+    digit_to_superscript,
+    number_to_superscript,
+)
+from termflow.ansi.color import (
+    bg_color,
+    fg_color,
+    hex2rgb,
+    hsv_to_rgb,
+    rgb2hex,
+)
+from termflow.ansi.style import (
+    BOLD,
+    DIM,
+    ITALIC,
+    LINK,
+    STRIKEOUT,
+    UNDERLINE,
+    make_link,
+)
+from termflow.ansi.utils import (
+    ANSI_CSI_RE,
+    ANSI_ESCAPE_RE,
+    ANSI_SGR_RE,
+    extract_ansi_codes,
+    is_ansi_code,
+    parse_sgr_params,
+    split_ansi,
+    truncate_ansi,
+    visible,
+    visible_length,
+    wrap_ansi,
+)
+
+__all__ = [
+    "ANSI_CSI_RE",
+    "ANSI_ESCAPE_RE",
+    "ANSI_SGR_RE",
+    "BGRESET",
+    "BOLD",
+    "BOLD_OFF",
+    "BOLD_ON",
+    "DIM",
+    "DIM_OFF",
+    "DIM_ON",
+    "ITALIC",
+    "ITALIC_OFF",
+    "ITALIC_ON",
+    "LINK",
+    "RESET",
+    "STRIKEOUT",
+    "STRIKEOUT_OFF",
+    "STRIKEOUT_ON",
+    "SUPERSCRIPTS",
+    "UNDERLINE",
+    "UNDERLINE_OFF",
+    "UNDERLINE_ON",
+    "bg_color",
+    "digit_to_superscript",
+    "extract_ansi_codes",
+    "fg_color",
+    "hex2rgb",
+    "hsv_to_rgb",
+    "is_ansi_code",
+    "make_link",
+    "number_to_superscript",
+    "parse_sgr_params",
+    "rgb2hex",
+    "split_ansi",
+    "truncate_ansi",
+    "visible",
+    "visible_length",
+    "wrap_ansi",
+]

termflow/ansi/codes.py

@@ -0,0 +1,92 @@
+"""ANSI escape code constants and superscript utilities.
+
+This module provides all the raw ANSI escape sequences needed for terminal
+text styling, along with utilities for converting digits to Unicode superscripts.
+"""
+
+# =============================================================================
+# Reset
+# =============================================================================
+RESET = "\x1b[0m"
+
+# =============================================================================
+# Text Styles - On/Off pairs
+# =============================================================================
+BOLD_ON = "\x1b[1m"
+BOLD_OFF = "\x1b[22m"  # Also turns off DIM
+
+DIM_ON = "\x1b[2m"
+DIM_OFF = "\x1b[22m"  # Also turns off BOLD
+
+ITALIC_ON = "\x1b[3m"
+ITALIC_OFF = "\x1b[23m"
+
+UNDERLINE_ON = "\x1b[4m"
+UNDERLINE_OFF = "\x1b[24m"
+
+STRIKEOUT_ON = "\x1b[9m"
+STRIKEOUT_OFF = "\x1b[29m"
+
+# =============================================================================
+# Background
+# =============================================================================
+BGRESET = "\x1b[49m"
+
+# =============================================================================
+# Superscript Unicode Characters
+# =============================================================================
+SUPERSCRIPTS = "⁰¹²³⁴⁵⁶⁷⁸⁹"
+
+
+def digit_to_superscript(digit: int) -> str:
+    """Convert a digit (0-9) to its superscript Unicode character.
+
+    Args:
+        digit: An integer from 0 to 9.
+
+    Returns:
+        The corresponding superscript Unicode character.
+
+    Raises:
+        ValueError: If digit is not in range 0-9.
+
+    Example:
+        >>> digit_to_superscript(2)
+        '²'
+        >>> digit_to_superscript(0)
+        '⁰'
+    """
+    if not 0 <= digit <= 9:
+        raise ValueError(f"Digit must be 0-9, got {digit}")
+    return SUPERSCRIPTS[digit]
+
+
+def number_to_superscript(num: int) -> str:
+    """Convert an integer to its superscript string representation.
+
+    Handles negative numbers by prefixing with superscript minus (⁻).
+
+    Args:
+        num: Any integer.
+
+    Returns:
+        The superscript representation of the number.
+
+    Example:
+        >>> number_to_superscript(42)
+        '⁴²'
+        >>> number_to_superscript(-5)
+        '⁻⁵'
+        >>> number_to_superscript(0)
+        '⁰'
+    """
+    if num < 0:
+        return "⁻" + number_to_superscript(-num)
+    if num == 0:
+        return SUPERSCRIPTS[0]
+
+    result = []
+    while num > 0:
+        result.append(SUPERSCRIPTS[num % 10])
+        num //= 10
+    return "".join(reversed(result))

termflow/ansi/color.py

@@ -0,0 +1,160 @@
+"""HSV/RGB color utilities for ANSI terminal colors.
+
+This module provides color conversion functions and ANSI escape sequence
+generators for 24-bit (truecolor) terminal support.
+"""
+
+import re
+
+# Regex for hex color validation
+_HEX_COLOR_RE = re.compile(r"^#?([0-9a-fA-F]{6})$")
+
+
+def hex2rgb(hex_color: str) -> tuple[int, int, int] | None:
+    """Convert hex color (#RRGGBB or RRGGBB) to RGB tuple.
+
+    Args:
+        hex_color: Hex color string, with or without leading '#'.
+
+    Returns:
+        Tuple of (R, G, B) values (0-255 each), or None if invalid.
+
+    Example:
+        >>> hex2rgb("#FF5500")
+        (255, 85, 0)
+        >>> hex2rgb("00FF00")
+        (0, 255, 0)
+        >>> hex2rgb("invalid")
+        None
+    """
+    match = _HEX_COLOR_RE.match(hex_color)
+    if not match:
+        return None
+
+    hex_str = match.group(1)
+    return (
+        int(hex_str[0:2], 16),
+        int(hex_str[2:4], 16),
+        int(hex_str[4:6], 16),
+    )
+
+
+def rgb2hex(r: int, g: int, b: int) -> str:
+    """Convert RGB values to hex string (#RRGGBB).
+
+    Args:
+        r: Red component (0-255).
+        g: Green component (0-255).
+        b: Blue component (0-255).
+
+    Returns:
+        Hex color string with leading '#'.
+
+    Example:
+        >>> rgb2hex(255, 85, 0)
+        '#FF5500'
+        >>> rgb2hex(0, 0, 0)
+        '#000000'
+    """
+    # Clamp values to valid range
+    r = max(0, min(255, r))
+    g = max(0, min(255, g))
+    b = max(0, min(255, b))
+    return f"#{r:02X}{g:02X}{b:02X}"
+
+
+def hsv_to_rgb(h: float, s: float, v: float) -> tuple[int, int, int]:
+    """Convert HSV color to RGB.
+
+    Args:
+        h: Hue (0.0-1.0).
+        s: Saturation (0.0-1.0).
+        v: Value/brightness (0.0-1.0).
+
+    Returns:
+        Tuple of (R, G, B) values (0-255 each).
+
+    Example:
+        >>> hsv_to_rgb(0.0, 1.0, 1.0)  # Red
+        (255, 0, 0)
+        >>> hsv_to_rgb(0.333, 1.0, 1.0)  # Green-ish
+        (0, 255, 2)
+        >>> hsv_to_rgb(0.0, 0.0, 1.0)  # White
+        (255, 255, 255)
+    """
+    if s == 0.0:
+        # Achromatic (grey)
+        val = int(v * 255)
+        return (val, val, val)
+
+    h = h % 1.0  # Wrap hue to 0-1 range
+    h *= 6.0
+    i = int(h)
+    f = h - i
+
+    p = v * (1.0 - s)
+    q = v * (1.0 - s * f)
+    t = v * (1.0 - s * (1.0 - f))
+
+    if i == 0:
+        r, g, b = v, t, p
+    elif i == 1:
+        r, g, b = q, v, p
+    elif i == 2:
+        r, g, b = p, v, t
+    elif i == 3:
+        r, g, b = p, q, v
+    elif i == 4:
+        r, g, b = t, p, v
+    else:
+        r, g, b = v, p, q
+
+    return (int(r * 255), int(g * 255), int(b * 255))
+
+
+def fg_color(hex_color: str) -> str:
+    """Generate foreground ANSI escape sequence from hex color.
+
+    Uses 24-bit truecolor ANSI escape codes (\x1b[38;2;R;G;Bm).
+
+    Args:
+        hex_color: Hex color string (#RRGGBB or RRGGBB).
+
+    Returns:
+        ANSI escape sequence for foreground color, or empty string if invalid.
+
+    Example:
+        >>> fg_color("#FF5500")
+        '\\x1b[38;2;255;85;0m'
+        >>> fg_color("invalid")
+        ''
+    """
+    rgb = hex2rgb(hex_color)
+    if rgb is None:
+        return ""
+    r, g, b = rgb
+    return f"\x1b[38;2;{r};{g};{b}m"
+
+
+def bg_color(hex_color: str) -> str:
+    """Generate background ANSI escape sequence from hex color.
+
+    Uses 24-bit truecolor ANSI escape codes (\x1b[48;2;R;G;Bm).
+
+    Args:
+        hex_color: Hex color string (#RRGGBB or RRGGBB).
+
+    Returns:
+        ANSI escape sequence for background color, or empty string if invalid.
+
+    Example:
+        >>> bg_color("#FF5500")
+        '\\x1b[48;2;255;85;0m'
+        >>> bg_color("invalid")
+        ''
+    """
+    rgb = hex2rgb(hex_color)
+    if rgb is None:
+        return ""
+    r, g, b = rgb
+    return f"\x1b[48;2;{r};{g};{b}m"

termflow/ansi/style.py

@@ -0,0 +1,51 @@
+"""Style pairs (on, off) tuples for easy toggling.
+
+These tuples make it easy to wrap text with styles:
+    styled_text = f"{BOLD[0]}bold text{BOLD[1]}"
+
+Each tuple is (on_code, off_code) for symmetric style application.
+"""
+
+# =============================================================================
+# Text Style Pairs: (on, off)
+# =============================================================================
+
+#: Bold text style - Note: BOLD_OFF (22m) also turns off DIM
+BOLD: tuple[str, str] = ("\x1b[1m", "\x1b[22m")
+
+#: Dim/faint text style - Note: DIM_OFF (22m) also turns off BOLD
+DIM: tuple[str, str] = ("\x1b[2m", "\x1b[22m")
+
+#: Italic text style
+ITALIC: tuple[str, str] = ("\x1b[3m", "\x1b[23m")
+
+#: Underline text style
+UNDERLINE: tuple[str, str] = ("\x1b[4m", "\x1b[24m")
+
+#: Strikethrough/strikeout text style
+STRIKEOUT: tuple[str, str] = ("\x1b[9m", "\x1b[29m")
+
+# =============================================================================
+# OSC 8 Hyperlink
+# =============================================================================
+
+#: OSC 8 hyperlink - Usage: f"{LINK[0]}{url}\x1b\\{text}{LINK[1]}"
+#: The URL goes after LINK[0], then ST (\x1b\\), then visible text, then LINK[1]
+LINK: tuple[str, str] = ("\x1b]8;;", "\x1b]8;;\x1b\\")
+
+
+def make_link(url: str, text: str) -> str:
+    """Create an OSC 8 hyperlink.
+
+    Args:
+        url: The URL to link to.
+        text: The visible text to display.
+
+    Returns:
+        ANSI-escaped hyperlink string.
+
+    Example:
+        >>> link = make_link("https://example.com", "Click here")
+        >>> # Renders as clickable "Click here" in supported terminals
+    """
+    return f"{LINK[0]}{url}\x1b\\{text}{LINK[1]}"