asciimath2mathml

Convert AsciiMath strings to MathML markup.

Overview

asciimath2mathml is a zero-dependency Python library that compiles AsciiMath notation into semantically accurate MathML. It's optimized for fast, stateless, in-memory execution and works in both standard Python environments and browser-based WebAssembly contexts via Pyodide.

Features

• Zero runtime dependencies - Only uses Python's standard library plus Lark parser
• Stateless functional API - No class instantiation required
• WebAssembly compatible - Runs in Pyodide without compiled extensions
• Graceful degradation - Falls back to escaped text on parse errors
• Formal EBNF grammar - Lark-based Earley parser for predictable handling
• Comprehensive coverage - Implements all core mathematical symbols, matrix styles, and delimiters. See COVERAGE_CHECKLIST.md and ROADMAP.md for full specification plans.

Installation

pip install asciimath2mathml

Or for development:

pip install -e ".[dev]"

Usage

from asciimath2mathml import convert

# Inline formula
result = convert("x^2 + y^2 = z^2")
# <math xmlns="http://www.w3.org"><mrow>...</mrow></math>

# Display block (centered, larger)
result = convert("sum_(i=1)^n i^2", display_block=True)
# <math xmlns="http://www.w3.org"><mstyle displaystyle="true">...</mstyle></math>

API Reference

convert(asciimath_string: str, display_block: bool = False) -> str

Compiles an AsciiMath string into valid presentational MathML markup.

Parameters:

• asciimath_string (str): Raw text formula notation input string
• display_block (bool): If True, wraps output in <mstyle displaystyle="true"> for block-level display

Returns:

• str: Validated XML/XHTML string with MathML namespace declarations

Examples

Basic Operations

convert("x + 42")
# <math xmlns="http://www.w3.org"><mrow><mi>x</mi><mo>+</mo><mn>42</mn></mrow></math>

convert("x^2")
# <math xmlns="http://www.w3.org"><msup><mi>x</mi><mn>2</mn></msup></math>

convert("x_1")
# <math xmlns="http://www.w3.org"><msub><mi>x</mi><mn>1</mn></msub></math>

Complex Expressions

convert("(a + b) / (c - d)")
# <math xmlns="http://www.w3.org"><mfrac>...</mfrac></math>

convert("sqrt(x^2 + y^2)")
# <math xmlns="http://www.w3.org"><msqrt>...</msqrt></math>

convert("x_1^2 + y_1^2 = z_1^2")
# <math xmlns="http://www.w3.org"><mrow><msubsup>...</msubsup>...</mrow></math>

Element Mapping

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"   # editable install — required before running tests

Testing

# Unit tests
pytest tests/ --ignore=tests/performance -v

# Performance benchmarks
pytest tests/performance/ -v

Performance

The library targets sub-2.5ms conversion time per formula on standard hardware. See tests/performance/ for benchmark profiles.

License

MIT

Project Structure

asciimath2mathml/
├── src/
│   └── asciimath2mathml/
│       ├── __init__.py      # Public API
│       ├── core.py          # Compiler execution loop
│       ├── grammar.lark     # EBNF grammar definition
│       └── transformer.py   # AST to MathML transformer
└── tests/
    ├── unit/                # Unit tests
    └── performance/         # Performance benchmarks