PyPI - python-color-math - Versions diffs - 0.1.0__py3-none-any.whl - Mend

python-color-math 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (40) hide show

color_math/__init__.py +8 -0
color_math/__main__.py +5 -0
color_math/adapters.py +288 -0
color_math/config.py +351 -0
color_math/converters/__init__.py +27 -0
color_math/converters/align.py +18 -0
color_math/converters/block.py +126 -0
color_math/converters/derivative.py +266 -0
color_math/converters/equation.py +5 -0
color_math/converters/generic.py +101 -0
color_math/converters/integral.py +16 -0
color_math/converters/limit.py +16 -0
color_math/converters/matrix.py +143 -0
color_math/converters/semantic.py +76 -0
color_math/io.py +53 -0
color_math/main.py +162 -0
color_math/parsers/__init__.py +64 -0
color_math/parsers/braket.py +109 -0
color_math/parsers/delimiters.py +151 -0
color_math/parsers/differentials.py +71 -0
color_math/parsers/dimensionless.py +74 -0
color_math/parsers/latex_spans.py +1050 -0
color_math/parsers/markdown_scanner.py +463 -0
color_math/parsers/math_parser.py +366 -0
color_math/parsers/scanner.py +351 -0
color_math/parsers/taxonomy.py +124 -0
color_math/parsers/units.py +98 -0
color_math/parsers/variable_hash.py +126 -0
color_math/self_test.py +224 -0
color_math/undo.py +63 -0
color_math/utils/__init__.py +30 -0
color_math/utils/coloring.py +61 -0
color_math/utils/latex_helpers.py +232 -0
color_math/utils/spans.py +77 -0
python_color_math-0.1.0.dist-info/METADATA +167 -0
python_color_math-0.1.0.dist-info/RECORD +40 -0
python_color_math-0.1.0.dist-info/WHEEL +5 -0
python_color_math-0.1.0.dist-info/entry_points.txt +2 -0
python_color_math-0.1.0.dist-info/licenses/LICENSE +21 -0
python_color_math-0.1.0.dist-info/top_level.txt +1 -0

color_math/converters/block.py ADDED Viewed

@@ -0,0 +1,126 @@
+# converters/block.py
+from __future__ import annotations
+import re
+from collections.abc import Callable
+from ..config import ColorMathOptions
+from ..parsers.markdown_scanner import scan_markdown
+from .align import convert_align_block
+from .derivative import convert_derivative_line
+from .equation import convert_equation_line
+from .generic import color_latex_body, color_generic_math_line
+from .integral import convert_integral_line
+from .limit import convert_limit_line
+from .matrix import convert_matrix_block
+MATH_BLOCK_RE = re.compile(
+    r"^(?P<prefix>\s*\#+\s*)?\$\$(?P<body>.*)\$\$(?P<suffix>\s*)$",
+    re.DOTALL,
+)
+Converter = Callable[[str], str | None]
+LINE_CONVERTERS: tuple[Converter, ...] = (
+    convert_derivative_line,
+    convert_integral_line,
+    convert_limit_line,
+    convert_equation_line,
+)
+BLOCK_CONVERTERS: tuple[Converter, ...] = (
+    convert_matrix_block,
+    convert_align_block,
+)
+def try_converters(text: str, converters: tuple[Converter, ...]) -> str | None:
+    for converter in converters:
+        converted = converter(text)
+        if converted is not None:
+            return converted
+    return None
+def convert_math_block(
+    block: str,
+    palette: dict[str, str] | None = None,
+    options: ColorMathOptions | None = None,
+) -> str:
+    """
+    Convert a multiline math block.
+    Specialized converters insert wrappers into the original source. Generic
+    coloring is used only when no semantic formatter recognizes the block.
+    """
+    match = MATH_BLOCK_RE.match(block)
+    if not match:
+        return block
+    prefix = match.group("prefix") or ""
+    body = match.group("body")
+    suffix = match.group("suffix")
+    line_match = try_converters(block, LINE_CONVERTERS)
+    if line_match is not None:
+        return line_match
+    block_match = try_converters(block, BLOCK_CONVERTERS)
+    if block_match is not None:
+        return block_match
+    # fallback to generic coloring
+    return f"{prefix}$${color_latex_body(body, palette, options)}$${suffix}"
+def convert_line(
+    line: str,
+    palette: dict[str, str] | None = None,
+    options: ColorMathOptions | None = None,
+) -> str:
+    """
+    Convert a single line.
+    Checks specialized converters first,
+    otherwise generic math coloring.
+    """
+    converted = try_converters(line, LINE_CONVERTERS)
+    if converted is not None:
+        return converted
+    return color_generic_math_line(line, palette, options)
+def convert_text(
+    text: str,
+    palette: dict[str, str] | None = None,
+    options: ColorMathOptions | None = None,
+) -> str:
+    """
+    Convert an entire document.
+    Handles:
+      - single-line and multiline $$ ... $$ math blocks
+      - normal text passthrough
+    """
+    math_blocks = scan_markdown(text).math_blocks
+    if not math_blocks:
+        return text
+    converted: list[str] = []
+    index = 0
+    for span in math_blocks:
+        converted.append(text[index:span.start])
+        converted.append(convert_math_block(text[span.start:span.end], palette, options))
+        index = span.end
+    converted.append(text[index:])
+    return "".join(converted)

color_math/converters/derivative.py ADDED Viewed

@@ -0,0 +1,266 @@
+"""Lossless semantic coloring for chain-rule derivatives."""
+from __future__ import annotations
+import re
+from ..config import COLORS
+from ..parsers.latex_spans import (
+    find_operand_spans,
+    read_command,
+    read_group_end,
+    read_operand,
+    skip_ignorable,
+)
+from ..parsers.scanner import collect_operator_spans
+from ..utils.latex_helpers import contains_color_wrapper
+from ..utils.spans import ColorSpan, apply_color_spans
+from .semantic import first_equality, parse_math_block, relation_spans, trim_range
+NUMERIC_FRACTION_RE = re.compile(
+    r"\\(?:dfrac|tfrac|frac)\{[+-]?\d+(?:\.\d+)?\}"
+    r"\{[+-]?\d+(?:\.\d+)?\}"
+)
+PLAIN_COEFFICIENT_RE = re.compile(r"[A-Za-z]")
+ADDITIVE_SEPARATOR_RE = re.compile(
+    r"[+\-=<>]|\\(?:pm|mp|leq|geq|neq|approx|sim|equiv)(?![A-Za-z])"
+)
+MULTIPLICATIVE_GAP_RE = re.compile(
+    r"(?:\s|[·*]|\\(?:cdot|times|,|:|;|!|quad|qquad)(?![A-Za-z]))*"
+)
+def _compact(value: str) -> str:
+    return re.sub(r"\s+", "", value)
+def _is_derivative_prefix(value: str) -> bool:
+    compact = _compact(value)
+    return compact.startswith(
+        (r"\frac{d}{d", r"\dfrac{d}{d", r"\tfrac{d}{d")
+    )
+def _is_prime(value: str) -> bool:
+    return bool(re.match(r"(?:[A-Za-z]|\\[A-Za-z]+)'", value.lstrip()))
+def _is_numeric(value: str) -> bool:
+    compact = _compact(value)
+    return bool(
+        re.fullmatch(r"[+-]?\d+(?:\.\d+)?", compact)
+        or NUMERIC_FRACTION_RE.fullmatch(compact)
+    )
+def _is_outer_derivative(value: str) -> bool:
+    compact = _compact(value)
+    return (
+        compact.startswith(
+            (
+                r"\cos",
+                r"\sin",
+                r"\tan",
+                r"\sec",
+                r"\ln",
+                r"\log",
+                r"\sqrt",
+                r"\frac",
+                r"\dfrac",
+                r"\tfrac",
+                "e^",
+            )
+        )
+        or _is_prime(compact)
+    )
+def _has_additive_separator(value: str) -> bool:
+    return ADDITIVE_SEPARATOR_RE.search(value) is not None
+def _is_multiplicative_gap(value: str) -> bool:
+    return MULTIPLICATIVE_GAP_RE.fullmatch(value) is not None
+def _fraction_arguments(
+    body: str,
+    operand_start: int,
+    end: int,
+) -> tuple[tuple[int, int], ...]:
+    command = read_command(body, operand_start, end)
+    if command is None or command[0] not in {"frac", "dfrac", "tfrac"}:
+        return ()
+    ranges: list[tuple[int, int]] = []
+    index = command[1]
+    for _ in range(2):
+        index = skip_ignorable(body, index, end)
+        group_end = read_group_end(body, index, end)
+        if group_end is None:
+            return ()
+        ranges.append((index + 1, group_end - 1))
+        index = group_end
+    return tuple(ranges)
+def _rhs_spans(body: str, start: int, end: int | None = None) -> list[ColorSpan]:
+    end = len(body) if end is None else end
+    operands = list(find_operand_spans(body, start, end))
+    spans: list[ColorSpan] = []
+    prime_seen = False
+    previous_end = start
+    for index, operand in enumerate(operands):
+        if _has_additive_separator(body[previous_end:operand.start]):
+            prime_seen = False
+        value = body[operand.start:operand.end]
+        compact = _compact(value)
+        next_exists = index + 1 < len(operands)
+        multiplicative_gap = (
+            body[operand.end:operands[index + 1].start]
+            if next_exists
+            else ""
+        )
+        is_coefficient = _is_numeric(value) or (
+            next_exists
+            and PLAIN_COEFFICIENT_RE.fullmatch(compact) is not None
+            and _is_multiplicative_gap(multiplicative_gap)
+        )
+        if is_coefficient:
+            color_name = "orange"
+        elif _is_prime(value):
+            color_name = "chain" if prime_seen else "derivative"
+            prime_seen = True
+        elif prime_seen:
+            color_name = "chain" if operand.kind == "symbol" else "main"
+        else:
+            color_name = "derivative" if _is_outer_derivative(value) else "main"
+        span_start = operand.start
+        if _is_numeric(value):
+            sign = operand.start - 1
+            while sign >= start and body[sign].isspace():
+                sign -= 1
+            if sign >= start and body[sign] in "+-":
+                before = sign - 1
+                while before >= start and body[before].isspace():
+                    before -= 1
+                if before < start or body[before] in "=+-(":
+                    span_start = sign
+        primed_name = re.match(r"[A-Za-z]+['’]+", value)
+        product_group: tuple[int, int] | None = None
+        if primed_name is not None:
+            group_start = skip_ignorable(
+                body,
+                operand.start + primed_name.end(),
+                operand.end,
+            )
+            group_end = read_group_end(body, group_start, operand.end)
+            if (
+                group_end is not None
+                and any(token in body[group_start + 1:group_end - 1] for token in "+-")
+            ):
+                product_group = (group_start, operand.end)
+        if product_group is None:
+            spans.append(
+                ColorSpan(
+                    span_start,
+                    operand.end,
+                    COLORS[color_name],
+                    priority=20,
+                )
+            )
+        else:
+            spans.extend(
+                (
+                    ColorSpan(
+                        span_start,
+                        operand.start + primed_name.end(),
+                        COLORS[color_name],
+                        priority=20,
+                    ),
+                    ColorSpan(
+                        product_group[0],
+                        product_group[1],
+                        COLORS["main"],
+                        priority=20,
+                    ),
+                )
+            )
+        if (
+            not _is_numeric(value)
+            and value.lstrip().startswith((r"\frac", r"\dfrac", r"\tfrac"))
+        ):
+            for inner_start, inner_end in _fraction_arguments(
+                body,
+                operand.start,
+                operand.end,
+            ):
+                inner_semantic = _rhs_spans(body, inner_start, inner_end)
+                inner_relations = relation_spans(body, inner_start, inner_end)
+                spans.extend(
+                    relation
+                    for relation in inner_relations
+                    if not any(
+                        semantic.start <= relation.start
+                        and relation.end <= semantic.end
+                        for semantic in inner_semantic
+                    )
+                )
+                spans.extend(inner_semantic)
+        previous_end = operand.end
+    return spans
+def convert_derivative_line(source: str) -> str | None:
+    """Color a derivative block by inserting wrappers into its exact source."""
+    block = parse_math_block(source)
+    if block is None:
+        return None
+    body_start = skip_ignorable(block.body, 0, len(block.body))
+    prefix = read_operand(block.body, body_start)
+    if prefix is None or not _is_derivative_prefix(prefix.text(block.body)):
+        return None
+    if contains_color_wrapper(block.body):
+        return source
+    equality = first_equality(block.body)
+    if equality is None or equality[0] <= prefix.end:
+        return None
+    target_start, target_end = trim_range(
+        block.body,
+        prefix.end,
+        equality[0],
+    )
+    relations = relation_spans(block.body)
+    operators = collect_operator_spans(block.body)
+    target: ColorSpan | None = None
+    if target_start < target_end:
+        target = ColorSpan(
+            target_start,
+            target_end,
+            COLORS["main"],
+            priority=20,
+        )
+    semantic_rhs = _rhs_spans(block.body, equality[1])
+    relations = [
+        span
+        for span in relations
+        if not any(
+            semantic.start <= span.start and span.end <= semantic.end
+            for semantic in semantic_rhs
+        )
+    ]
+    spans = [*relations, *operators, *semantic_rhs]
+    if target is not None:
+        spans.append(target)
+    return block.render(apply_color_spans(block.body, spans))

color_math/converters/equation.py ADDED Viewed

@@ -0,0 +1,5 @@
+from __future__ import annotations
+def convert_equation_line(line: str) -> str | None:
+    return None

color_math/converters/generic.py ADDED Viewed

@@ -0,0 +1,101 @@
+"""Generic source-preserving LaTeX coloring."""
+from __future__ import annotations
+import re
+from ..config import COLORS, ColorMathOptions
+from ..parsers.math_parser import find_semantic_spans
+from ..parsers.scanner import collect_scanner_spans
+from ..parsers.units import find_unit_spans, collect_unit_spans
+from ..parsers.differentials import find_differential_spans, collect_differential_spans
+from ..parsers.braket import collect_braket_delimiter_spans
+from ..parsers.dimensionless import find_dimensionless_spans, collect_dimensionless_spans
+from ..parsers.delimiters import collect_delimiter_spans
+from ..parsers.taxonomy import collect_taxonomy_spans
+from ..parsers.variable_hash import collect_variable_spans
+from ..utils.latex_helpers import contains_color_wrapper
+from ..utils.spans import ColorSpan, apply_color_spans
+MATH_LINE_RE = re.compile(
+    r"^(?P<prefix>\s*\#+\s*)?\$\$(?P<body>.*)\$\$(?P<suffix>\s*)$"
+)
+FUNCTION_COLOR_NAMES = ("main", "derivative", "chain")
+def collect_function_spans(body: str, palette: dict[str, str] | None = None) -> list[ColorSpan]:
+    """Color nested call names and recognize literal constants."""
+    pal = palette or COLORS
+    semantic, _ = find_semantic_spans(body)
+    spans: list[ColorSpan] = []
+    for item in semantic:
+        if item.kind == "function":
+            color_name = FUNCTION_COLOR_NAMES[min(item.depth, 2)]
+        elif item.kind == "constant":
+            color_name = "orange"
+        else:
+            continue
+        spans.append(
+            ColorSpan(item.start, item.end, pal[color_name], priority=20)
+        )
+    return spans
+def color_latex_body(
+    body: str,
+    palette: dict[str, str] | None = None,
+    options: ColorMathOptions | None = None,
+) -> str:
+    """Insert scoped colors while preserving every original source character."""
+    if contains_color_wrapper(body):
+        return body
+    pal = palette or COLORS
+    opts = options or ColorMathOptions()
+    unit_spans = find_unit_spans(body)
+    diff_spans = find_differential_spans(body)
+    dim_spans = find_dimensionless_spans(body)
+    spans: list[ColorSpan] = [
+        *collect_function_spans(body, pal),
+        *collect_scanner_spans(body),
+    ]
+    if opts.color_units:
+        spans.extend(collect_unit_spans(body, pal, unit_spans))
+    if opts.color_differentials:
+        spans.extend(collect_differential_spans(body, pal, diff_spans))
+    if opts.color_dimensionless:
+        spans.extend(collect_dimensionless_spans(body, pal, dim_spans))
+    if opts.color_braket:
+        spans.extend(collect_braket_delimiter_spans(body, pal))
+    if opts.rainbow_delimiters:
+        spans.extend(collect_delimiter_spans(body))
+    if opts.enable_taxonomy:
+        spans.extend(collect_taxonomy_spans(body, pal, unit_spans, diff_spans, dim_spans))
+    if opts.variable_data_flow:
+        spans.extend(collect_variable_spans(body, None, unit_spans, diff_spans, dim_spans))
+    return apply_color_spans(body, spans)
+def color_generic_math_line(
+    line: str,
+    palette: dict[str, str] | None = None,
+    options: ColorMathOptions | None = None,
+) -> str:
+    """Convert a single-line ``$$...$$`` math block."""
+    match = MATH_LINE_RE.match(line)
+    if match is None:
+        return line
+    prefix = match.group("prefix") or ""
+    suffix = match.group("suffix")
+    return f"{prefix}$${color_latex_body(match.group('body'), palette, options)}$${suffix}"

color_math/converters/integral.py ADDED Viewed

@@ -0,0 +1,16 @@
+from __future__ import annotations
+import re
+from .generic import color_latex_body
+from .semantic import parse_math_block
+INTEGRAL_RE = re.compile(r"\\(?:i{1,3}nt|oint)(?![A-Za-z])")
+def convert_integral_line(line: str) -> str | None:
+    block = parse_math_block(line)
+    if block is None or INTEGRAL_RE.search(block.body) is None:
+        return None
+    return block.render(color_latex_body(block.body))

color_math/converters/limit.py ADDED Viewed

@@ -0,0 +1,16 @@
+from __future__ import annotations
+import re
+from .generic import color_latex_body
+from .semantic import parse_math_block
+LIMIT_RE = re.compile(r"\\(?:lim|liminf|limsup|inf|sup|max|min)(?![A-Za-z])")
+def convert_limit_line(line: str) -> str | None:
+    block = parse_math_block(line)
+    if block is None or LIMIT_RE.search(block.body) is None:
+        return None
+    return block.render(color_latex_body(block.body))

color_math/converters/matrix.py ADDED Viewed

@@ -0,0 +1,143 @@
+"""Lossless semantic coloring for matrix and indexed tensor expressions."""
+from __future__ import annotations
+import re
+from ..config import COLORS
+from ..parsers.latex_spans import OperandSpan, find_operand_spans, read_operand
+from ..parsers.scanner import collect_operator_spans, collect_structured_spans
+from ..utils.latex_helpers import contains_color_wrapper
+from ..utils.spans import ColorSpan, apply_color_spans
+from .semantic import first_equality, parse_math_block, relation_spans
+MATRIX_COMMAND_RE = re.compile(
+    r"\\(?:mathbf|mathcal|nabla|det|tr|Tr|trace|Vert|lVert)"
+    r"(?![A-Za-z])|\\\|(?![A-Za-z])|"
+    r"\\operatorname\s*\{\s*tr\s*\}"
+)
+MATRIX_ENV_RE = re.compile(
+    r"\\begin\s*\{\s*"
+    r"(?:Bmatrix|Vmatrix|array|bmatrix|matrix|pmatrix|smallmatrix|vmatrix)"
+    r"\s*\}"
+)
+NUMBER_RE = re.compile(r"[+-]?\d+(?:\.\d+)?")
+def _structural_source(body: str) -> str:
+    """Mask comments and opaque macros before semantic classification."""
+    visible = list(body)
+    index = 0
+    while index < len(body):
+        if body[index] == "%":
+            end = index + 1
+            while end < len(body) and body[end] not in "\r\n":
+                visible[end] = " "
+                end += 1
+            visible[index] = " "
+            index = end
+            continue
+        operand = read_operand(body, index)
+        if operand is not None and operand.kind == "opaque":
+            for position in range(operand.start, operand.end):
+                if visible[position] not in "\r\n":
+                    visible[position] = " "
+            index = operand.end
+            continue
+        index += 1
+    return "".join(visible)
+def _is_matrix_expression(body: str) -> bool:
+    structural = _structural_source(body)
+    operands = find_operand_spans(structural)
+    indexed = [
+        operand
+        for operand in operands
+        if operand.kind == "symbol" and "_" in operand.text(structural)
+    ]
+    return (
+        MATRIX_COMMAND_RE.search(structural) is not None
+        or MATRIX_ENV_RE.search(structural) is not None
+        or any(operand.kind == "matrix" for operand in operands)
+        or len(indexed) >= 2
+    )
+def _operand_color_spans(
+    body: str,
+    operands: tuple[OperandSpan, ...],
+    names: tuple[str, ...],
+) -> list[ColorSpan]:
+    spans: list[ColorSpan] = []
+    semantic_index = 0
+    for operand in operands:
+        value = re.sub(r"\s+", "", operand.text(body))
+        if NUMBER_RE.fullmatch(value):
+            name = "orange"
+        else:
+            name = names[min(semantic_index, len(names) - 1)]
+            semantic_index += 1
+        spans.append(
+            ColorSpan(
+                operand.start,
+                operand.end,
+                COLORS[name],
+                priority=20,
+            )
+        )
+    return spans
+def _operator_spans(body: str) -> list[ColorSpan]:
+    return collect_operator_spans(body)
+def convert_matrix_block(source: str) -> str | None:
+    """Color complete matrix/tensor operands without reconstructing LaTeX."""
+    block = parse_math_block(source)
+    if block is None or not _is_matrix_expression(block.body):
+        return None
+    if contains_color_wrapper(block.body):
+        return source
+    equality = first_equality(block.body)
+    if equality is None:
+        return None
+    lhs = find_operand_spans(block.body, 0, equality[0])
+    rhs = find_operand_spans(block.body, equality[1])
+    if not lhs or not rhs:
+        return None
+    lhs_first = re.sub(r"\s+", "", lhs[0].text(block.body))
+    if len(lhs) == 1:
+        lhs_colors = (
+            ("upper",)
+            if lhs_first.startswith((r"\det", r"\operatorname{tr}"))
+            else ("main",)
+        )
+    elif lhs_first.startswith((r"\frac{\partial}", r"\nabla")):
+        lhs_colors = ("upper", "main")
+    else:
+        lhs_colors = ("upper", "chain", "orange")
+    lhs_text = re.sub(r"\s+", "", block.body[:equality[0]])
+    if lhs_first.startswith(r"\frac{\partial}"):
+        rhs_colors = ("chain", "main")
+    elif len(lhs) > 1 and len(rhs) == 1:
+        rhs_colors = ("main",)
+    elif lhs_text.startswith((r"\det", r"\operatorname{tr}")):
+        rhs_colors = ("main", "chain")
+    elif r"\otimes" in block.body:
+        rhs_colors = ("upper", "chain", "orange")
+    else:
+        rhs_colors = ("upper", "chain")
+    spans = relation_spans(block.body)
+    spans.extend(_operand_color_spans(block.body, lhs, lhs_colors))
+    spans.extend(_operand_color_spans(block.body, rhs, rhs_colors))
+    spans.extend(_operator_spans(block.body))
+    spans.extend(collect_structured_spans(block.body))
+    return block.render(apply_color_spans(block.body, spans))