termflow-md 0.1.0__tar.gz

termflow_md-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  quality:
+    name: Quality (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint with ruff
+        run: uvx ruff check .
+
+      - name: Format check with ruff
+        run: uvx ruff format --check .
+
+      - name: Type check with mypy
+        run: uv run mypy termflow --ignore-missing-imports
+        continue-on-error: true # Optional for now
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Check distribution
+        run: uvx twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 5

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

@@ -0,0 +1,30 @@
+# Publishes to PyPI on release
+# Set PYPI_API_TOKEN in repo secrets
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: uvx twine upload dist/*

termflow_md-0.1.0/.gitignore

@@ -0,0 +1,107 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+*.sublime-project
+*.sublime-workspace
+
+# Linting / Type checking
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# uv cache
+.uv/
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Local development
+*.local
+*.log
+tmp/
+temp/
+
+# Documentation builds
+docs/_build/
+site/

termflow_md-0.1.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to termflow will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+
+- Initial release of termflow 🌊
+- Streaming markdown parser with event-based architecture
+- Terminal renderer with ANSI true-color (24-bit) support
+- Syntax highlighting via Pygments (100+ languages supported)
+- CLI tool (`tf`) with streaming support
+- Configuration via TOML files
+
+#### Markdown Support
+
+- **Headings** (H1-H6) with distinct visual styles
+  - H1: Centered, bold, bright color with double-line underline
+  - H2: Bold, bright color with underline
+  - H3-H6: Progressively subtle styling
+- **Code blocks** with:
+  - Unicode box drawing borders (╭╮╰╯│─)
+  - Language labels
+  - Syntax highlighting
+  - OSC 52 clipboard integration
+- **Inline code** with background highlighting
+- **Text formatting**: bold, italic, underline, strikethrough
+- **Lists**:
+  - Bullet lists with cycling bullets (• ◦ ▪ ▫ ▸ ▹)
+  - Ordered lists with multiple styles (1. a) i. A))
+  - Nested lists with proper indentation
+- **Tables** with Unicode box drawing borders
+- **Block quotes** with vertical bar prefix
+- **Think blocks** for LLM chain-of-thought (`<think>...</think>`)
+- **Horizontal rules**
+- **Links** with OSC 8 hyperlink support
+- **Images** (displayed as alt text with 🖼 icon)
+- **Footnotes**
+
+#### CLI Features
+
+- `tf <file>` - Render markdown file
+- `cat file.md | tf` - Pipe markdown input
+- `-w, --width` - Set terminal width
+- `--style` - Choose color preset (default, dracula, nord, gruvbox)
+- `--syntax-style` - Choose Pygments syntax style
+- `--no-clipboard` - Disable OSC 52 clipboard
+- `--no-hyperlinks` - Disable OSC 8 links
+- `--no-pretty` - Disable decorative borders
+- `--list-syntax-styles` - List available syntax styles
+
+#### Configuration
+
+- TOML configuration file support
+- Search order: `$TERMFLOW_CONFIG` → `~/.config/termflow/config.toml` → `~/.termflow.toml`
+- Customizable colors, features, and syntax style
+
+#### Style Presets
+
+- **default**: Soft, readable colors for dark backgrounds
+- **dracula**: Purple-tinted dark theme
+- **nord**: Arctic, bluish color scheme
+- **gruvbox**: Warm, retro color scheme
+
+[Unreleased]: https://github.com/username/termflow/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/username/termflow/releases/tag/v0.1.0

termflow_md-0.1.0/LICENSE

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

termflow_md-0.1.0/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: termflow-md
+Version: 0.1.0
+Summary: A streaming markdown renderer for modern terminals
+Project-URL: Homepage, https://github.com/mpfaffenberger/termflow
+Project-URL: Repository, https://github.com/mpfaffenberger/termflow
+Project-URL: Documentation, https://github.com/mpfaffenberger/termflow#readme
+Project-URL: Issues, https://github.com/mpfaffenberger/termflow/issues
+Author-email: Your Name <your.email@example.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ansi,cli,markdown,renderer,streaming,syntax-highlighting,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pygments>=2.17.0
+Requires-Dist: wcwidth>=0.2.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: twine>=6.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<!-- Logo placeholder -->
+<!-- <img src="assets/logo.png" alt="termflow logo" width="200"/> -->
+
+# termflow 🌊
+
+**A streaming markdown renderer for modern terminals**
+
+[![PyPI version](https://img.shields.io/pypi/v/termflow.svg)](https://pypi.org/project/termflow/)
+[![Python versions](https://img.shields.io/pypi/pyversions/termflow.svg)](https://pypi.org/project/termflow/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build status](https://img.shields.io/github/actions/workflow/status/your-username/termflow/ci.yml?branch=main)](https://github.com/your-username/termflow/actions)
+
+*Perfect for rendering LLM output in real-time.*
+
+</div>
+
+---
+
+## ✨ Features
+
+- **📡 Streaming Rendering** - Render markdown as it arrives, line by line
+- **🎨 Syntax Highlighting** - Beautiful code blocks powered by Pygments
+- **📊 Tables** - Full support for GitHub-flavored markdown tables
+- **📝 Lists** - Ordered, unordered, and nested lists with smart indentation
+- **💻 Code Blocks** - Fenced code blocks with language detection and clipboard support
+- **💭 Think Blocks** - Special rendering for `<think>` tags (great for LLM chain-of-thought)
+- **🔗 Hyperlinks** - OSC 8 clickable links in supported terminals
+- **📋 Clipboard** - OSC 52 clipboard integration for code blocks
+- **🎛️ Configurable** - Customize colors, styles, and features via TOML config
+- **⚡ Fast** - Lightweight and performant, minimal dependencies
+
+## 🚀 Quick Installation
+
+### Using uvx (recommended)
+
+```bash
+uvx termflow
+```
+
+### Using pip
+
+```bash
+pip install termflow-md
+```
+
+### From source
+
+```bash
+git clone https://github.com/your-username/termflow.git
+cd termflow
+pip install -e ".[dev]"
+```
+
+## 📖 Usage
+
+### Command Line
+
+```bash
+# Render a file
+tf README.md
+
+# Pipe markdown content
+echo "# Hello World" | tf
+
+# Pipe from LLM output
+curl -s https://api.example.com/chat | tf
+
+# Set terminal width
+tf -w 100 document.md
+
+# Use a color preset
+tf --style dracula README.md
+
+# Use a syntax highlighting theme
+tf --syntax-style nord file.md
+
+# Disable clipboard integration
+tf --no-clipboard document.md
+
+# List available syntax styles
+tf --list-syntax-styles
+```
+
+### CLI Options
+
+```
+usage: tf [-h] [-w N] [-c PATH] [--style {default,dracula,nord,gruvbox}]
+          [--syntax-style NAME] [--list-syntax-styles] [--no-clipboard]
+          [--no-hyperlinks] [--no-pretty] [-V]
+          [file]
+
+options:
+  -h, --help            show this help message and exit
+  -w, --width N         Terminal width (default: auto-detect)
+  -c, --config PATH     Path to config file
+  --style PRESET        Color style preset (default, dracula, nord, gruvbox)
+  --syntax-style NAME   Pygments syntax highlighting style
+  --list-syntax-styles  List available syntax highlighting styles
+  --no-clipboard        Disable OSC 52 clipboard for code blocks
+  --no-hyperlinks       Disable OSC 8 hyperlinks
+  --no-pretty           Disable pretty code block borders
+  -V, --version         show program's version number and exit
+```
+
+### Programmatic Usage
+
+```python
+from termflow import Parser, Renderer, render_markdown
+
+# Quick rendering to stdout
+render_markdown("# Hello World!")
+
+# Render to a file or buffer
+from io import StringIO
+
+output = StringIO()
+render_markdown("# Hello\n\nThis is **bold** text.", output=output)
+print(output.getvalue())
+```
+
+### Streaming Mode
+
+For real-time rendering of streaming content (e.g., LLM responses):
+
+```python
+from termflow import Parser, Renderer
+import sys
+
+# Create parser and renderer
+parser = Parser()
+renderer = Renderer(output=sys.stdout, width=80)
+
+# Process markdown line by line as it streams in
+for line in markdown_stream:
+    events = parser.parse_line(line)
+    renderer.render_all(events)
+
+# Finalize to close any open blocks
+renderer.render_all(parser.finalize())
+```
+
+### Custom Styling
+
+```python
+from termflow import Renderer, RenderStyle, RenderFeatures
+from io import StringIO
+
+# Use a preset style
+style = RenderStyle.dracula()  # or .nord(), .gruvbox()
+
+# Or create a custom style
+style = RenderStyle(
+    bright="#87ceeb",   # Main accent color
+    head="#98fb98",     # Heading color
+    symbol="#dda0dd",   # Bullets, borders
+    link="#87cefa",     # Link color
+)
+
+# Configure features
+features = RenderFeatures(
+    clipboard=True,     # OSC 52 clipboard support
+    hyperlinks=True,    # OSC 8 clickable links
+    pretty_pad=True,    # Pretty code block borders
+)
+
+# Create renderer with custom config
+output = StringIO()
+renderer = Renderer(
+    output=output,
+    width=100,
+    style=style,
+    features=features,
+)
+```
+
+## 🔧 Configuration
+
+Create a config file at `~/.config/termflow/config.toml`:
+
+```toml
+# Terminal width (null = auto-detect)
+width = null
+max_width = 120
+
+# Pygments syntax highlighting style
+syntax_style = "monokai"
+
+# Color scheme
+[style]
+bright = "#87ceeb"    # Main accent color
+head = "#98fb98"      # Heading color  
+symbol = "#dda0dd"    # Bullets, table borders, code block borders
+grey = "#808080"      # Muted text
+dark = "#404040"      # Dark accents
+mid = "#a0a0a0"       # Medium text
+light = "#d0d0d0"     # Light accents
+link = "#87cefa"      # Hyperlink color
+error = "#ff6b6b"     # Error messages
+
+# Feature toggles
+[features]
+clipboard = true      # OSC 52 clipboard for code blocks
+hyperlinks = true     # OSC 8 clickable links
+pretty_pad = true     # Pretty unicode borders on code blocks
+```
+
+You can also set the config path via environment variable:
+
+```bash
+export TERMFLOW_CONFIG=/path/to/config.toml
+```
+
+## 🎨 Style Presets
+
+termflow includes several built-in color presets:
+
+| Preset | Description |
+|--------|-------------|
+| `default` | Soft pastel colors |
+| `dracula` | Purple-tinted dark theme |
+| `nord` | Arctic, bluish color palette |
+| `gruvbox` | Retro, earthy colors |
+
+Use them via CLI:
+
+```bash
+tf --style dracula README.md
+```
+
+Or programmatically:
+
+```python
+from termflow import RenderStyle
+
+style = RenderStyle.dracula()
+style = RenderStyle.nord()
+style = RenderStyle.gruvbox()
+```
+
+## 💭 Think Block Support
+
+termflow has special support for `<think>` blocks, commonly used in LLM
+chain-of-thought prompting:
+
+```markdown
+<think>
+Let me reason through this step by step...
+1. First, I'll analyze the problem
+2. Then, I'll formulate a solution
+</think>
+
+Here's my answer based on my reasoning above.
+```
+
+Think blocks are rendered with a distinct style to visually separate the
+model's reasoning from its final response.
+
+## 🦀 Origin
+
+termflow is a Python port of [streamdown-rs](https://github.com/streamdown-rs/streamdown),
+a high-performance streaming markdown renderer written in Rust. This project brings
+the same streaming rendering capabilities to the Python ecosystem with a clean,
+Pythonic API.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+```bash
+# Clone and install for development
+git clone https://github.com/your-username/termflow.git
+cd termflow
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run linter
+ruff check .
+ruff format .
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+<div align="center">
+
+Made with ❤️ for the terminal
+
+</div>