mathml2docx 0.1.3__tar.gz → 1.0.0__tar.gz

mathml2docx-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Documentation
+
+on:
+  push:
+    branches: [master, develop, compat/python36-uv]
+  pull_request:
+    branches: [master, develop]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.13.7'
+      - run: uv sync --locked --extra latex --extra markdown --group docs --group examples
+      - run: uv run --no-sync python scripts/build_docs.py
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/deploy-pages@v4
+        id: deployment

mathml2docx-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,83 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.13.7'
+      - name: Verify tag version and source on master
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+          RELEASE_EVENT: ${{ github.event_name }}
+        run: |
+          if [ "$RELEASE_EVENT" = push ]; then
+            uv run --no-project --python 3.14 --with 'packaging>=24,<27' python scripts/check_release.py --tag "$RELEASE_TAG"
+          else
+            uv run --no-project --python 3.14 --with 'packaging>=24,<27' python scripts/check_release.py
+          fi
+      - name: Require TestPyPI upload and installation for this exact commit
+        if: github.event_name == 'push'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: uv run --no-project --python 3.14 python scripts/check_testpypi_run.py
+
+  checks:
+    needs: gate
+    uses: ./.github/workflows/python-app.yml
+
+  build:
+    needs: checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.13.7'
+      - run: uv build
+      - run: uv run --no-project --python 3.14 python scripts/check_dist.py
+      - run: uv run --no-project --python 3.14 --with 'twine>=6,<7' twine check dist/*
+      - run: uv run --no-project --python 3.14 python scripts/check_wheel_install.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pypi-distributions
+          overwrite: true
+          path: dist/
+
+  publish:
+    # Creating a GitHub Release does not upload again. Only a validated final tag
+    # can publish; workflow_dispatch validates/builds without uploading.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mathml2docx
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: pypi-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

mathml2docx-1.0.0/.github/workflows/python-app.yml

@@ -0,0 +1,121 @@
+name: Python package
+
+on:
+  push:
+    branches: [develop, compat/python36-uv]
+  pull_request:
+    branches: [master, develop]
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  legacy:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        image: ['python:3.6.15-slim-buster', 'python:3.7.17-slim-bullseye']
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Test legacy source and installed wheel
+        run: bash scripts/test_legacy.sh '${{ matrix.image }}'
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.13.7'
+      - run: uv sync --locked --no-default-groups --python '${{ matrix.python-version }}' --extra latex --extra markdown --extra test
+      - run: .venv/bin/python -m unittest discover -v
+      - run: .venv/bin/python -m pytest -q tests/test_math_audit_regressions.py tests/test_math_html_regressions.py
+      - name: Check utility docstrings through package imports
+        run: |
+          .venv/bin/python - <<'PY'
+          import doctest
+          from mathml2docx import utils
+          result = doctest.testmod(utils, verbose=True)
+          raise SystemExit(bool(result.failed))
+          PY
+
+  platforms:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {os: windows-latest, python-version: '3.8'}
+          - {os: windows-latest, python-version: '3.14'}
+          - {os: macos-15-intel, python-version: '3.14'}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.13.7'
+      - run: uv sync --locked --no-default-groups --python '${{ matrix.python-version }}' --extra latex --extra markdown --extra test
+      - run: uv run --no-sync --no-default-groups --python '${{ matrix.python-version }}' python -m unittest discover -v
+      - run: uv run --no-sync --no-default-groups --python '${{ matrix.python-version }}' python -m pytest -q tests/test_math_audit_regressions.py tests/test_math_html_regressions.py
+
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.13.7'
+      - run: uv sync --locked --all-extras --group docs --group examples
+      - run: uv run --no-sync python -m pytest -q
+      - run: uv run --no-sync python scripts/check_math_mutations.py
+      - run: uv run --no-sync ruff check mathml2docx tests/test_v1.py tests/test_regressions.py tests/test_existing_fixes.py tests/test_extended.py tests/test_examples.py tests/test_math_validation.py tests/test_advanced_documents.py tests/test_math_policies.py tests/test_math_audit_regressions.py tests/test_math_html_regressions.py tests/test_math_template_regressions.py tests/test_math_oracle_regressions.py tests/test_word_comparison_regressions.py tests/test_rendering.py tests/test_docx_oracles.py tests/test_release_metadata.py tests/docx_oracle.py examples scripts
+      - run: uv run --no-sync ruff format --check mathml2docx tests/test_v1.py tests/test_regressions.py tests/test_existing_fixes.py tests/test_extended.py tests/test_examples.py tests/test_math_validation.py tests/test_advanced_documents.py tests/test_math_policies.py tests/test_math_audit_regressions.py tests/test_math_html_regressions.py tests/test_math_template_regressions.py tests/test_math_oracle_regressions.py tests/test_word_comparison_regressions.py tests/test_rendering.py tests/test_docx_oracles.py tests/test_release_metadata.py tests/docx_oracle.py examples scripts
+      - run: uv run --no-sync python scripts/build_docs.py
+      - name: Validate mathematical and document structure against official schemas
+        run: |
+          uv run --no-sync python scripts/prepare_ecma_schema.py "$RUNNER_TEMP/ecma376"
+          uv run --no-sync python scripts/validate_math_schema.py --schemas "$RUNNER_TEMP/ecma376" --docx-dir site/downloads/examples
+      - run: uv build
+      - run: uv run --no-sync python scripts/check_dist.py
+      - run: uv run --no-sync twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package-distributions
+          overwrite: true
+          path: dist/
+
+
+  libreoffice:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.13.7'
+      - name: Install Writer, Math and fonts
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libreoffice-writer libreoffice-math poppler-utils fonts-noto-cjk fonts-stix
+      - run: uv sync --locked --no-default-groups --extra latex --extra markdown --group examples
+      - run: uv run --no-sync python -m examples.run_all
+      - name: Verify formula import and actual PDF math rendering
+        run: uv run --no-sync python scripts/render_examples.py --output examples/output/libreoffice-review
+      - uses: actions/upload-artifact@v4
+        with:
+          name: libreoffice-previews
+          path: examples/output/libreoffice-review/

mathml2docx-1.0.0/.github/workflows/testpypi.yml

@@ -0,0 +1,90 @@
+name: TestPyPI candidate
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: testpypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  checks:
+    if: github.ref == 'refs/heads/master'
+    uses: ./.github/workflows/python-app.yml
+
+  build:
+    needs: checks
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.candidate.outputs.version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.13.7'
+      - name: Assign a unique development version in this checkout only
+        id: candidate
+        env:
+          CANDIDATE_RUN_ID: ${{ github.run_id }}
+          CANDIDATE_ATTEMPT: ${{ github.run_attempt }}
+        run: |
+          uv run --no-project --python 3.14 --with 'packaging>=24,<27' python -m scripts.prepare_testpypi --run-id "$CANDIDATE_RUN_ID" --attempt "$CANDIDATE_ATTEMPT" --output "$GITHUB_OUTPUT"
+          uv lock
+      - run: uv build
+      - run: uv run --no-project --python 3.14 python scripts/check_dist.py
+      - run: uv run --no-project --python 3.14 --with 'twine>=6,<7' twine check dist/*
+      - run: uv run --no-project --python 3.14 python scripts/check_wheel_install.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: testpypi-distributions
+          overwrite: true
+          path: dist/
+      - name: Report candidate version
+        env:
+          CANDIDATE_VERSION: ${{ steps.candidate.outputs.version }}
+        run: echo "TestPyPI candidate version is $CANDIDATE_VERSION" >> "$GITHUB_STEP_SUMMARY"
+
+  upload:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/mathml2docx
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: testpypi-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  install:
+    needs: [build, upload]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.8', '3.14']
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.13.7'
+      - uses: actions/download-artifact@v4
+        with:
+          name: testpypi-distributions
+          path: dist/
+      - name: Install the exact published wheel and test public APIs
+        run: uv run --no-project --python 3.14 python scripts/check_testpypi_install.py --wheel dist/*.whl --python '${{ matrix.python-version }}'

mathml2docx-1.0.0/.python-version

@@ -0,0 +1 @@
+3.14

mathml2docx-1.0.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## 1.0.0 — Unreleased
+
+### Conversion and integration
+
+- Replace the bundled Office XSL with a native Presentation MathML-to-OMML converter.
+- Rework HTML traversal for merged/nested tables, inline assets, lists, links, and static CSS.
+- Add optional LaTeX/Markdown frontends, a CLI, public Word style constants, class mappings,
+  and marker/bookmark replacement in existing documents.
+- Preserve the Python 3.6 core runtime. LaTeX requires Python 3.6.2+ and latex2mathml 3.64+.
+- Preserve adjacent matrix fence groups, complete parenthesized script bases, and
+  prefixed cases on older LaTeX backends. Apply explicit CSS fonts to East Asian
+  and complex-script slots as well as Latin text.
+- Correct fraction types, mathematical alphabets, accents, delimiters, cases tables,
+  limit grouping, per-operator layout directives, inline spacing, and OOXML property order.
+
+- Follow MathML inline defaults, with configurable missing-display layout and CSS precedence.
+- Support selected enclosures and chemical prescripts, and explicit preprocessing, source/image
+  fallback, and LibreOffice compatibility policies. Avoid empty postscript placeholders.
+
+- Honor scoped MathML defaults, compact movable limits, XML whitespace, Unicode input
+  declarations and quoted strings. Validate known arities before unsupported-element recovery.
+- Recover explicitly for unsupported merged/ragged matrices, forced breaks, RTL and complex
+  accents instead of silently changing their meaning. Preserve supported MathML CSS and anchors.
+- Preserve equations around template markers and within bookmark replacement boundaries.
+- Preserve linked display equations and mixed math styles through Word resaving; align
+  native OMML properties with Unicode mathematical alphabets already emitted by LaTeX backends.
+
+### Compatibility changes
+
+- URL images and external stylesheets require explicit loaders; local images are limited
+  to a configured base directory.
+- File conversion adds `.docx` once and returns the output Path.
+- `fix_html` is retained for call compatibility; HTML always uses tree parsing.
+- Style helpers require explicit run/paragraph targets. Unsupported MathML is reported
+  rather than silently dropped. Full browser CSS and complete MathML/LaTeX are not promised.
+
+### Validation and packaging
+
+- Replace MkDocs with a custom Markdown/Jinja static site, responsive navigation, bilingual
+  search and code copying. Rewrite reader-facing guides and remove session status reports.
+- Check independently authored source equation counts before rendering, compare math run
+  styles and explicit display layout, and detect lost internal-link targets.
+- Verify LibreOffice formula import counts and a real PDF math probe; fail when Math is missing.
+  Add a dedicated CI job and explicit Writer/Math/font setup instructions.
+
+- Add text equation inputs and independent JSON answers for inspecting saved DOCX structures.
+- Add 30 runnable examples, schema validation, mixed-document checks, and targeted corruption tests.
+- Provide English-default and Korean READMEs and documentation, with equivalent-page
+  language switching and localized search.
+- Add 18 advanced authored inputs with independent answers and optional Windows
+  Word open/PDF-export/resave checks, with 224 native equations across 30 examples.
+- Exclude XSL and generated DOCX files from new package distributions; retain inherited MIT notices.
+- Manage dependencies with uv and verify legacy/modern Python plus Windows/macOS in CI.
+- Use develop for daily work, master pushes for unique TestPyPI candidates and remote
+  installation checks, and verified final tags for PyPI publishing through OIDC.
+
+Historical XSL redistribution rights and application-specific visual review remain separate concerns.
+See the migration, licensing, validation, and publishing documentation before release.

{mathml2docx-0.1.3 → mathml2docx-1.0.0}/LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
 Copyright (c) 2019 pqzx
-Copyright (c) 2024 joongi007
+Copyright (c) 2024-2026 joongi007
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

mathml2docx-1.0.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: mathml2docx
+Version: 1.0.0
+Summary: Convert HTML, MathML and optional LaTeX/Markdown to Word documents
+Keywords: html,mathml,docx,convert
+Author: joongi007
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: beautifulsoup4>=4.12,<5
+Requires-Dist: python-docx>=0.8.11,<2
+Requires-Dist: lxml>=4.9,<7
+Requires-Dist: tinycss2>=1.1,<2
+Requires-Dist: Pillow>=8.4,<13
+Requires-Dist: cssselect2>=0.4,<1
+Requires-Dist: latex2mathml>=3.64,<4 ; extra == "latex" and ( python_full_version >= '3.6.2')
+Requires-Dist: Markdown>=3.3,<4 ; extra == "markdown"
+Requires-Dist: pytest>=6.2,<10 ; extra == "test"
+Requires-Dist: docxtpl>=0.16,<1 ; extra == "test"
+Requires-Dist: Markdown>=3.3,<4 ; extra == "test"
+Project-URL: Documentation, https://joongi007.github.io/mathml2docx/
+Project-URL: Repository, https://github.com/joongi007/mathml2docx
+Provides-Extra: latex
+Provides-Extra: markdown
+Provides-Extra: test
+
+# mathml2docx
+
+[English](README.md) · [한국어](README.ko.md) · [Documentation](https://joongi007.github.io/mathml2docx/)
+
+Convert HTML and MathML into Word documents with Python. Create reports, worksheets
+and templates with **editable equations**, formatted text, tables and images.
+Microsoft Office is not required to generate a document.
+
+Python 3.6+ · Optional LaTeX and Markdown inputs · MIT license
+
+## Installation
+
+This README describes the 1.0 API. Install the repository version while 1.0 is
+unreleased on PyPI:
+
+```sh
+python -m pip install 'git+https://github.com/joongi007/mathml2docx.git@master'
+# With optional LaTeX and Markdown support:
+python -m pip install 'mathml2docx[latex,markdown] @ git+https://github.com/joongi007/mathml2docx.git@master'
+```
+
+Python 3.6.2+ is required for the optional LaTeX frontend. Library users do not need uv.
+For a reproducible installation, replace `master` with a reviewed commit or release tag.
+
+## Your first Word document
+
+```python
+from mathml2docx import convert
+
+convert('''
+<h1>Lesson notes</h1>
+<p>The value <math><mfrac><mn>1</mn><mn>2</mn></mfrac></math> is one half.</p>
+<math display="block"><msup><mi>x</mi><mn>2</mn></msup></math>
+''', 'lesson.docx')
+```
+
+Open `lesson.docx` in Word to edit its text and equations. `convert()` also returns
+a python-docx `Document`; omit the output path to continue editing it in Python.
+
+## What it supports
+
+| Input or task | Features |
+| --- | --- |
+| HTML | Headings, paragraphs, links, nested lists and text formatting |
+| Tables | Merged cells, nested tables and Word table styles |
+| Images | Data URLs, configured local files and explicit application loaders |
+| CSS | Supported selectors, fonts, colors, alignment and page breaks |
+| MathML | Fractions, roots, scripts, limits, accents, matrices, selected enclosures and isotope scripts |
+| LaTeX / Markdown | Optional frontends using latex2mathml and Python-Markdown |
+| Templates | Add to an existing document or cell; replace markers and bookmarks |
+
+The converter implements a documented subset of HTML, CSS and Presentation MathML.
+It does not reproduce a complete browser layout.
+
+## Equation layout and unsupported input
+
+`<math>` is **inline by default**, following MathML. Use `display="block"` for a
+separate display equation. To retain block behavior for input that omits `display`:
+
+```python
+from mathml2docx import MathmlToDocx
+
+parser = MathmlToDocx(default_math_display='block')
+```
+
+Unsupported mathematical structures raise `UnsupportedMathMLError` by default.
+Applications handling mixed input can select `unsupported_math='text'` to preserve
+the formula's XML visibly, provide `mathml_fallback(source, error)` returning text
+or an image, or normalize input with `mathml_preprocessor(source)`. Recovery emits
+`MathMLFallbackWarning`; invalid XML still raises an error.
+See [equation handling](https://joongi007.github.io/mathml2docx/03-mathematics/)
+for supported notations and complete examples.
+
+## LaTeX, Markdown and command line
+
+```python
+from mathml2docx import MathmlToDocx
+
+parser = MathmlToDocx()
+parser.parse_latex(r'\frac{1}{2} + x_1^2').save('equation.docx')
+parser.parse_markdown('# Notes\n\n**Bold** and ~~removed~~ text.').save('notes.docx')
+```
+
+```sh
+mathml2docx input.html output.docx
+mathml2docx equation.tex equation.docx --format latex
+mathml2docx input.html output.docx --default-math-display block --unsupported-math text
+```
+
+Use `--force` to replace an existing output file. HTML dollar delimiters are not
+interpreted as LaTeX. Network images and stylesheets require explicit loaders.
+
+## Guides and examples
+
+- [Getting started](https://joongi007.github.io/mathml2docx/01-getting-started/) · [API and options](https://joongi007.github.io/mathml2docx/02-api/) · [Recipes](https://joongi007.github.io/mathml2docx/08-recipes/)
+- [Runnable examples and DOCX downloads](https://joongi007.github.io/mathml2docx/examples/00-index/): formatting, templates, scientific reports, chemistry and fallback rendering.
+- [MathML fidelity example](https://joongi007.github.io/mathml2docx/examples/30_mathml_fidelity/): inherited defaults, accents, equation styles, links and template replacement.
+- [Migration from 0.x](https://joongi007.github.io/mathml2docx/05-migration/) · [Compatibility and validation](https://joongi007.github.io/mathml2docx/11-validation/)
+- [한국어 문서](https://joongi007.github.io/mathml2docx/ko/)
+
+For headless PDF conversion with LibreOffice, install **Writer and Math**, plus
+appropriate fonts. Writer-only installations can leave equations blank. The
+[rendering guide](https://joongi007.github.io/mathml2docx/11-validation/#libreoffice)
+includes installation and verification commands. Use `math_target='libreoffice'`
+with an explicit fallback for known enclosure differences.
+
+## Contributing and license
+
+Work from `develop`; see [development and releases](https://joongi007.github.io/mathml2docx/09-development-release/)
+for setup, tests and publishing. Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+[MIT](LICENSE), derived from [html2docx](https://github.com/pqzx/html2docx).
+Dependencies retain their own licenses; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+The 1.0 converter constructs OMML directly and includes no Office XSL. Historical
+0.x distributions are covered separately in the [provenance record](https://joongi007.github.io/mathml2docx/06-xsl-provenance/).
+