wechat-formatter 1.0.0__tar.gz

wechat_formatter-1.0.0/LICENSE

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

wechat_formatter-1.0.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: wechat-formatter
+Version: 1.0.0
+Summary: Render Markdown into inline-styled HTML for WeChat Official Account (公众号) articles, with 6 visual themes × 12 colors.
+Author: wechat-formatter contributors
+License: MIT
+Project-URL: Homepage, https://github.com/your-org/wechat-formatter
+Project-URL: Repository, https://github.com/your-org/wechat-formatter
+Keywords: wechat,markdown,公众号,wechat-mp,html,formatter,mistune
+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 :: Text Processing :: Markup :: HTML
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mistune<4.0,>=3.0
+Dynamic: license-file
+
+# wechat-formatter
+
+把 Markdown 渲染成**内联样式 HTML**，可直接复制粘贴到微信公众号编辑器。
+
+基于 [`mistune`](https://github.com/lepture/mistune)，内置 **6 种视觉风格 × 12 种配色 = 72 套模板**，所有 CSS 都写在 `style="..."` 内联属性里，不依赖任何外部 CSS 文件或 JS。
+
+## 安装
+
+```bash
+pip install wechat-formatter
+```
+
+或从源码安装：
+
+```bash
+cd wechat-formatter
+pip install .
+```
+
+## 快速开始
+
+```python
+from wechat_formatter import get_template, render_article, FormatTweaks
+
+markdown_text = """\
+# 你好，公众号
+
+这是一段**普通文字**，包含 ==高亮== 内容和 ^上标^、~下标~。
+
+## 一个小标题
+
+- 列表项一
+- 列表项二
+- ~~删除线~~
+
+> 这是一段引用
+
+```python
+print("hello")
+```
+"""
+
+# 按中文风格名 + 颜色名选择模板
+template = get_template("极简风", "经典")
+
+# 可选：覆盖字号、行高、边距等
+tweaks = FormatTweaks(
+    fontSize=15,
+    lineHeight=1.75,
+    paragraphSpacing=16,
+)
+
+html = render_article(markdown_text, template, tweaks)
+
+# 把 html 写入文件，用浏览器打开后全选复制，粘贴到公众号编辑器
+with open("article.html", "w", encoding="utf-8") as f:
+    f.write(html)
+```
+
+## 模板选择
+
+`get_template(category, color)` 接受中文风格名或英文 id：
+
+| 风格中文名 | 英文 id |
+|---|---|
+| 新粗野风 | `neo-brutalism` |
+| 极简风 | `minimalist` |
+| 商务风 | `business` |
+| 文艺风 | `literary` |
+| 科技风 | `tech` |
+| 节庆风 | `festive` |
+
+颜色名（12 种）：`经典`、`雅致`、`先锋`、`深邃`、`晨光`、`星穹`、`暖阳`、`暮色`、`清泉`、`破晓`、`璀璨`、`幽蓝`。
+
+也可以遍历全部模板：
+
+```python
+from wechat_formatter import all_templates, grouped_templates
+
+for tpl in all_templates:
+    print(tpl.category, tpl.name, tpl.themeColor)
+
+# 按风格分组
+for group in grouped_templates:
+    print(group["name"], len(group["templates"]))
+```
+
+## FormatTweaks 参数
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `themeColor` | `str \| None` | `None` | 覆盖模板主题色（hex） |
+| `fontSize` | `int` | `15` | 正文字号 px |
+| `lineHeight` | `float` | `1.75` | 行高 |
+| `paragraphSpacing` | `int` | `16` | 段间距 px |
+| `firstLineIndent` | `bool` | `False` | 首行缩进 2em |
+| `letterSpacing` | `float` | `0.5` | 字间距 px |
+| `imageRadius` | `int` | `4` | 图片圆角 px |
+| `h1Layout` | `str \| None` | `None` | 一级标题对齐：`left`/`center`/`right` |
+| `h2Layout` | `str \| None` | `None` | 二级标题对齐 |
+| `pagePaddingTop` | `int` | `20` | 页面上边距 px |
+| `pagePaddingRight` | `int` | `20` | 页面右边距 px |
+| `pagePaddingBottom` | `int` | `20` | 页面下边距 px |
+| `pagePaddingLeft` | `int` | `20` | 页面左边距 px |
+
+## 支持的 Markdown 语法
+
+- 标准：标题 `#`/`##`/`###`、段落、**加粗**、*斜体*、`行内代码`、链接、图片、引用、有序/无序列表、分割线 `---`、表格
+- 扩展：
+  - `==高亮==` → `<mark>`
+  - `^上标^` → `<sup>`
+  - `~下标~` → `<sub>`
+  - `~~删除线~~` → `<del>`
+  - 任务列表（`- [x]` / `- [ ]`）
+  - 代码块带 macOS 风格圆点头部
+  - 段落中多图自动排成一行
+
+## API 一览
+
+```python
+from wechat_formatter import (
+    # 渲染
+    render_article,
+    # 模板
+    all_templates,        # list[TemplateConfig]
+    grouped_templates,    # list[dict]，按风格分组
+    get_template,         # (category, color) -> TemplateConfig
+    build_template,       # 自定义构建
+    get_styles_by_category,
+    # 类型
+    TemplateConfig,
+    FormatTweaks,
+    BaseStyle,
+    # 颜色
+    color_palettes,
+    categories_list,
+    names,
+    hex_to_rgb,
+    hex_to_rgba,
+    # 工具
+    get_style_value,
+    ensure_style_value,
+    bg_fallback,
+)
+```
+
+## License
+
+MIT

wechat_formatter-1.0.0/README.md

@@ -0,0 +1,149 @@
+# wechat-formatter
+
+把 Markdown 渲染成**内联样式 HTML**，可直接复制粘贴到微信公众号编辑器。
+
+基于 [`mistune`](https://github.com/lepture/mistune)，内置 **6 种视觉风格 × 12 种配色 = 72 套模板**，所有 CSS 都写在 `style="..."` 内联属性里，不依赖任何外部 CSS 文件或 JS。
+
+## 安装
+
+```bash
+pip install wechat-formatter
+```
+
+或从源码安装：
+
+```bash
+cd wechat-formatter
+pip install .
+```
+
+## 快速开始
+
+```python
+from wechat_formatter import get_template, render_article, FormatTweaks
+
+markdown_text = """\
+# 你好，公众号
+
+这是一段**普通文字**，包含 ==高亮== 内容和 ^上标^、~下标~。
+
+## 一个小标题
+
+- 列表项一
+- 列表项二
+- ~~删除线~~
+
+> 这是一段引用
+
+```python
+print("hello")
+```
+"""
+
+# 按中文风格名 + 颜色名选择模板
+template = get_template("极简风", "经典")
+
+# 可选：覆盖字号、行高、边距等
+tweaks = FormatTweaks(
+    fontSize=15,
+    lineHeight=1.75,
+    paragraphSpacing=16,
+)
+
+html = render_article(markdown_text, template, tweaks)
+
+# 把 html 写入文件，用浏览器打开后全选复制，粘贴到公众号编辑器
+with open("article.html", "w", encoding="utf-8") as f:
+    f.write(html)
+```
+
+## 模板选择
+
+`get_template(category, color)` 接受中文风格名或英文 id：
+
+| 风格中文名 | 英文 id |
+|---|---|
+| 新粗野风 | `neo-brutalism` |
+| 极简风 | `minimalist` |
+| 商务风 | `business` |
+| 文艺风 | `literary` |
+| 科技风 | `tech` |
+| 节庆风 | `festive` |
+
+颜色名（12 种）：`经典`、`雅致`、`先锋`、`深邃`、`晨光`、`星穹`、`暖阳`、`暮色`、`清泉`、`破晓`、`璀璨`、`幽蓝`。
+
+也可以遍历全部模板：
+
+```python
+from wechat_formatter import all_templates, grouped_templates
+
+for tpl in all_templates:
+    print(tpl.category, tpl.name, tpl.themeColor)
+
+# 按风格分组
+for group in grouped_templates:
+    print(group["name"], len(group["templates"]))
+```
+
+## FormatTweaks 参数
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `themeColor` | `str \| None` | `None` | 覆盖模板主题色（hex） |
+| `fontSize` | `int` | `15` | 正文字号 px |
+| `lineHeight` | `float` | `1.75` | 行高 |
+| `paragraphSpacing` | `int` | `16` | 段间距 px |
+| `firstLineIndent` | `bool` | `False` | 首行缩进 2em |
+| `letterSpacing` | `float` | `0.5` | 字间距 px |
+| `imageRadius` | `int` | `4` | 图片圆角 px |
+| `h1Layout` | `str \| None` | `None` | 一级标题对齐：`left`/`center`/`right` |
+| `h2Layout` | `str \| None` | `None` | 二级标题对齐 |
+| `pagePaddingTop` | `int` | `20` | 页面上边距 px |
+| `pagePaddingRight` | `int` | `20` | 页面右边距 px |
+| `pagePaddingBottom` | `int` | `20` | 页面下边距 px |
+| `pagePaddingLeft` | `int` | `20` | 页面左边距 px |
+
+## 支持的 Markdown 语法
+
+- 标准：标题 `#`/`##`/`###`、段落、**加粗**、*斜体*、`行内代码`、链接、图片、引用、有序/无序列表、分割线 `---`、表格
+- 扩展：
+  - `==高亮==` → `<mark>`
+  - `^上标^` → `<sup>`
+  - `~下标~` → `<sub>`
+  - `~~删除线~~` → `<del>`
+  - 任务列表（`- [x]` / `- [ ]`）
+  - 代码块带 macOS 风格圆点头部
+  - 段落中多图自动排成一行
+
+## API 一览
+
+```python
+from wechat_formatter import (
+    # 渲染
+    render_article,
+    # 模板
+    all_templates,        # list[TemplateConfig]
+    grouped_templates,    # list[dict]，按风格分组
+    get_template,         # (category, color) -> TemplateConfig
+    build_template,       # 自定义构建
+    get_styles_by_category,
+    # 类型
+    TemplateConfig,
+    FormatTweaks,
+    BaseStyle,
+    # 颜色
+    color_palettes,
+    categories_list,
+    names,
+    hex_to_rgb,
+    hex_to_rgba,
+    # 工具
+    get_style_value,
+    ensure_style_value,
+    bg_fallback,
+)
+```
+
+## License
+
+MIT

wechat_formatter-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wechat-formatter"
+version = "1.0.0"
+description = "Render Markdown into inline-styled HTML for WeChat Official Account (公众号) articles, with 6 visual themes × 12 colors."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "wechat-formatter contributors" },
+]
+keywords = ["wechat", "markdown", "公众号", "wechat-mp", "html", "formatter", "mistune"]
+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 :: Text Processing :: Markup :: HTML",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mistune>=3.0,<4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/your-org/wechat-formatter"
+Repository = "https://github.com/your-org/wechat-formatter"
+
+[tool.setuptools]
+packages = ["wechat_formatter"]
+
+[tool.setuptools.package-data]
+wechat_formatter = ["py.typed"]

wechat_formatter-1.0.0/setup.cfg

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

wechat_formatter-1.0.0/tests/test_basic.py

@@ -0,0 +1,97 @@
+"""Basic smoke tests for wechat_formatter."""
+
+from wechat_formatter import (
+    FormatTweaks,
+    TemplateConfig,
+    all_templates,
+    categories_list,
+    get_template,
+    grouped_templates,
+    hex_to_rgba,
+    names,
+    render_article,
+)
+
+
+def test_template_catalogue_size():
+    # 6 categories × 12 colors = 72
+    assert len(all_templates) == 72
+    assert len(categories_list) == 6
+    assert len(names) == 12
+
+
+def test_grouped_templates():
+    assert len(grouped_templates) == 6
+    for group in grouped_templates:
+        assert len(group["templates"]) == 12
+
+
+def test_get_template_by_chinese_name():
+    tpl = get_template("极简风", "经典")
+    assert isinstance(tpl, TemplateConfig)
+    assert tpl.category == "minimalist"
+    assert tpl.name == "经典"
+
+
+def test_get_template_by_english_id():
+    tpl = get_template("tech", "晨光")
+    assert tpl.category == "tech"
+    assert tpl.name == "晨光"
+
+
+def test_get_template_unknown_category():
+    import pytest
+
+    with pytest.raises(ValueError):
+        get_template("不存在的风格", "经典")
+
+
+def test_hex_to_rgba():
+    assert hex_to_rgba("#ff0000", 0.5) == "rgba(255, 0, 0, 0.5)"
+    assert hex_to_rgba("#f00", 1.0) == "rgba(255, 0, 0, 1)"
+    # alpha clamped
+    assert hex_to_rgba("#000", 5.0) == "rgba(0, 0, 0, 1)"
+    assert hex_to_rgba("#000", -1.0) == "rgba(0, 0, 0, 0)"
+
+
+def test_render_article_basic():
+    tpl = get_template("极简风", "经典")
+    html = render_article("# Hello\n\n正文内容", tpl, FormatTweaks())
+    assert "<section" in html
+    assert "Hello" in html
+    assert "正文内容" in html
+
+
+def test_render_extra_syntax():
+    tpl = get_template("商务风", "经典")
+    md = "==高亮== 普通 ^上标^ ~下标~ ~~删除~~"
+    html = render_article(md, tpl, FormatTweaks())
+    assert "<mark" in html
+    assert "<sup>" in html
+    assert "<sub>" in html
+    assert "<del" in html
+
+
+def test_render_task_list():
+    tpl = get_template("科技风", "经典")
+    md = "- [x] 已完成\n- [ ] 未完成"
+    html = render_article(md, tpl, FormatTweaks())
+    assert "已完成" in html
+    assert "未完成" in html
+
+
+def test_render_code_block():
+    tpl = get_template("极简风", "经典")
+    md = '```python\nprint("hi")\n```'
+    html = render_article(md, tpl, FormatTweaks())
+    assert "print" in html
+    # code block should be wrapped in pre
+    assert "<pre" in html
+
+
+def test_theme_color_override():
+    tpl = get_template("极简风", "经典")
+    tweaks = FormatTweaks(themeColor="#ff0000")
+    # A heading uses themeColor in its style (color: {color}).
+    html = render_article("# 标题", tpl, tweaks)
+    assert "#ff0000" in html

wechat_formatter-1.0.0/wechat_formatter/__init__.py

@@ -0,0 +1,65 @@
+"""wechat_formatter — Markdown → WeChat Official Account styled HTML.
+
+A Markdown article template engine that renders Markdown into inline-styled
+HTML suitable for pasting into the WeChat Official Account (公众号) editor.
+Six visual categories × twelve color themes = 72 ready-to-use templates.
+
+Public API::
+
+    from wechat_formatter import (
+        all_templates,
+        grouped_templates,
+        get_template,
+        render_article,
+        TemplateConfig,
+        FormatTweaks,
+    )
+
+    # Pick by Chinese style name + color name:
+    tpl = get_template("极简风", "经典")
+    html = render_article("# Hello", tpl, FormatTweaks())
+"""
+
+from __future__ import annotations
+
+from .colors import (
+    categories_list,
+    color_palettes,
+    hex_to_rgb,
+    hex_to_rgba,
+    names,
+)
+from .renderer import render_article
+from .style_utils import bg_fallback, ensure_style_value, get_style_value
+from .templates import (
+    all_templates,
+    build_template,
+    generate_templates,
+    get_styles_by_category,
+    get_template,
+    grouped_templates,
+)
+from .types import BaseStyle, FormatTweaks, TemplateConfig
+
+__all__ = [
+    "BaseStyle",
+    "FormatTweaks",
+    "TemplateConfig",
+    "all_templates",
+    "build_template",
+    "categories_list",
+    "color_palettes",
+    "generate_templates",
+    "get_styles_by_category",
+    "get_template",
+    "grouped_templates",
+    "hex_to_rgb",
+    "hex_to_rgba",
+    "names",
+    "render_article",
+    "bg_fallback",
+    "ensure_style_value",
+    "get_style_value",
+]
+
+__version__ = "1.0.0"

wechat_formatter-1.0.0/wechat_formatter/colors.py

@@ -0,0 +1,150 @@
+"""Color palettes, template names, and hex/ rgba helpers.
+
+Translated from the top-level constants and helpers in the TypeScript source.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Tuple
+
+# ---------------------------------------------------------------------------
+# Palettes / names / categories
+# ---------------------------------------------------------------------------
+
+color_palettes: Dict[str, List[str]] = {
+    "neoBrutalism": [
+        "#ff6f9f",
+        "#3b82f6",
+        "#10b981",
+        "#f59e0b",
+        "#8b5cf6",
+        "#ef4444",
+        "#06b6d4",
+        "#f43f5e",
+        "#14b8a6",
+        "#f97316",
+        "#d946ef",
+        "#84cc16",
+    ],
+    "minimalist": [
+        "#3b82f6",
+        "#10b981",
+        "#6366f1",
+        "#f59e0b",
+        "#ef4444",
+        "#8b5cf6",
+        "#14b8a6",
+        "#f43f5e",
+        "#64748b",
+        "#000000",
+        "#2dd4bf",
+        "#fb923c",
+    ],
+    "business": [
+        "#1e40af",
+        "#0f766e",
+        "#4338ca",
+        "#b45309",
+        "#be123c",
+        "#6d28d9",
+        "#0e7490",
+        "#9f1239",
+        "#334155",
+        "#111827",
+        "#1d4ed8",
+        "#047857",
+    ],
+    "literary": [
+        "#059669",
+        "#d97706",
+        "#be185d",
+        "#7c3aed",
+        "#0284c7",
+        "#ea580c",
+        "#4d7c0f",
+        "#c026d3",
+        "#0891b2",
+        "#86198f",
+        "#db2777",
+        "#7c2d12",
+    ],
+    "tech": [
+        "#2563eb",
+        "#0ea5e9",
+        "#06b6d4",
+        "#10b981",
+        "#8b5cf6",
+        "#a855f7",
+        "#d946ef",
+        "#f43f5e",
+        "#6366f1",
+        "#14b8a6",
+        "#f97316",
+        "#84cc16",
+    ],
+    "festive": [
+        "#ef4444",
+        "#dc2626",
+        "#b91c1c",
+        "#f59e0b",
+        "#d97706",
+        "#ea580c",
+        "#c2410c",
+        "#be123c",
+        "#9f1239",
+        "#fbbf24",
+        "#e11d48",
+        "#ca8a04",
+    ],
+}
+
+names: List[str] = [
+    "经典",
+    "雅致",
+    "先锋",
+    "深邃",
+    "晨光",
+    "星穹",
+    "暖阳",
+    "暮色",
+    "清泉",
+    "破晓",
+    "璀璨",
+    "幽蓝",
+]
+
+categories_list: List[Dict[str, str]] = [
+    {"id": "neo-brutalism", "name": "新粗野风"},
+    {"id": "minimalist", "name": "极简风"},
+    {"id": "business", "name": "商务风"},
+    {"id": "literary", "name": "文艺风"},
+    {"id": "tech", "name": "科技风"},
+    {"id": "festive", "name": "节庆风"},
+]
+
+
+# ---------------------------------------------------------------------------
+# Color helpers
+# ---------------------------------------------------------------------------
+
+
+def hex_to_rgb(hex_color: str) -> Tuple[int, int, int]:
+    """Convert a ``#rrggbb`` or ``#rgb`` hex string to an ``(r, g, b)`` tuple."""
+    normalized = hex_color.replace("#", "").strip()
+    if len(normalized) == 3:
+        normalized = "".join(ch + ch for ch in normalized)
+    value = int(normalized, 16)
+    r = (value >> 16) & 255
+    g = (value >> 8) & 255
+    b = value & 255
+    return r, g, b
+
+
+def hex_to_rgba(hex_color: str, alpha: float) -> str:
+    """Convert a hex color + alpha into a CSS ``rgba(...)`` string."""
+    r, g, b = hex_to_rgb(hex_color)
+    # Mirror the TS rounding: Number(alpha.toFixed(3)) then clamped to [0, 1].
+    # ``:g`` drops trailing zeros so 0.0 renders as "0" and 1.0 as "1", exactly
+    # like JS's Number-to-string coercion.
+    safe_alpha = max(0.0, min(1.0, round(float(alpha), 3)))
+    return f"rgba({r}, {g}, {b}, {safe_alpha:g})"