tg-rich-render 0.1.0__tar.gz

tg_rich_render-0.1.0/LICENSE

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

tg_rich_render-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: tg-rich-render
+Version: 0.1.0
+Summary: Lightweight Telegram rich table and format converter with zero-dependency CJK alignment.
+Author-email: shali10 <99240403+shali10@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shali10/tg-rich-render
+Project-URL: Repository, https://github.com/shali10/tg-rich-render
+Project-URL: Issues, https://github.com/shali10/tg-rich-render/issues
+Keywords: telegram,aiogram,telegram-bot,table,markdown,cjk,rich-formatting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tg-rich-render 📊✨
+
+> **Zero-dependency, CJK-aware Markdown table & rich format converter for Telegram bots.**  
+> 专治 Telegram 机器人表格排版错位、中英混排对不齐、手机端横向溢出变难看代码块的痛点。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![CI Status](https://github.com/shali10/tg-rich-render/actions/workflows/ci.yml/badge.svg)](https://github.com/shali10/tg-rich-render/actions)
+
+---
+
+## 💡 为什么需要 tg-rich-render？
+
+Telegram 官方的 MarkdownV2 并不支持标准的 GFM Pipe Table（管道表格）。在日常 Telegram 机器人开发（运维巡检播报、资产统计、行情早报）中，直接发送表格通常会遇到以下问题：
+
+1. **直接报错**：Telegram Bot API 无法解析 `| col | col |` 语法；
+2. **粗暴丢进代码块**：直接用 ```` 包裹，但在中英汉字、Emoji 混排时由于字符显示宽度（CJK 宽度为 2）导致竖线完全错位，排版歪歪扭扭；
+3. **窄屏移动端阅读体验差**：宽表格在手机竖屏下横向拉长折行。
+
+`tg-rich-render` 提供纯 Python 标准库实现的智能 CJK 宽度对齐与多风格自适应渲染，一行代码即可集成到 **aiogram 3**、**python-telegram-bot** 或任何 HTTP 请求中。
+
+---
+
+## ✨ 核心特性
+
+- 🚀 **零外部依赖**：纯 Python 标准库构建（基于 `unicodedata` 模块），即装即用，启动开销 0ms。
+- 📐 **精准 CJK / Emoji 宽度补偿**：完美对齐汉字、日韩文、全角符号与 Emoji 表情，拒绝折线与锯齿。
+- 🎨 **多风格视觉呈现**：
+  - `rounded`：现代优雅圆角框线（`╭───┬───╮`），视觉质感拉满。
+  - `classic`：经典 ASCII 风格（`+---+---+`）。
+  - `clean`：极简流式无竖框风格。
+  - `card`：移动端窄屏优先卡片流（键值对展示，杜绝横向滚动）。
+  - `html`：Telegram 兼容 HTML `<table>` 格式。
+- 🤖 **主流框架开箱即用**：自带 aiogram 3 与 python-telegram-bot 发送适配器。
+- 💻 **CLI 工具支持**：支持管道输入与终端即时预览。
+
+---
+
+## 📦 快速安装
+
+```bash
+pip install tg-rich-render
+```
+
+或直接克隆使用：
+
+```bash
+git clone https://github.com/shali10/tg-rich-render.git
+cd tg-rich-render
+pip install -e .
+```
+
+---
+
+## 🚀 快速上手
+
+### 1. 独立使用（纯 Python）
+
+```python
+from tg_rich_render import render_telegram
+
+raw_markdown = """
+# 节点健康巡检
+
+| 节点 | 状态 | 延迟 |
+|:---|:---:|---:|
+| 香港CN2 🚀 | 正常 | 15ms |
+| 美国洛杉矶 | 良好 | 135ms |
+| 日本东京 ⚡ | 正常 | 48ms |
+
+巡检完成，无异常节点。
+"""
+
+# 渲染为 Telegram 优雅圆角等宽表格
+message = render_telegram(raw_markdown, style="rounded")
+print(message)
+```
+
+**输出效果：**
+
+```
+# 节点健康巡检
+
+```
+╭────────────┬──────┬───────╮
+│ 节点       │ 状态 │  延迟 │
+├────────────┼──────┼───────┤
+│ 香港CN2 🚀 │ 正常 │  15ms │
+│ 美国洛杉矶 │ 良好 │ 135ms │
+│ 日本东京 ⚡ │ 正常 │  48ms │
+╰────────────┴──────┴───────╯
+```
+
+巡检完成，无异常节点。
+```
+
+---
+
+### 2. 结合 aiogram 3
+
+```python
+from aiogram import Bot
+from tg_rich_render import send_smart_message
+
+bot = Bot(token="YOUR_BOT_TOKEN")
+
+# 一行代码自适应格式化并发送
+await send_smart_message(
+    bot=bot,
+    chat_id=12345678,
+    text=raw_markdown,
+    table_style="rounded"
+)
+```
+
+---
+
+### 3. 结合 python-telegram-bot
+
+```python
+from telegram import Bot
+from tg_rich_render import send_smart_message
+
+bot = Bot(token="YOUR_BOT_TOKEN")
+
+await send_smart_message(
+    bot=bot,
+    chat_id=12345678,
+    text=raw_markdown,
+    table_style="rounded"
+)
+```
+
+---
+
+### 4. 命令行（CLI）使用
+
+```bash
+# 转换 Markdown 文件
+tg-rich-render report.md --style rounded
+
+# 从终端管道流式转换
+cat summary.md | tg-rich-render --style card
+```
+
+---
+
+## 🎨 渲染风格展示
+
+| 风格名称 | 预览示意 | 适用场景 |
+|:---|:---|:---|
+| **rounded** (默认) | `╭─┬─╮\n│A│B│\n╰─┴─╯` | PC 端与大屏客户端，视觉质感极高 |
+| **classic** | `+-+-+\n|A|B|\n+-+-+` | 通用等宽终端、标准日志输出 |
+| **clean** | `A  B\n─  ─\n1  2` | 极简通知、紧凑监控通知 |
+| **card** | `📌 节点\n  • 延迟: 15ms` | 移动端窄屏、列数较多的宽表格 |
+| **html** | `<table>...</table>` | Telegram WebApp 或特定富文本容器 |
+
+---
+
+## 🧪 单元测试
+
+项目自带完整的自动化测试集（覆盖 CJK 宽度、对齐算法、长文本解析与适配器）：
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+---
+
+## 📄 开源许可
+
+本项目基于 [MIT License](LICENSE) 开源。

tg_rich_render-0.1.0/README.md

@@ -0,0 +1,172 @@
+# tg-rich-render 📊✨
+
+> **Zero-dependency, CJK-aware Markdown table & rich format converter for Telegram bots.**  
+> 专治 Telegram 机器人表格排版错位、中英混排对不齐、手机端横向溢出变难看代码块的痛点。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![CI Status](https://github.com/shali10/tg-rich-render/actions/workflows/ci.yml/badge.svg)](https://github.com/shali10/tg-rich-render/actions)
+
+---
+
+## 💡 为什么需要 tg-rich-render？
+
+Telegram 官方的 MarkdownV2 并不支持标准的 GFM Pipe Table（管道表格）。在日常 Telegram 机器人开发（运维巡检播报、资产统计、行情早报）中，直接发送表格通常会遇到以下问题：
+
+1. **直接报错**：Telegram Bot API 无法解析 `| col | col |` 语法；
+2. **粗暴丢进代码块**：直接用 ```` 包裹，但在中英汉字、Emoji 混排时由于字符显示宽度（CJK 宽度为 2）导致竖线完全错位，排版歪歪扭扭；
+3. **窄屏移动端阅读体验差**：宽表格在手机竖屏下横向拉长折行。
+
+`tg-rich-render` 提供纯 Python 标准库实现的智能 CJK 宽度对齐与多风格自适应渲染，一行代码即可集成到 **aiogram 3**、**python-telegram-bot** 或任何 HTTP 请求中。
+
+---
+
+## ✨ 核心特性
+
+- 🚀 **零外部依赖**：纯 Python 标准库构建（基于 `unicodedata` 模块），即装即用，启动开销 0ms。
+- 📐 **精准 CJK / Emoji 宽度补偿**：完美对齐汉字、日韩文、全角符号与 Emoji 表情，拒绝折线与锯齿。
+- 🎨 **多风格视觉呈现**：
+  - `rounded`：现代优雅圆角框线（`╭───┬───╮`），视觉质感拉满。
+  - `classic`：经典 ASCII 风格（`+---+---+`）。
+  - `clean`：极简流式无竖框风格。
+  - `card`：移动端窄屏优先卡片流（键值对展示，杜绝横向滚动）。
+  - `html`：Telegram 兼容 HTML `<table>` 格式。
+- 🤖 **主流框架开箱即用**：自带 aiogram 3 与 python-telegram-bot 发送适配器。
+- 💻 **CLI 工具支持**：支持管道输入与终端即时预览。
+
+---
+
+## 📦 快速安装
+
+```bash
+pip install tg-rich-render
+```
+
+或直接克隆使用：
+
+```bash
+git clone https://github.com/shali10/tg-rich-render.git
+cd tg-rich-render
+pip install -e .
+```
+
+---
+
+## 🚀 快速上手
+
+### 1. 独立使用（纯 Python）
+
+```python
+from tg_rich_render import render_telegram
+
+raw_markdown = """
+# 节点健康巡检
+
+| 节点 | 状态 | 延迟 |
+|:---|:---:|---:|
+| 香港CN2 🚀 | 正常 | 15ms |
+| 美国洛杉矶 | 良好 | 135ms |
+| 日本东京 ⚡ | 正常 | 48ms |
+
+巡检完成，无异常节点。
+"""
+
+# 渲染为 Telegram 优雅圆角等宽表格
+message = render_telegram(raw_markdown, style="rounded")
+print(message)
+```
+
+**输出效果：**
+
+```
+# 节点健康巡检
+
+```
+╭────────────┬──────┬───────╮
+│ 节点       │ 状态 │  延迟 │
+├────────────┼──────┼───────┤
+│ 香港CN2 🚀 │ 正常 │  15ms │
+│ 美国洛杉矶 │ 良好 │ 135ms │
+│ 日本东京 ⚡ │ 正常 │  48ms │
+╰────────────┴──────┴───────╯
+```
+
+巡检完成，无异常节点。
+```
+
+---
+
+### 2. 结合 aiogram 3
+
+```python
+from aiogram import Bot
+from tg_rich_render import send_smart_message
+
+bot = Bot(token="YOUR_BOT_TOKEN")
+
+# 一行代码自适应格式化并发送
+await send_smart_message(
+    bot=bot,
+    chat_id=12345678,
+    text=raw_markdown,
+    table_style="rounded"
+)
+```
+
+---
+
+### 3. 结合 python-telegram-bot
+
+```python
+from telegram import Bot
+from tg_rich_render import send_smart_message
+
+bot = Bot(token="YOUR_BOT_TOKEN")
+
+await send_smart_message(
+    bot=bot,
+    chat_id=12345678,
+    text=raw_markdown,
+    table_style="rounded"
+)
+```
+
+---
+
+### 4. 命令行（CLI）使用
+
+```bash
+# 转换 Markdown 文件
+tg-rich-render report.md --style rounded
+
+# 从终端管道流式转换
+cat summary.md | tg-rich-render --style card
+```
+
+---
+
+## 🎨 渲染风格展示
+
+| 风格名称 | 预览示意 | 适用场景 |
+|:---|:---|:---|
+| **rounded** (默认) | `╭─┬─╮\n│A│B│\n╰─┴─╯` | PC 端与大屏客户端，视觉质感极高 |
+| **classic** | `+-+-+\n|A|B|\n+-+-+` | 通用等宽终端、标准日志输出 |
+| **clean** | `A  B\n─  ─\n1  2` | 极简通知、紧凑监控通知 |
+| **card** | `📌 节点\n  • 延迟: 15ms` | 移动端窄屏、列数较多的宽表格 |
+| **html** | `<table>...</table>` | Telegram WebApp 或特定富文本容器 |
+
+---
+
+## 🧪 单元测试
+
+项目自带完整的自动化测试集（覆盖 CJK 宽度、对齐算法、长文本解析与适配器）：
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+---
+
+## 📄 开源许可
+
+本项目基于 [MIT License](LICENSE) 开源。

tg_rich_render-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tg-rich-render"
+version = "0.1.0"
+description = "Lightweight Telegram rich table and format converter with zero-dependency CJK alignment."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "shali10", email = "99240403+shali10@users.noreply.github.com" }
+]
+keywords = ["telegram", "aiogram", "telegram-bot", "table", "markdown", "cjk", "rich-formatting"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.8"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/shali10/tg-rich-render"
+Repository = "https://github.com/shali10/tg-rich-render"
+Issues = "https://github.com/shali10/tg-rich-render/issues"
+
+[project.scripts]
+tg-rich-render = "tg_rich_render.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tg_rich_render*"]

tg_rich_render-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tg_rich_render-0.1.0/tests/test_adapter.py

@@ -0,0 +1,29 @@
+import unittest
+from tg_rich_render.adapter import smart_format_payload
+
+MD_SAMPLE = """
+| 维度 | 得分 |
+|---|---|
+| 速度 | 98 |
+"""
+
+class TestAdapter(unittest.TestCase):
+    def test_smart_format_payload_default():
+        payload = smart_format_payload(MD_SAMPLE)
+        self.assertIsNone(payload["parse_mode"])
+        self.assertIn("╭", payload["text"])
+        self.assertIn("```", payload["text"])
+
+    def test_smart_format_payload_html(self):
+        payload = smart_format_payload(MD_SAMPLE, prefer_html=True)
+        self.assertEqual(payload["parse_mode"], "HTML")
+        self.assertIn("<table>", payload["text"])
+
+    def test_smart_format_payload_default(self):
+        payload = smart_format_payload(MD_SAMPLE)
+        self.assertIsNone(payload["parse_mode"])
+        self.assertIn("╭", payload["text"])
+        self.assertIn("```", payload["text"])
+
+if __name__ == '__main__':
+    unittest.main()

tg_rich_render-0.1.0/tests/test_cjk.py

@@ -0,0 +1,31 @@
+import unittest
+from tg_rich_render.cjk import get_display_width, pad_cjk, strip_ansi
+
+class TestCJK(unittest.TestCase):
+    def test_strip_ansi(self):
+        colored = "\x1b[31mRed Text\x1b[0m"
+        self.assertEqual(strip_ansi(colored), "Red Text")
+        self.assertEqual(get_display_width(colored), 8)
+
+    def test_get_display_width(self):
+        self.assertEqual(get_display_width("hello"), 5)
+        self.assertEqual(get_display_width("你好"), 4)
+        self.assertEqual(get_display_width("Hello, 世界！"), 13)
+
+    def test_pad_cjk(self):
+        # Left alignment
+        padded = pad_cjk("测试", 6, align='left')
+        self.assertEqual(padded, "测试  ")
+        self.assertEqual(get_display_width(padded), 6)
+
+        # Right alignment
+        padded_r = pad_cjk("测试", 6, align='right')
+        self.assertEqual(padded_r, "  测试")
+        self.assertEqual(get_display_width(padded_r), 6)
+
+        # Center alignment
+        padded_c = pad_cjk("A", 5, align='center')
+        self.assertEqual(padded_c, "  A  ")
+
+if __name__ == '__main__':
+    unittest.main()

tg_rich_render-0.1.0/tests/test_parser.py

@@ -0,0 +1,41 @@
+import unittest
+from tg_rich_render.parser import render_telegram, extract_tables_and_text
+
+DOC = """# 系统巡检报告
+
+以下是当前节点健康度：
+
+| 节点 | CPU | 内存 |
+|---|---|---|
+| US-East | 14% | 42% |
+| HK-01 | 28% | 65% |
+
+```bash
+# 这里是普通代码块，不应被误判为表格
+| not | a | table |
+```
+
+请及时关注高负载节点。
+"""
+
+class TestParser(unittest.TestCase):
+    def test_extract_tables_and_text(self):
+        blocks = extract_tables_and_text(DOC)
+        types = [b[0] for b in blocks]
+        self.assertIn('table', types)
+        self.assertEqual(types.count('table'), 1)
+
+    def test_render_telegram_rounded(self):
+        out = render_telegram(DOC, style='rounded')
+        self.assertIn("```", out)
+        self.assertIn("╭", out)
+        self.assertIn("系统巡检报告", out)
+        self.assertIn("请及时关注高负载节点", out)
+
+    def test_render_telegram_card(self):
+        out = render_telegram(DOC, style='card')
+        self.assertIn("📌 US-East", out)
+        self.assertIn("• CPU: 14%", out)
+
+if __name__ == '__main__':
+    unittest.main()

tg_rich_render-0.1.0/tests/test_table.py

@@ -0,0 +1,51 @@
+import unittest
+from tg_rich_render.table import Table
+
+RAW_TABLE = """
+| 服务 | 状态 | 延迟 |
+|:---|:---:|---:|
+| API 网关 | 运行中 | 12ms |
+| 数据库 | 正常 | 2ms |
+"""
+
+class TestTable(unittest.TestCase):
+    def test_table_parsing(self):
+        table = Table.from_markdown(RAW_TABLE)
+        self.assertIsNotNone(table)
+        self.assertEqual(table.headers, ["服务", "状态", "延迟"])
+        self.assertEqual(len(table.rows), 2)
+        self.assertEqual(table.alignments, ["left", "center", "right"])
+
+    def test_table_render_rounded(self):
+        table = Table.from_markdown(RAW_TABLE)
+        rendered = table.render_rounded()
+        self.assertIn("╭", rendered)
+        self.assertIn("╰", rendered)
+        self.assertIn("API 网关", rendered)
+
+    def test_table_render_classic(self):
+        table = Table.from_markdown(RAW_TABLE)
+        rendered = table.render_classic()
+        self.assertIn("+", rendered)
+        self.assertIn("|", rendered)
+
+    def test_table_render_clean(self):
+        table = Table.from_markdown(RAW_TABLE)
+        rendered = table.render_clean()
+        self.assertIn("─", rendered)
+        self.assertIn("API 网关", rendered)
+
+    def test_table_render_card(self):
+        table = Table.from_markdown(RAW_TABLE)
+        rendered = table.render_card()
+        self.assertIn("📌 API 网关", rendered)
+        self.assertIn("• 状态: 运行中", rendered)
+
+    def test_table_render_html(self):
+        table = Table.from_markdown(RAW_TABLE)
+        rendered = table.render_html()
+        self.assertIn("<table>", rendered)
+        self.assertIn("<th>服务</th>", rendered)
+
+if __name__ == '__main__':
+    unittest.main()

tg_rich_render-0.1.0/tg_rich_render/__init__.py

@@ -0,0 +1,22 @@
+"""tg-rich-render: Lightweight Telegram rich table and format converter.
+
+Solves the common pain point of ugly, misaligned tables in Telegram bots.
+Provides zero-dependency CJK alignment and multi-style table formatting.
+"""
+
+from tg_rich_render.cjk import get_display_width, pad_cjk
+from tg_rich_render.table import Table
+from tg_rich_render.parser import render_telegram, extract_tables_and_text, TableStyle
+from tg_rich_render.adapter import smart_format_payload, send_smart_message
+
+__version__ = "0.1.0"
+__all__ = [
+    "Table",
+    "TableStyle",
+    "get_display_width",
+    "pad_cjk",
+    "render_telegram",
+    "extract_tables_and_text",
+    "smart_format_payload",
+    "send_smart_message",
+]

tg_rich_render-0.1.0/tg_rich_render/adapter.py

@@ -0,0 +1,50 @@
+"""Adapters and helper bindings for aiogram 3 and python-telegram-bot.
+"""
+
+from typing import Any, Optional, Dict, Literal
+from tg_rich_render.parser import render_telegram, TableStyle
+
+def smart_format_payload(
+    text: str,
+    prefer_html: bool = False,
+    table_style: TableStyle = 'rounded'
+) -> Dict[str, Any]:
+    """Prepare payload dictionary with formatted text and appropriate parse_mode."""
+    if prefer_html:
+        formatted = render_telegram(text, style='html')
+        return {
+            "text": formatted,
+            "parse_mode": "HTML"
+        }
+    else:
+        formatted = render_telegram(text, style=table_style, wrap_in_code_block=True)
+        return {
+            "text": formatted,
+            "parse_mode": None  # Plain/Markdown compatible
+        }
+
+async def send_smart_message(
+    bot: Any,
+    chat_id: Any,
+    text: str,
+    table_style: TableStyle = 'rounded',
+    **kwargs
+) -> Any:
+    """Send a message through aiogram 3 or python-telegram-bot with auto-formatted rich tables.
+    
+    Compatible with:
+    - aiogram 3.x (Bot instance)
+    - python-telegram-bot 20+ (Bot or ExtBot instance)
+    """
+    payload = smart_format_payload(text, table_style=table_style)
+    send_kwargs = {**payload, **kwargs}
+
+    # aiogram 3.x
+    if hasattr(bot, 'send_message') and callable(getattr(bot, 'send_message')):
+        return await bot.send_message(chat_id=chat_id, **send_kwargs)
+    
+    # python-telegram-bot
+    elif hasattr(bot, 'send_message'):
+        return await bot.send_message(chat_id=chat_id, **send_kwargs)
+    
+    raise TypeError(f"Unsupported bot instance type: {type(bot)}")

tg_rich_render-0.1.0/tg_rich_render/cjk.py

@@ -0,0 +1,51 @@
+"""CJK and wide-character display width utilities.
+
+Ensures perfect column alignment for Chinese, Japanese, Korean,
+full-width punctuation, and emoji in Telegram monospace contexts.
+Also strips ANSI escapes so styled strings calculate accurately.
+"""
+
+import re
+import unicodedata
+from typing import Literal
+
+ANSI_RE = re.compile(r'\x1b\[[0-9;]*[a-zA-Z]')
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from string."""
+    return ANSI_RE.sub('', text)
+
+def get_char_width(ch: str) -> int:
+    """Return the display column width of a single unicode character."""
+    # Control characters
+    if unicodedata.category(ch).startswith('C'):
+        return 0
+    # East Asian Width property
+    # W: Wide, F: Fullwidth -> 2 columns
+    # A: Ambiguous -> usually 1 column in modern monospace fonts
+    # Na: Narrow, N: Neutral, H: Halfwidth -> 1 column
+    status = unicodedata.east_asian_width(ch)
+    if status in ('W', 'F'):
+        return 2
+    return 1
+
+def get_display_width(text: str) -> int:
+    """Calculate the total display width of a string in monospace columns."""
+    clean_text = strip_ansi(text)
+    return sum(get_char_width(ch) for ch in clean_text)
+
+def pad_cjk(text: str, width: int, align: Literal['left', 'right', 'center'] = 'left') -> str:
+    """Pad a string containing CJK characters to the specified display width."""
+    current_width = get_display_width(text)
+    if current_width >= width:
+        return text
+    
+    pad_needed = width - current_width
+    if align == 'right':
+        return ' ' * pad_needed + text
+    elif align == 'center':
+        left_pad = pad_needed // 2
+        right_pad = pad_needed - left_pad
+        return ' ' * left_pad + text + ' ' * right_pad
+    else:  # left
+        return text + ' ' * pad_needed

tg_rich_render-0.1.0/tg_rich_render/cli.py

@@ -0,0 +1,44 @@
+"""Command Line Interface for tg-rich-render."""
+
+import sys
+import argparse
+from pathlib import Path
+from tg_rich_render.parser import render_telegram
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Transform Markdown tables into Telegram-optimized rich formats."
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        help="Markdown file to read (reads stdin if omitted)"
+    )
+    parser.add_argument(
+        "--style",
+        choices=["rounded", "classic", "clean", "card", "html"],
+        default="rounded",
+        help="Table rendering style (default: rounded)"
+    )
+    parser.add_argument(
+        "--no-wrap",
+        action="store_true",
+        help="Do not wrap rendered tables in code blocks"
+    )
+
+    args = parser.parse_args()
+
+    if args.file and args.file != "-":
+        content = Path(args.file).read_text(encoding="utf-8")
+    else:
+        content = sys.stdin.read()
+
+    rendered = render_telegram(
+        content,
+        style=args.style,
+        wrap_in_code_block=not args.no_wrap
+    )
+    print(rendered)
+
+if __name__ == "__main__":
+    main()

tg_rich_render-0.1.0/tg_rich_render/parser.py

@@ -0,0 +1,115 @@
+"""Markdown document parser that isolates tables and applies rich Telegram formatting.
+"""
+
+import re
+from typing import Literal, Optional, List
+from tg_rich_render.table import Table
+
+TableStyle = Literal['rounded', 'classic', 'clean', 'card', 'html']
+
+TABLE_LINE_RE = re.compile(r'^\s*\|.*\|\s*$')
+
+def extract_tables_and_text(md_text: str):
+    """Split markdown text into ordinary text blocks and table blocks.
+    
+    Protects existing fenced code blocks from being parsed as tables.
+    """
+    lines = md_text.splitlines()
+    blocks = []
+    
+    in_code_block = False
+    current_text_lines: List[str] = []
+    current_table_lines: List[str] = []
+
+    def flush_text():
+        nonlocal current_text_lines
+        if current_text_lines:
+            blocks.append(('text', '\n'.join(current_text_lines)))
+            current_text_lines = []
+
+    def flush_table():
+        nonlocal current_table_lines
+        if current_table_lines:
+            raw_table = '\n'.join(current_table_lines)
+            t = Table.from_markdown(raw_table)
+            if t:
+                blocks.append(('table', t))
+            else:
+                blocks.append(('text', raw_table))
+            current_table_lines = []
+
+    for line in lines:
+        stripped = line.strip()
+        
+        # Check code fence
+        if stripped.startswith('```'):
+            in_code_block = not in_code_block
+            if current_table_lines:
+                flush_table()
+            current_text_lines.append(line)
+            continue
+
+        if in_code_block:
+            current_text_lines.append(line)
+            continue
+
+        # Check if line looks like a markdown table row
+        if TABLE_LINE_RE.match(stripped):
+            if current_text_lines:
+                flush_text()
+            current_table_lines.append(line)
+        else:
+            if current_table_lines:
+                flush_table()
+            current_text_lines.append(line)
+
+    if current_table_lines:
+        flush_table()
+    if current_text_lines:
+        flush_text()
+
+    return blocks
+
+def render_telegram(
+    md_text: str,
+    style: TableStyle = 'rounded',
+    wrap_in_code_block: bool = True
+) -> str:
+    """Transform markdown text for optimal Telegram display.
+    
+    Parameters:
+        md_text: Input markdown text containing pipe tables.
+        style: Rendering style for tables ('rounded', 'classic', 'clean', 'card', 'html').
+        wrap_in_code_block: Wrap monospace tables in ``` for perfect alignment.
+    """
+    blocks = extract_tables_and_text(md_text)
+    output_parts = []
+
+    for kind, payload in blocks:
+        if kind == 'text':
+            output_parts.append(payload)
+        elif kind == 'table':
+            table: Table = payload
+            if style == 'rounded':
+                rendered = table.render_rounded()
+                if wrap_in_code_block:
+                    rendered = f"```\n{rendered}\n```"
+            elif style == 'classic':
+                rendered = table.render_classic()
+                if wrap_in_code_block:
+                    rendered = f"```\n{rendered}\n```"
+            elif style == 'clean':
+                rendered = table.render_clean()
+                if wrap_in_code_block:
+                    rendered = f"```\n{rendered}\n```"
+            elif style == 'card':
+                rendered = table.render_card()
+            elif style == 'html':
+                rendered = table.render_html()
+            else:
+                rendered = table.render_rounded()
+                if wrap_in_code_block:
+                    rendered = f"```\n{rendered}\n```"
+            output_parts.append(rendered)
+
+    return "\n".join(output_parts)

tg_rich_render-0.1.0/tg_rich_render/table.py

@@ -0,0 +1,165 @@
+"""Markdown Pipe Table Parser and Multi-style Telegram Renderers.
+
+Supports:
+- CJK wide character awareness
+- Column alignment (:---, :---:, ---:)
+- Multiple visual styles: rounded, classic, clean, card, html
+"""
+
+import re
+import html
+from typing import List, Dict, Any, Optional, Literal
+from tg_rich_render.cjk import get_display_width, pad_cjk
+
+Alignment = Literal['left', 'right', 'center']
+
+class Table:
+    """Represents a parsed Markdown table."""
+
+    def __init__(self, headers: List[str], rows: List[List[str]], alignments: Optional[List[Alignment]] = None):
+        self.headers = [h.strip() for h in headers]
+        self.rows = [[cell.strip() for cell in row] for row in rows]
+        
+        col_count = len(self.headers)
+        if not alignments or len(alignments) < col_count:
+            alignments = ['left'] * col_count
+        self.alignments = alignments[:col_count]
+
+        # Calculate max display width per column
+        self.col_widths = [get_display_width(h) for h in self.headers]
+        for row in self.rows:
+            # Pad row if incomplete
+            while len(row) < col_count:
+                row.append('')
+            for idx in range(col_count):
+                cell_w = get_display_width(row[idx])
+                if cell_w > self.col_widths[idx]:
+                    self.col_widths[idx] = cell_w
+
+    @classmethod
+    def from_markdown(cls, table_str: str) -> Optional['Table']:
+        """Parse a markdown pipe table string into a Table instance."""
+        lines = [line.strip() for line in table_str.strip().splitlines() if line.strip()]
+        if len(lines) < 2:
+            return None
+
+        # Clean pipe edges
+        def split_row(line: str) -> List[str]:
+            if line.startswith('|'):
+                line = line[1:]
+            if line.endswith('|'):
+                line = line[:-1]
+            return [cell.strip() for cell in line.split('|')]
+
+        raw_header = split_row(lines[0])
+        separator_line = split_row(lines[1])
+
+        # Validate separator line has dashes
+        alignments: List[Alignment] = []
+        for sep in separator_line:
+            s = sep.strip()
+            if not re.match(r'^:?-+:?$', s):
+                return None  # Invalid markdown table separator
+            if s.startswith(':') and s.endswith(':'):
+                alignments.append('center')
+            elif s.endswith(':'):
+                alignments.append('right')
+            else:
+                alignments.append('left')
+
+        rows: List[List[str]] = []
+        for line in lines[2:]:
+            if '|' in line:
+                rows.append(split_row(line))
+
+        return cls(headers=raw_header, rows=rows, alignments=alignments)
+
+    def render_rounded(self) -> str:
+        """Render using modern Unicode rounded box characters."""
+        widths = self.col_widths
+        
+        # ╭──────┬──────╮
+        top = "╭" + "┬".join("─" * (w + 2) for w in widths) + "╮"
+        # ├──────┼──────┤
+        mid = "├" + "┼".join("─" * (w + 2) for w in widths) + "┤"
+        # ╰──────┴──────╯
+        bot = "╰" + "┴".join("─" * (w + 2) for w in widths) + "╯"
+
+        def fmt_row(cells: List[str]) -> str:
+            padded = []
+            for i, cell in enumerate(cells):
+                w = widths[i]
+                align = self.alignments[i] if i < len(self.alignments) else 'left'
+                padded.append(" " + pad_cjk(cell, w, align=align) + " ")
+            return "│" + "│".join(padded) + "│"
+
+        lines = [top, fmt_row(self.headers), mid]
+        for row in self.rows:
+            lines.append(fmt_row(row))
+        lines.append(bot)
+        return "\n".join(lines)
+
+    def render_classic(self) -> str:
+        """Render using classic ASCII borders."""
+        widths = self.col_widths
+        sep = "+" + "+".join("-" * (w + 2) for w in widths) + "+"
+
+        def fmt_row(cells: List[str]) -> str:
+            padded = []
+            for i, cell in enumerate(cells):
+                w = widths[i]
+                align = self.alignments[i] if i < len(self.alignments) else 'left'
+                padded.append(" " + pad_cjk(cell, w, align=align) + " ")
+            return "|" + "|".join(padded) + "|"
+
+        lines = [sep, fmt_row(self.headers), sep]
+        for row in self.rows:
+            lines.append(fmt_row(row))
+        lines.append(sep)
+        return "\n".join(lines)
+
+    def render_clean(self) -> str:
+        """Render minimalist table without vertical border lines."""
+        widths = self.col_widths
+        header_pad = [pad_cjk(h, widths[i], align=self.alignments[i]) for i, h in enumerate(self.headers)]
+        sep_line = ["─" * widths[i] for i in range(len(widths))]
+        
+        lines = [" ".join(header_pad), " ".join(sep_line)]
+        for row in self.rows:
+            row_pad = []
+            for i, cell in enumerate(row):
+                w = widths[i] if i < len(widths) else len(cell)
+                align = self.alignments[i] if i < len(self.alignments) else 'left'
+                row_pad.append(pad_cjk(cell, w, align=align))
+            lines.append(" ".join(row_pad))
+        return "\n".join(lines)
+
+    def render_card(self) -> str:
+        """Render table as mobile-friendly cards, ideal for narrow screens."""
+        blocks = []
+        for row_idx, row in enumerate(self.rows):
+            title = row[0] if row else f"Item {row_idx + 1}"
+            details = []
+            for col_idx in range(1, len(self.headers)):
+                h = self.headers[col_idx]
+                val = row[col_idx] if col_idx < len(row) else ""
+                if val:
+                    details.append(f"  • {h}: {val}")
+            if details:
+                blocks.append(f"📌 {title}\n" + "\n".join(details))
+            else:
+                blocks.append(f"📌 {title}")
+        return "\n\n".join(blocks)
+
+    def render_html(self) -> str:
+        """Render as Telegram-compatible HTML table or styled blocks."""
+        out = ["<table>"]
+        out.append("  <thead>")
+        out.append("    <tr>" + "".join(f"<th>{html.escape(h)}</th>" for h in self.headers) + "</tr>")
+        out.append("  </thead>")
+        out.append("  <tbody>")
+        for row in self.rows:
+            out.append("    <tr>" + "".join(f"<td>{html.escape(cell)}</td>" for cell in row) + "</tr>")
+        out.append("  </tbody>")
+        out.append("</table>")
+        return "\n".join(out)

tg_rich_render-0.1.0/tg_rich_render.egg-info/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: tg-rich-render
+Version: 0.1.0
+Summary: Lightweight Telegram rich table and format converter with zero-dependency CJK alignment.
+Author-email: shali10 <99240403+shali10@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shali10/tg-rich-render
+Project-URL: Repository, https://github.com/shali10/tg-rich-render
+Project-URL: Issues, https://github.com/shali10/tg-rich-render/issues
+Keywords: telegram,aiogram,telegram-bot,table,markdown,cjk,rich-formatting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tg-rich-render 📊✨
+
+> **Zero-dependency, CJK-aware Markdown table & rich format converter for Telegram bots.**  
+> 专治 Telegram 机器人表格排版错位、中英混排对不齐、手机端横向溢出变难看代码块的痛点。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![CI Status](https://github.com/shali10/tg-rich-render/actions/workflows/ci.yml/badge.svg)](https://github.com/shali10/tg-rich-render/actions)
+
+---
+
+## 💡 为什么需要 tg-rich-render？
+
+Telegram 官方的 MarkdownV2 并不支持标准的 GFM Pipe Table（管道表格）。在日常 Telegram 机器人开发（运维巡检播报、资产统计、行情早报）中，直接发送表格通常会遇到以下问题：
+
+1. **直接报错**：Telegram Bot API 无法解析 `| col | col |` 语法；
+2. **粗暴丢进代码块**：直接用 ```` 包裹，但在中英汉字、Emoji 混排时由于字符显示宽度（CJK 宽度为 2）导致竖线完全错位，排版歪歪扭扭；
+3. **窄屏移动端阅读体验差**：宽表格在手机竖屏下横向拉长折行。
+
+`tg-rich-render` 提供纯 Python 标准库实现的智能 CJK 宽度对齐与多风格自适应渲染，一行代码即可集成到 **aiogram 3**、**python-telegram-bot** 或任何 HTTP 请求中。
+
+---
+
+## ✨ 核心特性
+
+- 🚀 **零外部依赖**：纯 Python 标准库构建（基于 `unicodedata` 模块），即装即用，启动开销 0ms。
+- 📐 **精准 CJK / Emoji 宽度补偿**：完美对齐汉字、日韩文、全角符号与 Emoji 表情，拒绝折线与锯齿。
+- 🎨 **多风格视觉呈现**：
+  - `rounded`：现代优雅圆角框线（`╭───┬───╮`），视觉质感拉满。
+  - `classic`：经典 ASCII 风格（`+---+---+`）。
+  - `clean`：极简流式无竖框风格。
+  - `card`：移动端窄屏优先卡片流（键值对展示，杜绝横向滚动）。
+  - `html`：Telegram 兼容 HTML `<table>` 格式。
+- 🤖 **主流框架开箱即用**：自带 aiogram 3 与 python-telegram-bot 发送适配器。
+- 💻 **CLI 工具支持**：支持管道输入与终端即时预览。
+
+---
+
+## 📦 快速安装
+
+```bash
+pip install tg-rich-render
+```
+
+或直接克隆使用：
+
+```bash
+git clone https://github.com/shali10/tg-rich-render.git
+cd tg-rich-render
+pip install -e .
+```
+
+---
+
+## 🚀 快速上手
+
+### 1. 独立使用（纯 Python）
+
+```python
+from tg_rich_render import render_telegram
+
+raw_markdown = """
+# 节点健康巡检
+
+| 节点 | 状态 | 延迟 |
+|:---|:---:|---:|
+| 香港CN2 🚀 | 正常 | 15ms |
+| 美国洛杉矶 | 良好 | 135ms |
+| 日本东京 ⚡ | 正常 | 48ms |
+
+巡检完成，无异常节点。
+"""
+
+# 渲染为 Telegram 优雅圆角等宽表格
+message = render_telegram(raw_markdown, style="rounded")
+print(message)
+```
+
+**输出效果：**
+
+```
+# 节点健康巡检
+
+```
+╭────────────┬──────┬───────╮
+│ 节点       │ 状态 │  延迟 │
+├────────────┼──────┼───────┤
+│ 香港CN2 🚀 │ 正常 │  15ms │
+│ 美国洛杉矶 │ 良好 │ 135ms │
+│ 日本东京 ⚡ │ 正常 │  48ms │
+╰────────────┴──────┴───────╯
+```
+
+巡检完成，无异常节点。
+```
+
+---
+
+### 2. 结合 aiogram 3
+
+```python
+from aiogram import Bot
+from tg_rich_render import send_smart_message
+
+bot = Bot(token="YOUR_BOT_TOKEN")
+
+# 一行代码自适应格式化并发送
+await send_smart_message(
+    bot=bot,
+    chat_id=12345678,
+    text=raw_markdown,
+    table_style="rounded"
+)
+```
+
+---
+
+### 3. 结合 python-telegram-bot
+
+```python
+from telegram import Bot
+from tg_rich_render import send_smart_message
+
+bot = Bot(token="YOUR_BOT_TOKEN")
+
+await send_smart_message(
+    bot=bot,
+    chat_id=12345678,
+    text=raw_markdown,
+    table_style="rounded"
+)
+```
+
+---
+
+### 4. 命令行（CLI）使用
+
+```bash
+# 转换 Markdown 文件
+tg-rich-render report.md --style rounded
+
+# 从终端管道流式转换
+cat summary.md | tg-rich-render --style card
+```
+
+---
+
+## 🎨 渲染风格展示
+
+| 风格名称 | 预览示意 | 适用场景 |
+|:---|:---|:---|
+| **rounded** (默认) | `╭─┬─╮\n│A│B│\n╰─┴─╯` | PC 端与大屏客户端，视觉质感极高 |
+| **classic** | `+-+-+\n|A|B|\n+-+-+` | 通用等宽终端、标准日志输出 |
+| **clean** | `A  B\n─  ─\n1  2` | 极简通知、紧凑监控通知 |
+| **card** | `📌 节点\n  • 延迟: 15ms` | 移动端窄屏、列数较多的宽表格 |
+| **html** | `<table>...</table>` | Telegram WebApp 或特定富文本容器 |
+
+---
+
+## 🧪 单元测试
+
+项目自带完整的自动化测试集（覆盖 CJK 宽度、对齐算法、长文本解析与适配器）：
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+---
+
+## 📄 开源许可
+
+本项目基于 [MIT License](LICENSE) 开源。

tg_rich_render-0.1.0/tg_rich_render.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_adapter.py
+tests/test_cjk.py
+tests/test_parser.py
+tests/test_table.py
+tg_rich_render/__init__.py
+tg_rich_render/adapter.py
+tg_rich_render/cjk.py
+tg_rich_render/cli.py
+tg_rich_render/parser.py
+tg_rich_render/table.py
+tg_rich_render.egg-info/PKG-INFO
+tg_rich_render.egg-info/SOURCES.txt
+tg_rich_render.egg-info/dependency_links.txt
+tg_rich_render.egg-info/entry_points.txt
+tg_rich_render.egg-info/top_level.txt

tg_rich_render-0.1.0/tg_rich_render.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tg_rich_render-0.1.0/tg_rich_render.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tg-rich-render = tg_rich_render.cli:main

tg_rich_render-0.1.0/tg_rich_render.egg-info/top_level.txt

@@ -0,0 +1 @@
+tg_rich_render