latex2code 0.2.0__py3-none-any.whl

latex2code/cli.py

@@ -0,0 +1,230 @@
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from latex2code import __version__
+from latex2code.core import (
+    Backend,
+    LaTeXTranspilerError,
+    inspect_latex,
+    transpile_latex,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Transpile LaTeX mathematical expressions into executable Python functions."
+    )
+    parser.add_argument(
+        "latex",
+        nargs="?",
+        type=str,
+        help="The LaTeX expression wrapped in quotes, or '-' to read from stdin",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-n",
+        "--name",
+        type=str,
+        default="formula",
+        help="Name of the generated Python function (default: 'formula')",
+    )
+    parser.add_argument(
+        "--no-types",
+        action="store_true",
+        help="Disable type hints in the generated function definition",
+    )
+    parser.add_argument(
+        "--backend",
+        choices=("python", "numpy", "torch", "jax"),
+        help="Generated code target (default: python)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        help="Write generated Python source to this file instead of stdout",
+    )
+    parser.add_argument(
+        "--inspect",
+        action="store_true",
+        help="Print a JSON report with the parsed expression, variables, warnings, and code",
+    )
+    parser.add_argument(
+        "--map-variable",
+        action="append",
+        metavar="SYMBOL=NAME",
+        help="Rename a parsed variable to a Python argument name (repeatable)",
+    )
+    parser.add_argument(
+        "-i",
+        "--interactive",
+        action="store_true",
+        help="Read expressions interactively until 'quit' or end-of-file",
+    )
+
+    args = parser.parse_args()
+
+    if args.latex is None and not args.interactive:
+        parser.print_help()
+        return
+    if args.interactive and args.latex is not None:
+        parser.error("--interactive cannot be combined with a positional expression")
+    if args.inspect and args.output:
+        parser.error("--inspect cannot be combined with --output")
+    if args.interactive and args.output:
+        parser.error("--interactive cannot be combined with --output")
+
+    variable_map = {}
+    for item in args.map_variable or ():
+        symbol, separator, name = item.partition("=")
+        if not separator or not symbol or not name:
+            parser.error(f"invalid --map-variable value {item!r}; expected SYMBOL=NAME")
+        if symbol in variable_map:
+            parser.error(f"variable {symbol!r} was mapped more than once")
+        variable_map[symbol] = name
+
+    latex_input = args.latex
+    if args.interactive:
+        _run_interactive(
+            function_name=args.name,
+            type_hints=not args.no_types,
+            backend=args.backend,
+            inspect=args.inspect,
+            variable_map=variable_map,
+        )
+        return
+
+    if latex_input == "-":
+        latex_input = sys.stdin.read().strip()
+
+    try:
+        if args.inspect:
+            details = inspect_latex(
+                latex_input,
+                function_name=args.name,
+                type_hints=not args.no_types,
+                backend=args.backend,
+                variable_map=variable_map,
+            )
+            print(json.dumps(asdict(details), indent=2))
+        else:
+            source = transpile_latex(
+                latex_input,
+                function_name=args.name,
+                type_hints=not args.no_types,
+                backend=args.backend,
+                variable_map=variable_map,
+            )
+            if args.output:
+                args.output.parent.mkdir(parents=True, exist_ok=True)
+                args.output.write_text(source, encoding="utf-8")
+            else:
+                print(source)
+    except LaTeXTranspilerError as err:
+        print(f"\n[Error] {err}", file=sys.stderr)
+        sys.exit(1)
+    except OSError as err:
+        print(f"\n[Error] Could not write output: {err}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as err:
+        print(f"\n[Unexpected Error] {err}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _run_interactive(
+    *,
+    function_name: str,
+    type_hints: bool,
+    backend: Backend | None,
+    inspect: bool,
+    variable_map: dict[str, str],
+) -> None:
+    mode = "inspection" if inspect else "code generation"
+    print(
+        f"latex2code interactive ({mode}); enter 'quit' to exit, "
+        "or ':begin' / ':end' for a multiline expression."
+    )
+    multiline: list[str] | None = None
+    while True:
+        try:
+            expression = input("latex2code> " if multiline is None else "...> ").strip()
+        except EOFError:
+            if multiline is not None:
+                print("Discarded unfinished multiline expression.", file=sys.stderr)
+            print()
+            return
+        if multiline is not None:
+            if expression == ":end":
+                _print_interactive_expression(
+                    "\n".join(multiline),
+                    function_name=function_name,
+                    type_hints=type_hints,
+                    backend=backend,
+                    inspect=inspect,
+                    variable_map=variable_map,
+                )
+                multiline = None
+            elif expression == ":cancel":
+                multiline = None
+                print("Cancelled.")
+            else:
+                multiline.append(expression)
+            continue
+        if expression == ":begin":
+            multiline = []
+            continue
+        if expression.lower() in {"quit", "exit"}:
+            return
+        if not expression:
+            continue
+        _print_interactive_expression(
+            expression,
+            function_name=function_name,
+            type_hints=type_hints,
+            backend=backend,
+            inspect=inspect,
+            variable_map=variable_map,
+        )
+
+
+def _print_interactive_expression(
+    expression: str,
+    *,
+    function_name: str,
+    type_hints: bool,
+    backend: Backend | None,
+    inspect: bool,
+    variable_map: dict[str, str],
+) -> None:
+    try:
+        if inspect:
+            details = inspect_latex(
+                expression,
+                function_name=function_name,
+                type_hints=type_hints,
+                backend=backend,
+                variable_map=variable_map,
+            )
+            print(json.dumps(asdict(details), indent=2))
+        else:
+            source = transpile_latex(
+                expression,
+                function_name=function_name,
+                type_hints=type_hints,
+                backend=backend,
+                variable_map=variable_map,
+            )
+            print(source, end="" if source.endswith("\n") else "\n")
+    except LaTeXTranspilerError as err:
+        print(f"[Error] {err}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

latex2code/core.py

@@ -0,0 +1,35 @@
+from .api import (
+    CompiledFormula,
+    TranspilationInfo,
+    compile_latex,
+    inspect_latex,
+    latex_to_code,
+    transpile_latex,
+)
+from .backends import Backend
+from .errors import (
+    CodeGenerationError,
+    InvalidLaTeXSyntaxError,
+    InvalidPythonIdentifierError,
+    LaTeXTranspilerError,
+    PiecewiseEvaluationWarning,
+    UnsupportedLaTeXFeatureError,
+)
+from .normalize import VALID_LATEX_COMMANDS
+
+__all__ = [
+    "Backend",
+    "CompiledFormula",
+    "TranspilationInfo",
+    "LaTeXTranspilerError",
+    "CodeGenerationError",
+    "InvalidLaTeXSyntaxError",
+    "UnsupportedLaTeXFeatureError",
+    "InvalidPythonIdentifierError",
+    "PiecewiseEvaluationWarning",
+    "VALID_LATEX_COMMANDS",
+    "transpile_latex",
+    "compile_latex",
+    "inspect_latex",
+    "latex_to_code",
+]

latex2code/errors.py

@@ -0,0 +1,210 @@
+import keyword
+import re
+
+RESERVED_MODULE_NAMES = {
+    "builtins",
+    "functools",
+    "jax",
+    "jnp",
+    "math",
+    "np",
+    "numpy",
+    "torch",
+}
+
+
+class LaTeXTranspilerError(Exception):
+    """Base exception raised for errors during LaTeX transpilation."""
+
+    pass
+
+
+class InvalidPythonIdentifierError(LaTeXTranspilerError):
+    """Raised when generated Python would contain an invalid identifier."""
+
+    def __init__(self, identifier: object, kind: str):
+        super().__init__(
+            f"{kind} must be a valid non-keyword Python identifier: {identifier!r}."
+        )
+
+
+class _LaTeXSyntaxError(LaTeXTranspilerError):
+    """Shared base for errors caused by LaTeX syntax or unsupported features."""
+
+    line: int | None
+    column: int | None
+
+
+class InvalidLaTeXSyntaxError(_LaTeXSyntaxError):
+    """Raised when the provided LaTeX string cannot be parsed."""
+
+    def __init__(
+        self,
+        raw_expression: str,
+        original_error: Exception | None = None,
+        hint: str | None = None,
+        location: tuple[int | None, int | None] | None = None,
+    ):
+        self.raw_expression = raw_expression
+        self.original_error = original_error
+        hint = hint or _syntax_hint(raw_expression)
+        resolved_location = (
+            location
+            if location is not None
+            else _syntax_location(raw_expression, original_error)
+        )
+        self.line, self.column = resolved_location
+        message = (
+            f"Failed to parse LaTeX expression: '{raw_expression}'. "
+            "Please verify the expression syntax and supported LaTeX subset."
+        )
+        if self.line is not None and self.column is not None:
+            message += (
+                f" Location: line {self.line}, column {self.column}."
+                f"\n{_source_context(raw_expression, self.line, self.column)}"
+            )
+        if hint:
+            message += f" Hint: {hint}"
+        super().__init__(message)
+
+
+class UnsupportedLaTeXFeatureError(_LaTeXSyntaxError):
+    """Raised when syntax is valid-looking but uses an unsupported command or function."""
+
+    def __init__(
+        self,
+        raw_expression: str,
+        feature: str,
+        kind: str = "LaTeX command",
+        suggestion: str | None = None,
+    ):
+        self.raw_expression = raw_expression
+        self.original_error = None
+        self.feature = feature
+        self.kind = kind
+        location_index = raw_expression.find(feature)
+        if location_index < 0 and feature.startswith("\\"):
+            location_index = raw_expression.find(feature[1:])
+        self.line, self.column = (
+            _line_and_column(raw_expression, location_index)
+            if location_index >= 0
+            else (None, None)
+        )
+        message = f"Unsupported {kind}: {feature}."
+        if self.line is not None and self.column is not None:
+            message += (
+                f" Location: line {self.line}, column {self.column}."
+                f"\n{_source_context(raw_expression, self.line, self.column)}"
+            )
+        if suggestion:
+            message += f" Did you mean {suggestion}?"
+        super().__init__(message)
+
+
+class CodeGenerationError(LaTeXTranspilerError):
+    """Raised when a parsed expression cannot be represented as executable Python."""
+
+
+class PiecewiseEvaluationWarning(UserWarning):
+    """Warns when array backends eagerly evaluate all branches of a piecewise expression."""
+
+
+def _line_and_column(expression: str, offset: int) -> tuple[int, int]:
+    line = expression.count("\n", 0, offset) + 1
+    line_start = expression.rfind("\n", 0, offset) + 1
+    return line, offset - line_start + 1
+
+
+def _source_context(expression: str, line: int, column: int) -> str:
+    lines = expression.splitlines() or [expression]
+    source_line = lines[line - 1] if line <= len(lines) else ""
+    start = max(0, column - 61)
+    end = min(len(source_line), start + 120)
+    prefix = "..." if start else ""
+    suffix = "..." if end < len(source_line) else ""
+    line_prefix = source_line[start : column - 1]
+    caret = " " * (len(prefix) + len(line_prefix.expandtabs())) + "^"
+    return f"  {prefix}{source_line[start:end]}{suffix}\n  {caret}"
+
+
+def _syntax_location(
+    expression: str,
+    original_error: Exception | None,
+) -> tuple[int | None, int | None]:
+    delimiters = {"(": ")", "[": "]", "{": "}"}
+    stack: list[tuple[str, int]] = []
+    for index, character in enumerate(expression):
+        if character in delimiters or character in delimiters.values():
+            backslashes = 0
+            previous = index - 1
+            while previous >= 0 and expression[previous] == "\\":
+                backslashes += 1
+                previous -= 1
+            if backslashes % 2:
+                continue
+            if character in delimiters:
+                stack.append((character, index))
+            elif not stack or delimiters[stack[-1][0]] != character:
+                return _line_and_column(expression, index)
+            else:
+                stack.pop()
+    if stack:
+        return _line_and_column(expression, stack[0][1])
+
+    begins = list(re.finditer(r"\\begin\{([^}]+)\}", expression))
+    endings = list(re.finditer(r"\\end\{([^}]+)\}", expression))
+    begin_names = [match.group(1) for match in begins]
+    ending_names = [match.group(1) for match in endings]
+    if begin_names != ending_names:
+        for begin, ending in zip(begins, endings):
+            if begin.group(1) != ending.group(1):
+                return _line_and_column(expression, begin.start())
+        if len(begins) > len(endings):
+            return _line_and_column(expression, begins[len(endings)].start())
+        if endings:
+            return _line_and_column(expression, endings[0].start())
+
+    if original_error is not None:
+        match = re.search(r"\n([^\n]*)\n([~ ]*)\^", str(original_error))
+        if match:
+            excerpt = match.group(1)
+            for line_number, source_line in enumerate(expression.splitlines(), start=1):
+                if source_line.strip() == excerpt.strip():
+                    return line_number, len(match.group(2)) + 1
+        trailing_operator = re.search(r"[+*/^=<>-]\s*$", expression)
+        if trailing_operator:
+            return _line_and_column(expression, len(expression.rstrip()))
+        repeated_operator = re.search(r"[+*/^=<>]\s*([*/^=<>])", expression)
+        if repeated_operator:
+            return _line_and_column(expression, repeated_operator.start(1))
+    return None, None
+
+
+def _syntax_hint(expression: str) -> str | None:
+    for opening, closing, label in (
+        ("{", "}", "curly braces"),
+        ("(", ")", "parentheses"),
+        ("[", "]", "square brackets"),
+    ):
+        if expression.count(opening) != expression.count(closing):
+            return f"Check that {label} are balanced."
+
+    environments = re.findall(r"\\begin\{([^}]+)\}", expression)
+    endings = re.findall(r"\\end\{([^}]+)\}", expression)
+    if environments != endings:
+        return "Make sure each \\begin{...} has a matching \\end{...} of the same environment."
+    if re.search(r"[+*/^=<>-]\s*$", expression):
+        return "The expression ends with an operator; add the missing operand or remove the operator."
+    if re.search(r"[+*/^=<>]\s*[*/^=<>]", expression):
+        return "Check for consecutive operators that do not form a valid expression."
+    return None
+
+
+def _validate_python_identifier(identifier: object, kind: str) -> None:
+    if (
+        not isinstance(identifier, str)
+        or not identifier.isidentifier()
+        or keyword.iskeyword(identifier)
+        or identifier in RESERVED_MODULE_NAMES
+    ):
+        raise InvalidPythonIdentifierError(identifier, kind)

latex2code/normalize.py

@@ -0,0 +1,207 @@
+import re
+
+LATEX_COMMAND_TRANSLATIONS = {
+    r"\coth": "coth",
+    r"\sech": "sech",
+    r"\csch": "csch",
+    r"\infty": "oo",
+    r"\equiv": "==",
+    r"\propto": "~",
+    r"\sim": "~",
+    r"\land": " and ",
+    r"\lor": " or ",
+    r"\not": " not ",
+    r"\asinh": "asinh",
+    r"\acosh": "acosh",
+    r"\atanh": "atanh",
+}
+
+LATEX_SYMBOL_COMMANDS = {
+    r"\frac",
+    r"\sin",
+    r"\cos",
+    r"\tan",
+    r"\cot",
+    r"\sec",
+    r"\csc",
+    r"\max",
+    r"\min",
+    r"\sinh",
+    r"\cosh",
+    r"\tanh",
+    r"\asin",
+    r"\acos",
+    r"\atan",
+    r"\arcsin",
+    r"\arccos",
+    r"\arctan",
+    r"\arccot",
+    r"\arcsec",
+    r"\arccsc",
+    r"\asinh",
+    r"\acosh",
+    r"\atanh",
+    r"\coth",
+    r"\sech",
+    r"\csch",
+    r"\sqrt",
+    r"\sum",
+    r"\prod",
+    r"\lim",
+    r"\binom",
+    r"\Gamma",
+    r"\beta",
+    r"\left",
+    r"\right",
+    r"\exp",
+    r"\log",
+    r"\ln",
+    r"\int",
+    r"\partial",
+    r"\pm",
+    r"\mp",
+    r"\times",
+    r"\cdot",
+    r"\div",
+    r"\ge",
+    r"\le",
+    r"\neq",
+    r"\neg",
+    r"\infty",
+    r"\pi",
+    r"\theta",
+    r"\alpha",
+    r"\gamma",
+    r"\delta",
+    r"\epsilon",
+    r"\varepsilon",
+    r"\zeta",
+    r"\eta",
+    r"\kappa",
+    r"\lambda",
+    r"\mu",
+    r"\nu",
+    r"\xi",
+    r"\rho",
+    r"\sigma",
+    r"\tau",
+    r"\upsilon",
+    r"\phi",
+    r"\varphi",
+    r"\chi",
+    r"\psi",
+    r"\omega",
+    r"\Delta",
+    r"\Lambda",
+    r"\Sigma",
+    r"\Theta",
+    r"\Omega",
+    r"\Phi",
+    r"\Pi",
+    r"\Psi",
+    r"\Xi",
+    r"\Upsilon",
+    r"\operatorname",
+    r"\mathrm",
+    r"\text",
+    r"\textbf",
+    r"\begin",
+    r"\end",
+    r"\vert",
+    r"\mid",
+    r"\lvert",
+    r"\rvert",
+    r"\langle",
+    r"\rangle",
+    r"\lfloor",
+    r"\rfloor",
+    r"\lceil",
+    r"\rceil",
+    r"\to",
+    r"\quad",
+    r"\qquad",
+    r"\vspace",
+    r"\hspace",
+}
+
+LATEX_ENVIRONMENTS = {
+    "cases",
+    "matrix",
+    "pmatrix",
+    "bmatrix",
+    "Bmatrix",
+    "vmatrix",
+    "Vmatrix",
+    "array",
+    "aligned",
+    "align",
+    "align*",
+    "gathered",
+    "eqnarray",
+    "eqnarray*",
+}
+
+VALID_LATEX_COMMANDS = LATEX_SYMBOL_COMMANDS | set(LATEX_COMMAND_TRANSLATIONS)
+
+
+def _normalize_latex_string(latex_str: str) -> str:
+    """Normalizes known LaTeX wrappers and function-style operators into SymPy-friendly syntax."""
+    normalized = latex_str.strip()
+
+    normalized = re.sub(r"\\mathrm\s*\{([A-Za-z]+)\}", r"\1", normalized)
+    command_pattern = re.compile(
+        "(?:"
+        + "|".join(
+            re.escape(command)
+            for command in sorted(LATEX_COMMAND_TRANSLATIONS, key=len, reverse=True)
+        )
+        + ")"
+        + r"(?![A-Za-z])"
+    )
+    normalized = command_pattern.sub(
+        lambda match: LATEX_COMMAND_TRANSLATIONS[match.group(0)],
+        normalized,
+    )
+
+    spacing_commands = (
+        r"\\(?:,|;|!|:|quad\b|qquad\b|enspace\b|thinspace\b|medspace\b|"
+        r"thickspace\b|negthinspace\b|hfill\b|vfill\b|allowbreak\b)"
+    )
+    normalized = re.sub(
+        spacing_commands,
+        lambda match: "".join(
+            "\n" if character == "\n" else " " for character in match.group(0)
+        ),
+        normalized,
+    )
+    sized_spacing_commands = r"\\(?:hspace|vspace)\*?\s*(?:\{[^{}]*\}|\[[^\[\]]*\])"
+    normalized = re.sub(
+        sized_spacing_commands,
+        lambda match: "".join(
+            "\n" if character == "\n" else " " for character in match.group(0)
+        ),
+        normalized,
+    )
+    style_commands = r"\\(?:displaystyle|textstyle|scriptstyle|scriptscriptstyle)\b"
+    normalized = re.sub(
+        style_commands,
+        lambda match: " " * len(match.group(0)),
+        normalized,
+    )
+
+    normalized = re.sub(
+        r"\\left\s*\|\s*(.+?)\s*\\right\s*\|", r"Abs(\1)", normalized, flags=re.DOTALL
+    )
+    normalized = re.sub(
+        r"\\left\s*\\lvert\s*(.+?)\s*\\right\s*\\rvert",
+        r"Abs(\1)",
+        normalized,
+        flags=re.DOTALL,
+    )
+    normalized = re.sub(r"\\left\s*[\[(]\s*", "(", normalized)
+    normalized = re.sub(r"\\right\s*[\])]\s*", ")", normalized)
+    normalized = re.sub(r"\\left\s*\\\{\s*", "(", normalized)
+    normalized = re.sub(r"\\right\s*\\\}\s*", ")", normalized)
+    normalized = re.sub(r"\\(?:left|right)\b", "", normalized)
+    normalized = re.sub(r"\\(?:vert|mid|lvert|rvert)\b", "|", normalized)
+    return normalized