omni-mdx

The high-performance MDX engine for Python, powered by a native Rust core.

pip install omni-mdx

Contents

• What is this?
• When should I use this?
• Install
• Use
  • 1. Parsing to AST
  • 2. Web Rendering (HTML)
  • 3. Native Desktop Rendering (PyQt5)
• API
• Architecture
• Compatibility
• Security
• Contribute
• License

What is this?

omni-mdx provides a high-performance bridge between the pulldown-cmark Rust parser and native Python applications. It parses MDX (Markdown + JSX) into a deeply manipulable Abstract Syntax Tree (AST) and offers zero-dependency native rendering solutions for both the Web (HTML/KaTeX) and Desktop (PyQt5/Matplotlib).

When should I use this?

• Extreme Performance: You need to parse large amounts of MDX content without blocking the Python GIL, thanks to the native Rust core.
• Data Mining & AI: You want to extract structured data (formulas, metadata, components) from MDX for LLM ingestion or indexing.
• Native Desktop Apps: You are building a PyQt5 or PySide application and need to render rich Markdown and Math equations without the overhead of a heavy WebEngine/Chromium component.
• Scientific Publishing: You need robust, built-in support for GFM Tables and KaTeX/LaTeX math.

Install

The package is distributed as a Fat Wheel, meaning the Rust binary is bundled directly. No Rust toolchain is required for installation.

pip install omni-mdx

# Optional: Required for high-quality Desktop math rendering
pip install matplotlib PyQt5

Use

1. Parsing to AST

Transform raw text into a structured, searchable tree.

import omni_mdx

mdx_content = r"""
# Physics 101
The kinetic energy is defined as:
$$\zeta(s) = \sum_{n=1}^\infty \frac{1}{n^s}$$

<Note type="warning">Check your units!</Note>
"""

# Parse returns an MdxAstRoot object
ast = omni_mdx.parse(mdx_content)

# Nodes are accessible via ast.nodes
for node in ast.nodes:
    if node.node_type == "BlockMath":
        print(f"Formula found: {node.attributes.get('data-math')}")

2. Web Rendering (HTML)

Generate clean, standards-compliant HTML.

from omni_mdx import render_html, parse

nodes = parse("<Speaker name='Leon'>Welcome to the show.</Speaker>").nodes

# Register custom rendering logic for JSX components
def render_speaker(node, ctx):
    name = node.attributes.get("name")
    return f'<div class="speaker-tag"><b>{name}:</b> {node.text_content()}</div>'

html_output = render_html(nodes, components={"Speaker": render_speaker})

3. Native Desktop Rendering (PyQt5)

Render MDX content directly into native Qt Widgets.

from PyQt5.QtWidgets import QScrollArea
from omni_mdx.qt_renderer import QtRenderer
import omni_mdx

# 1. Parse and render
nodes = omni_mdx.parse("# Hello Native!").nodes
renderer = QtRenderer()
content_widget = renderer.render(nodes)

# 2. Add to your UI
scroll = QScrollArea()
scroll.setWidget(content_widget)
scroll.setWidgetResizable(True)

API

omni_mdx.parse(source: str) -> MdxAstRoot

Parses the MDX source string into an AST root.

• Returns: An MdxAstRoot containing a list of MdxNode objects.

MdxNode Properties

• node_type: The type of the node (e.g., "h1", "text", "BlockMath").
• content: The raw content of the node.
• attributes: A dictionary of JSX props or math metadata.
• children: A list of child MdxNode objects.
• is_component: Boolean indicating if the node is a JSX component.

Architecture

Omni-MDX utilizes a "Bridge" architecture. The heavy parsing is performed in Rust, producing a high-performance tree. This tree is then wrapped in a Python layer that provides a familiar, typed API for manipulation and rendering.

Compatibility

• Python: 3.11+.
• Operating Systems: Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), Windows (x86_64).
• GUI Frameworks: Optimized for PyQt5 but compatible with any logic that can ingest the AST.

Security

The Rust core provides a safety layer against common regex-based DoS attacks found in many pure-Python parsers. For HTML rendering, ensure your custom components properly sanitize any raw user input if necessary.

Contribute

This package is part of the TOAQ open-source ecosystem. Current Status:

• Python Layer Coverage: 88.10%.
• Core Rust Coverage: 81.29%.

See the Contribution Guide to get started with local development and maturin.

License

MIT © TOAQ-oss