siwei-pymath 1.0.0

LaTeX to SVG/MathML converter using Python + mini-racer + MathJax 3.2.2

siwei-pymath

LaTeX to SVG/MathML converter powered by Python + mini-racer + MathJax 3.2.2.

安装

pip install siwei-pymath

快速使用

from latex.converter import latex_to_svg, latex_to_mathml

# LaTeX → SVG
svg = latex_to_svg(r"E = mc^2")
print(svg)

# LaTeX → MathML
mathml = latex_to_mathml(r"\int_a^b f(x)\,dx", display=True)
print(mathml)

环境要求

• Python >= 3.8
• mini-racer（pip 安装时会自动安装）

---

开发指南

项目结构

siwei-pymath/
├── latex/
│   ├── __init__.py
│   ├── converter.py          ← Python 核心代码
│   └── build/
│       ├── mathjax_entry.js  ← JS 入口（MathJax 配置）
│       └── mathjax_bundle.js ← JS 构建产物（2.5MB，由 esbuild 打包）
├── node_modules/             ← JS 依赖（本地构建用，不参与打包）
├── .gitignore
├── LICENSE
├── README.md
├── pyproject.toml            ← Python 打包配置
├── package.json              ← Node.js 构建配置
├── requirements.txt
└── test_converter.py

本地开发流程

1. 克隆仓库并安装依赖

git clone <仓库地址>
cd siwei-pymath

# Python 依赖
pip install -r requirements.txt

# Node.js 依赖（用于构建 MathJax bundle）
npm install

2. 修改 Python 代码 — 编辑 latex/converter.py 或 latex/__init__.py

3. 修改 MathJax 配置 — 编辑 latex/build/mathjax_entry.js，然后重新构建 bundle：

npx esbuild latex/build/mathjax_entry.js --bundle --outfile=latex/build/mathjax_bundle.js --platform=node --target=es2017

4. 本地测试

python test_converter.py
# 或在 Python 中交互测试
python -c "from latex.converter import latex_to_svg; print(latex_to_svg('E=mc^2')[:200])"

---

打包与发布（上传到 PyPI）

准备工作

1. 注册 PyPI 账号

   • 测试环境：https://test.pypi.org/account/register/
   • 正式环境：https://pypi.org/account/register/
   • 注册后创建 API token（用于命令行上传）

2. 安装打包工具

pip install build twine

构建分发包

# 确保 JS bundle 已构建
npx esbuild latex/build/mathjax_entry.js --bundle --outfile=latex/build/mathjax_bundle.js --platform=node --target=es2017

# 构建 sdist + wheel
python -m build

构建成功后，dist/ 目录下会生成：

• siwei_pymath-1.0.0.tar.gz（源码包）
• siwei_pymath-1.0.0-py3-none-any.whl（wheel 包）

验证一下：检查 wheel 中是否包含了 JS bundle：

python -c "import zipfile; z=zipfile.ZipFile('dist/siwei_pymath-1.0.0-py3-none-any.whl'); print([n for n in z.namelist() if 'mathjax' in n])"

上传到 TestPyPI（推荐先测试）

twine upload --repository-url https://test.pypi.org/legacy/ dist/*

从 TestPyPI 安装验证

pip install --index-url https://test.pypi.org/simple/ siwei-pymath
python -c "from latex.converter import latex_to_svg; print(latex_to_svg('E=mc^2')[:80])"

上传到正式 PyPI

确认测试无误后：

twine upload dist/*

版本更新

修改代码后，按以下步骤更新版本：

1. 更新版本号 — 修改 pyproject.toml 中的 version
2. 重新构建

# 清理旧的构建产物
rm -rf dist *.egg-info

# 重新构建
python -m build

# 上传
twine upload dist/*

注意：每次上传到 PyPI 时版本号必须递增，不能重复使用已有版本号。

常见问题

问题	解决
twine upload 要求输入用户名密码	使用 API token：用户名填 __token__，密码填 token 值
mathjax_bundle.js 没被打包进 wheel	确认 pyproject.toml 中有 [tool.setuptools.package-data] 配置
上传后 pip 安装报 mini-racer 错误	确保系统已安装 C 编译工具链，或使用预编译 wheel