expr2katex 0.1.0__py3-none-any.whl

expr2katex-0.1.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: expr2katex
+Version: 0.1.0
+Summary: Convert a Python expression string to a KaTeX string
+Project-URL: Homepage, https://github.com/YOUR_USERNAME/expr2katex
+Project-URL: Repository, https://github.com/YOUR_USERNAME/expr2katex
+Project-URL: Issues, https://github.com/YOUR_USERNAME/expr2katex/issues
+License: MIT
+License-File: LICENSE
+Keywords: ast,expression,katex,latex,math
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# expr2katex
+
+Convert a Python expression string to a [KaTeX](https://katex.org/) string.
+
+```python
+from expr2katex import expr2katex
+
+katex, err = expr2katex("sin(a) + (c + 3) * b")
+# katex → \sin\left(a\right)+\left(c+3\right)\times b
+# err   → None
+```
+
+## Features
+
+- **Zero dependencies** — built on Python's standard `ast` module only
+- **Precedence-aware parenthesisation** — reconstructs grouping from the AST structure, so `(a + b) * c` renders correctly without any string heuristics
+- **KaTeX-native functions** — `sin`, `cos`, `sqrt`, `log`, etc. render with their native KaTeX commands (`\sin`, `\sqrt{x}`, …)
+- **Unknown functions** fall back to `\operatorname{foo}` automatically
+- **Configurable division style** — `\frac{a}{b}` or `a \div b`
+- **Symbol style overrides** — control how variables and function names are rendered per symbol
+- **SyntaxError highlighting** — invalid expressions return a KaTeX string with the offending token highlighted in red, designed for real-time UI previews
+
+## Installation
+
+```bash
+pip install expr2katex
+```
+
+## Usage
+
+### Basic
+
+```python
+from expr2katex import expr2katex
+
+katex, err = expr2katex("sin(a) + b * c")
+# \sin\left(a\right)+b\times c
+```
+
+### Division style
+
+```python
+expr2katex("a / b")                      # \frac{a}{b}  (default)
+expr2katex("a / b", div_style="div")     # a \div b
+```
+
+### Power and roots
+
+```python
+expr2katex("a ** 2")          # a^{2}
+expr2katex("sqrt(x)")         # \sqrt{x}
+expr2katex("sqrt(x, 3)")      # \sqrt[3]{x}   (n-th root)
+```
+
+### Symbol style overrides
+
+```python
+from expr2katex import expr2katex, SymbolStyle
+
+expr2katex("foo(x)", symbol_styles={
+    "foo": SymbolStyle.TEXT,       # \text{foo}\left(x\right)
+    "x":   SymbolStyle.BOLD,       # \boldsymbol{x}
+})
+```
+
+| `SymbolStyle`   | Output                  | Default for  |
+|-----------------|-------------------------|--------------|
+| `ITALIC`        | `x`                     | variables    |
+| `OPERATORNAME`  | `\operatorname{foo}`    | functions    |
+| `TEXT`          | `\text{foo}`            |              |
+| `BOLD`          | `\boldsymbol{x}`        |              |
+
+### SyntaxError highlighting
+
+When the expression is invalid, `expr2katex` returns a KaTeX string with the offending token highlighted in red — useful for real-time formula editors.
+
+```python
+katex, err = expr2katex("sin(a + (b * c")
+# katex → \text{sin(a + }\textcolor{red}{\underbrace{\text{(}}}\text{b * c}
+# err   → '(' was never closed
+```
+
+Choose between `underbrace` (default) and `underline`:
+
+```python
+expr2katex("sin(a + (b * c", error_style="underline")
+```
+
+### Raising on error
+
+```python
+# SyntaxError is re-raised instead of being returned
+expr2katex("sin(a + (b * c", raise_on_error=True)
+# SyntaxError: '(' was never closed
+
+# All non-SyntaxError exceptions are always raised regardless of raise_on_error.
+```
+
+## API reference
+
+```python
+def expr2katex(
+    expr: str,
+    raise_on_error: bool = False,
+    div_style: Literal["frac", "div"] = "frac",
+    symbol_styles: dict[str, SymbolStyle] | None = None,
+    error_style: Literal["underbrace", "underline"] = "underbrace",
+) -> tuple[str, str | None]: ...
+```
+
+| Parameter       | Type                              | Default       | Description |
+|-----------------|-----------------------------------|---------------|-------------|
+| `expr`          | `str`                             | —             | Python expression string to convert |
+| `raise_on_error`| `bool`                            | `False`       | Re-raise `SyntaxError` instead of returning highlighted KaTeX |
+| `div_style`     | `"frac"` \| `"div"`              | `"frac"`      | Division rendering style |
+| `symbol_styles` | `dict[str, SymbolStyle] \| None` | `None`        | Per-symbol style overrides |
+| `error_style`   | `"underbrace"` \| `"underline"`  | `"underbrace"`| Error highlight decoration |
+
+**Returns** `(katex: str, err: str | None)` — `err` is `None` on success, or `SyntaxError.msg` on failure.
+
+## Supported operators
+
+| Python  | KaTeX output          |
+|---------|-----------------------|
+| `+`     | `a+b`                 |
+| `-`     | `a-b`                 |
+| `*`     | `a\times b`           |
+| `/`     | `\frac{a}{b}`         |
+| `//`    | `\lfloor\frac{a}{b}\rfloor` |
+| `%`     | `a\bmod b`            |
+| `**`    | `a^{b}`               |
+| `-x`    | `-x`                  |
+| `+x`    | `x` (omitted)         |
+
+## KaTeX-native functions
+
+The following function names are rendered with their native KaTeX command (`\sin`, `\cos`, …). All other names fall back to `\operatorname{name}`.
+
+`sin` `cos` `tan` `arcsin` `arccos` `arctan` `sinh` `cosh` `tanh` `log` `ln` `exp` `min` `max` `gcd` `lcm` `det` `dim` `sqrt`
+
+`sqrt` uses the dedicated `\sqrt{x}` template. Pass a second argument for n-th roots: `sqrt(x, n)` → `\sqrt[n]{x}`.
+
+## License
+
+MIT

expr2katex-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+expr2katex.py,sha256=XnSBPnGOqJSm8hKhpk7GvjcZzCyOT69etxCoAnHMA9U,13232
+expr2katex-0.1.0.dist-info/METADATA,sha256=VZDJqiwrrlsgszASRwZZ2hUFr_A4ByaQYeCuKgfpj7w,5885
+expr2katex-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+expr2katex-0.1.0.dist-info/licenses/LICENSE,sha256=Ka5j80Kk4YykLmHMuc8eGizbcj3Uwj9JJRAh07rwIwM,1098
+expr2katex-0.1.0.dist-info/RECORD,,

expr2katex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

expr2katex-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hiroshiasayadev-prog
+
+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.

expr2katex.py

@@ -0,0 +1,345 @@
+import ast
+from enum import Enum
+from typing import Literal
+
+
+class SymbolStyle(Enum):
+    """Rendering style for variables and function names in KaTeX output."""
+
+    ITALIC = "italic"
+    """Render as plain italic (default for variables). Example: ``x``"""
+
+    OPERATORNAME = "operatorname"
+    """Render using ``\\operatorname{}``. Example: ``\\operatorname{foo}``"""
+
+    TEXT = "text"
+    """Render using ``\\text{}``. Example: ``\\text{foo}``"""
+
+    BOLD = "bold"
+    """Render using ``\\boldsymbol{}``. Example: ``\\boldsymbol{x}``"""
+
+
+# Functions that KaTeX renders natively with a leading backslash (e.g. \sin, \cos).
+# All other function names fall back to \operatorname{name}.
+KATEX_NATIVE = {
+    "sin", "cos", "tan", "arcsin", "arccos", "arctan",
+    "sinh", "cosh", "tanh", "log", "ln", "exp",
+    "min", "max", "gcd", "lcm", "det", "dim",
+}
+
+# Operator precedence used to decide whether parentheses are needed around a
+# child BinOp node when it appears inside a higher-precedence parent BinOp.
+PRECEDENCE = {
+    ast.Add: 1,
+    ast.Sub: 1,
+    ast.Mult: 2,
+    ast.Div: 2,
+    ast.FloorDiv: 2,
+    ast.Mod: 2,
+    ast.Pow: 3,
+}
+
+
+def _apply_symbol_style(name: str, style: SymbolStyle) -> str:
+    """Wrap *name* in the KaTeX command that corresponds to *style*.
+
+    Args:
+        name: The raw symbol name (e.g. ``"x"`` or ``"foo"``).
+        style: The desired ``SymbolStyle``.
+
+    Returns:
+        A KaTeX string with the appropriate command applied.
+
+    Examples:
+        >>> _apply_symbol_style("x", SymbolStyle.BOLD)
+        '\\\\boldsymbol{x}'
+        >>> _apply_symbol_style("foo", SymbolStyle.OPERATORNAME)
+        '\\\\operatorname{foo}'
+    """
+    if style == SymbolStyle.ITALIC:
+        return name
+    elif style == SymbolStyle.OPERATORNAME:
+        return f"\\operatorname{{{name}}}"
+    elif style == SymbolStyle.TEXT:
+        return f"\\text{{{name}}}"
+    elif style == SymbolStyle.BOLD:
+        return f"\\boldsymbol{{{name}}}"
+    return name
+
+
+def _func2katex(name: str, style: SymbolStyle | None) -> str:
+    """Convert a function name to its KaTeX representation.
+
+    Resolution order:
+    1. If *style* is explicitly provided, delegate to :func:`_apply_symbol_style`.
+    2. If *name* is in :data:`KATEX_NATIVE`, render as ``\\name``.
+    3. Otherwise fall back to ``\\operatorname{name}``.
+
+    ``sqrt`` is handled separately in :func:`_convert` and should not be
+    passed here.
+
+    Args:
+        name: The function name as it appears in the source expression.
+        style: An explicit ``SymbolStyle`` override, or ``None`` to use the
+            default resolution order.
+
+    Returns:
+        A KaTeX string for the function name only (without arguments).
+
+    Examples:
+        >>> _func2katex("sin", None)
+        '\\\\sin'
+        >>> _func2katex("foo", None)
+        '\\\\operatorname{foo}'
+        >>> _func2katex("foo", SymbolStyle.TEXT)
+        '\\\\text{foo}'
+    """
+    if style is not None:
+        return _apply_symbol_style(name, style)
+    if name in KATEX_NATIVE:
+        return f"\\{name}"
+    return f"\\operatorname{{{name}}}"
+
+
+def _convert(
+    node: ast.expr,
+    parent_op: type | None,
+    div_style: Literal["frac", "div"],
+    symbol_styles: dict[str, SymbolStyle] | None,
+) -> str:
+    """Recursively convert an AST node to a KaTeX string.
+
+    Traversal is depth-first; leaf nodes (``Constant``, ``Name``) return
+    immediately, while compound nodes (``BinOp``, ``UnaryOp``, ``Call``)
+    recurse into their children before assembling the result.
+
+    Parentheses are inserted around a ``BinOp`` child whenever its precedence
+    is strictly lower than the *parent_op* precedence, reconstructing the
+    grouping that the Python parser encoded structurally in the AST.
+
+    Args:
+        node: The current AST node to convert.
+        parent_op: The ``type`` of the enclosing ``BinOp`` operator (e.g.
+            ``ast.Mult``), used for precedence-based parenthesisation.
+            Pass ``None`` at the root or when precedence context is irrelevant.
+        div_style: Controls division rendering — ``"frac"`` for
+            ``\\frac{l}{r}``, ``"div"`` for ``l \\div r``.
+        symbol_styles: Optional name-to-style mapping forwarded from
+            :func:`expr2katex`.
+
+    Returns:
+        A KaTeX string representing *node*.
+    """
+    # Leaf: numeric or string literal
+    if isinstance(node, ast.Constant):
+        return str(node.value)
+
+    # Leaf: variable name
+    if isinstance(node, ast.Name):
+        style = symbol_styles.get(node.id) if symbol_styles else None
+        if style is None:
+            style = SymbolStyle.ITALIC
+        return _apply_symbol_style(node.id, style)
+
+    # Unary operators: negate or identity
+    if isinstance(node, ast.UnaryOp):
+        operand = _convert(node.operand, None, div_style, symbol_styles)
+        # Wrap BinOp operands in parentheses so that -(a+b) does not render as -a+b.
+        if isinstance(node.operand, ast.BinOp):
+            operand = f"\\left({operand}\\right)"
+        if isinstance(node.op, ast.USub):
+            return f"-{operand}"
+        elif isinstance(node.op, ast.UAdd):
+            # Unary plus carries no mathematical meaning; omit it.
+            return operand
+        return operand
+
+    # Binary operators
+    if isinstance(node, ast.BinOp):
+        op_type = type(node.op)
+
+        # Division has two distinct visual forms controlled by div_style.
+        if isinstance(node.op, ast.Div):
+            left = _convert(node.left, op_type, div_style, symbol_styles)
+            right = _convert(node.right, op_type, div_style, symbol_styles)
+            if div_style == "frac":
+                return f"\\frac{{{left}}}{{{right}}}"
+            else:
+                return f"{left} \\div {right}"
+
+        # Exponentiation uses superscript notation.
+        if isinstance(node.op, ast.Pow):
+            left = _convert(node.left, op_type, div_style, symbol_styles)
+            right = _convert(node.right, op_type, div_style, symbol_styles)
+            return f"{left}^{{{right}}}"
+
+        left = _convert(node.left, op_type, div_style, symbol_styles)
+        right = _convert(node.right, op_type, div_style, symbol_styles)
+
+        if isinstance(node.op, ast.Add):
+            result = f"{left}+{right}"
+        elif isinstance(node.op, ast.Sub):
+            result = f"{left}-{right}"
+        elif isinstance(node.op, ast.Mult):
+            result = f"{left}\\times {right}"
+        elif isinstance(node.op, ast.FloorDiv):
+            result = f"\\lfloor\\frac{{{left}}}{{{right}}}\\rfloor"
+        elif isinstance(node.op, ast.Mod):
+            result = f"{left}\\bmod {right}"
+        else:
+            result = f"{left}?{right}"
+
+        # Wrap in parentheses when this node has lower precedence than its
+        # parent, preserving the grouping encoded in the AST structure.
+        if (
+            parent_op is not None
+            and op_type in PRECEDENCE
+            and parent_op in PRECEDENCE
+            and PRECEDENCE[op_type] < PRECEDENCE[parent_op]
+        ):
+            return f"\\left({result}\\right)"
+
+        return result
+
+    # Function call
+    if isinstance(node, ast.Call):
+        func_name = node.func.id if isinstance(node.func, ast.Name) else str(node.func)
+        style = symbol_styles.get(func_name) if symbol_styles else None
+        katex_func = _func2katex(func_name, style)
+
+        args = [_convert(a, None, div_style, symbol_styles) for a in node.args]
+
+        # sqrt has a dedicated KaTeX template; handle before the generic path.
+        if func_name == "sqrt":
+            if len(args) == 1:
+                return f"\\sqrt{{{args[0]}}}"
+            elif len(args) == 2:
+                # sqrt(x, n) renders as the n-th root of x.
+                return f"\\sqrt[{args[1]}]{{{args[0]}}}"
+
+        return f"{katex_func}\\left({', '.join(args)}\\right)"
+
+    return ""
+
+
+def _highlight_error(
+    expr: str,
+    offset: int,
+    error_style: Literal["underbrace", "underline"],
+) -> str:
+    """Build a KaTeX string that highlights the offending character in *expr*.
+
+    The character at *offset* (1-based, as reported by ``SyntaxError.offset``)
+    is wrapped in ``\\textcolor{red}`` combined with the decoration chosen by
+    *error_style*. The surrounding text is wrapped in ``\\text{}`` so that
+    spaces and special characters are rendered literally.
+
+    Args:
+        expr: The original expression string that caused the ``SyntaxError``.
+        offset: 1-based character index of the offending token, taken directly
+            from ``SyntaxError.offset``.
+        error_style: ``"underbrace"`` wraps the token in
+            ``\\textcolor{red}{\\underbrace{...}}``;
+            ``"underline"`` uses ``\\textcolor{red}{\\underline{...}}``.
+
+    Returns:
+        A KaTeX string with the error position highlighted in red.
+
+    Examples:
+        >>> _highlight_error("a+(b", 3, "underbrace")
+        '\\\\text{a+}\\\\textcolor{red}{\\\\underbrace{\\\\text{(}}}\\\\text{b}'
+    """
+    # offset is 1-based; convert to 0-based index.
+    idx = offset - 1
+    before = expr[:idx]
+    error_char = expr[idx] if idx < len(expr) else ""
+    after = expr[idx + 1:] if idx + 1 < len(expr) else ""
+
+    def escape(s: str) -> str:
+        """Wrap a raw string in \\text{} so KaTeX renders it literally."""
+        return f"\\text{{{s}}}" if s else ""
+
+    if error_style == "underbrace":
+        highlighted = f"\\textcolor{{red}}{{\\underbrace{{{escape(error_char)}}}}}" if error_char else ""
+    else:
+        highlighted = f"\\textcolor{{red}}{{\\underline{{{escape(error_char)}}}}}" if error_char else ""
+
+    return f"\\text{{{before}}}{highlighted}\\text{{{after}}}"
+
+
+def expr2katex(
+    expr: str,
+    raise_on_error: bool = False,
+    div_style: Literal["frac", "div"] = "frac",
+    symbol_styles: dict[str, SymbolStyle] | None = None,
+    error_style: Literal["underbrace", "underline"] = "underbrace",
+) -> tuple[str, str | None]:
+    """Convert a Python expression string to a KaTeX string.
+
+    Parses *expr* into an AST and recursively converts each node into its
+    KaTeX representation via :func:`_convert`. If a ``SyntaxError`` is
+    detected, the offending token is highlighted in red and the error message
+    is returned as the second element of the tuple.
+
+    Args:
+        expr:
+            A Python expression string to convert (e.g. ``"sin(a) + b * c"``).
+        raise_on_error:
+            If ``True``, re-raises ``SyntaxError`` instead of returning a
+            highlighted KaTeX string. Other exceptions are always re-raised
+            regardless of this flag.
+        div_style:
+            Controls how the ``/`` operator is rendered.
+            ``"frac"`` (default) produces ``\\frac{l}{r}``.
+            ``"div"`` produces ``l \\div r``.
+        symbol_styles:
+            Optional mapping from a symbol name to a ``SymbolStyle``, applied
+            to both variables (``ast.Name``) and function names (``ast.Call``).
+            Variables default to ``ITALIC``; functions default to
+            ``OPERATORNAME``. KaTeX-native functions (e.g. ``sin``, ``sqrt``)
+            always use their native command and ignore this mapping unless
+            explicitly overridden.
+        error_style:
+            Controls how the offending token is decorated on ``SyntaxError``.
+            ``"underbrace"`` (default) uses
+            ``\\textcolor{red}{\\underbrace{...}}``.
+            ``"underline"`` uses ``\\textcolor{red}{\\underline{...}}``.
+            Ignored when ``raise_on_error=True``.
+
+    Returns:
+        A tuple ``(katex, err)`` where:
+
+        - ``katex`` — the KaTeX string. Always present, even on
+          ``SyntaxError`` (unless ``raise_on_error=True``). The error token
+          is highlighted according to *error_style*.
+        - ``err`` — ``None`` on success, or ``SyntaxError.msg`` on failure.
+
+    Raises:
+        SyntaxError: if ``raise_on_error=True`` and *expr* is syntactically
+            invalid.
+        Exception: any exception raised during AST traversal is always
+            propagated, regardless of ``raise_on_error``.
+
+    Examples:
+        >>> expr2katex("sin(a) + b * c")
+        ('\\\\sin\\\\left(a\\\\right)+b\\\\times c', None)
+
+        >>> expr2katex("a / b", div_style="div")
+        ('a \\\\div b', None)
+
+        >>> expr2katex("sin(a+(c+3)*b")
+        ('\\\\text{sin(a+}\\\\textcolor{red}{\\\\underbrace{\\\\text{(}}}\\\\text{c+3*b}', "'(' was never closed")
+
+        >>> expr2katex("sin(a+(c+3)*b", raise_on_error=True)
+        SyntaxError: '(' was never closed
+    """
+    try:
+        tree = ast.parse(expr, mode="eval")
+    except SyntaxError as e:
+        if raise_on_error:
+            raise
+        katex = _highlight_error(expr, e.offset or 0, error_style)
+        return (katex, e.msg)
+
+    katex = _convert(tree.body, None, div_style, symbol_styles)
+    return (katex, None)