Metadata-Version: 2.1
Name: pykatex
Version: 0.0.2
Summary: A Python wrapper for the [KaTeX](https://katex.org/) library, providing fast server-side rendering of mathematical expressions.
Author-email: Ruben van Nieuwpoort <ruben@vannieuwpoort.dev>
License: MIT License
        
        Copyright (c) 2025 Ruben van Nieuwpoort
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3
Description-Content-Type: text/markdown
License-File: LICENSE

# PyKaTeX

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

PyKaTeX uses a C extension module with [QuickJS-NG](https://github.com/quickjs-ng/quickjs) 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

```bash
pip install pykatex
```

Or, to install from source, clone the repository and run
```bash
pip install .
```

in the root of this repository.


## Usage

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

```python
pykatex.renderToString(input, **options)
```

It can be used as follows.

```python
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](https://katex.org/docs/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:
  ```python
  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.
