PyKaTeX 0.0.2

A Python wrapper for the [KaTeX](https://katex.org/) library, providing fast server-side rendering of mathematical expressions.

PyKaTeX

A Python wrapper for the KaTeX library, providing fast server-side rendering of mathematical expressions.

PyKaTeX uses a C extension module with QuickJS-NG to enable Python to call into KaTeX, which is written in Javascript. The current version of PyKaTeX uses KaTeX v0.16.22 and QuickJS-NG v0.10.1.

⚠️ PyKaTex is currently in alpha. Some options are only partially supported (see the "usage" section for more information) and KaTeX exceptions are not handled gracefully yet.

Installation

pip install pykatex

Or, to install from source, clone the repository and run

pip install .

in the root of this repository.

Usage

PyKaTeX provides a single function renderToString that takes a LaTeX string and optional keyword arguments:

pykatex.renderToString(input, **options)

It can be used as follows.

import pykatex as katex

# Basic usage
html = katex.renderToString("E = mc^2", output="html")
print(html)

In PyKaTex, the options are passed to renderToString as optional keyword arguments that are mostly compatible with the KaTeX options, with the following exceptions:

• The macros option is not yet implemented
• Currently only string and boolean values are supported for the strict option (functions are not supported)

Note that you'll need to include KaTeX CSS in your HTML for proper rendering when using HTML output.

Options

Output Options

• output (str): Output format. Options:

  • "html" (default): HTML with CSS classes
  • "mathml": MathML markup
  • "htmlAndMathml": Both HTML and MathML

  You can also use the provided constants:

  import pykatex
  html = pykatex.renderToString("x^2", output=pykatex.OUTPUT_HTML)
  mathml = pykatex.renderToString("x^2", output=pykatex.OUTPUT_MATHML)
  both = pykatex.renderToString("x^2", output=pykatex.OUTPUT_HTMLANDMATHML)
  

Display Options

• displayMode (bool): Render in display mode (centered, larger). Default: False
• leqno (bool): Place equation numbers on the left. Default: False
• fleqn (bool): Left-align equations in display mode. Default: False

Error Handling

• throwOnError (bool): Throw an exception on parsing errors. Default: True
• errorColor (str): Color for error messages. Default: "#cc0000"

Styling

• minRuleThickness (float): Minimum thickness of rules/lines
• colorIsTextColor (bool): Use text color for styling. Default: False
• maxSize (float): Maximum allowed size multiplier
• maxExpand (float): Maximum number of macro expansions

Security & Behavior

• strict (str or bool): Error reporting level:
  • "warn": Log warnings for unrecognized commands
  • "error": Throw errors for unrecognized commands
  • "ignore": Silently ignore unrecognized commands
  • True: Same as "error"
  • False: Same as "ignore"
• trust (bool): Allow potentially unsafe commands. Default: False
• globalGroup (bool): Place definitions in global scope. Default: False

Architecture

PyKaTeX consists of:

• A Python C extension module (pykatex.c) that provides the Python interface
• QuickJS JavaScript engine (src/quickjs/) for executing KaTeX
• A wrapper script (katex.js) that calls into the KaTeX library (src/katex/)
• QuickJS bytecode (katex.bytecode.h) for the wrapper script, generated by the QuickJS-NG compiler qjs
• C wrapper code (katex.c) that bridges Python and JavaScript

The katex.bytecode.h file is generated by running

quickjs/build/qjsc -e -N katex -o katex.bytecode.h katex.js

in the src/ folder, and manually remove the JS_NewCustomContext and main functions. This needs to be done again when the wrapper script or KaTeX library is changed (for example, when KaTeX is updated to a new version).

License

This project bundles KaTeX and QuickJS-NG. Please refer to their respective licenses for terms and conditions.