python-color-math 0.2.12__py3-none-any.whl → 0.2.14__py3-none-any.whl

color_math/__init__.py

@@ -5,13 +5,19 @@ from .config import ColorMathOptions
 from .converters.block import convert_text
 from .undo import uncolor_text
 
-__version__ = "0.2.12"
+from .ipython import ColorMath, colormath, load_ipython_extension, unload_ipython_extension
+
+__version__ = "0.2.14"
 
 __all__ = [
     "__version__",
+    "ColorMath",
     "ColorMathOptions",
+    "colormath",
     "convert_text",
     "detect_format",
+    "load_ipython_extension",
     "transform_document",
     "uncolor_text",
+    "unload_ipython_extension",
 ]

color_math/ipython.py

@@ -0,0 +1,183 @@
+"""IPython and Jupyter integration for color-math.
+
+Enables seamless colorized math in Jupyter Notebook 7, JupyterLab, Classic
+Notebook, and Google Colab via `%load_ext color_math`.
+"""
+
+from __future__ import annotations
+
+import shlex
+from typing import Any
+
+from .adapters import transform_document
+from .config import ColorMathOptions, THEMES
+from .converters.block import convert_math_block, convert_text
+
+try:
+    from IPython.core.magic import Magics, cell_magic, line_magic, magics_class
+    from IPython.display import Markdown, Math, display
+    HAS_IPYTHON = True
+except ImportError:
+    HAS_IPYTHON = False
+    Magics = object  # type: ignore[misc,assignment]
+    def magics_class(cls: Any) -> Any: return cls
+    def line_magic(func: Any) -> Any: return func
+    def cell_magic(func: Any) -> Any: return func
+
+
+def colormath(
+    text: str,
+    palette: dict[str, str] | None = None,
+    options: ColorMathOptions | None = None,
+    theme: str | None = None,
+    is_fragment: bool = False,
+) -> str:
+    """Convenience helper to colorize LaTeX math or Markdown math.
+
+    If is_fragment is True, text is treated as raw math without $ delimiters.
+    """
+    active_palette = THEMES.get(theme) if theme else palette
+    if is_fragment:
+        converted = convert_math_block(f"$${text}$$", palette=active_palette, options=options)
+        return converted[2:-2]
+    return convert_text(text, palette=active_palette, options=options)
+
+
+if HAS_IPYTHON:
+    class ColorMath(Math):
+        """A drop-in replacement for IPython.display.Math that renders with semantic colors."""
+
+        def __init__(
+            self,
+            data: Any = None,
+            palette: dict[str, str] | None = None,
+            options: ColorMathOptions | None = None,
+            theme: str | None = None,
+            **kwargs: Any,
+        ) -> None:
+            raw = "" if data is None else str(data)
+            colored = colormath(raw, palette=palette, options=options, theme=theme, is_fragment=True)
+            super().__init__(data=colored, **kwargs)
+
+
+    @magics_class
+    class ColorMathMagics(Magics):
+        """IPython magics for semantic LaTeX colorization."""
+
+        def __init__(self, shell: Any) -> None:
+            super().__init__(shell)
+            self._auto_hook_active = False
+            self._orig_math_repr = None
+
+        @line_magic("color_math")
+        @line_magic("colormath")
+        def color_math_line(self, line: str) -> Any:
+            r"""Colorize and display a single LaTeX formula.
+
+            Usage:
+                %color_math \int_0^1 x^2 dx = \frac{1}{3}
+                %color_math --theme catppuccin \hat{H}\psi = E\psi
+            """
+            theme = None
+            raw_line = line.strip()
+            if raw_line.startswith("--theme "):
+                parts = shlex.split(raw_line)
+                if len(parts) >= 3 and parts[0] == "--theme":
+                    theme = parts[1]
+                    raw_line = " ".join(parts[2:])
+
+            if not raw_line:
+                display(Markdown("*Color Math: please provide a LaTeX expression.*"))
+                return None
+
+            # Render as display math
+            colored = colormath(raw_line, theme=theme, is_fragment=True)
+            return Math(colored)
+
+        @cell_magic("color_math")
+        @cell_magic("colormath")
+        def color_math_cell(self, line: str, cell: str) -> Any:
+            r"""Colorize and display a cell containing LaTeX or Markdown math.
+
+            Usage:
+                %%color_math
+                Here is the equation:
+                $$ \frac{df}{dx} = f'(x) $$
+            """
+            theme = None
+            args = shlex.split(line.strip()) if line.strip() else []
+            if len(args) >= 2 and args[0] == "--theme":
+                theme = args[1]
+
+            converted = colormath(cell, theme=theme, is_fragment=False)
+            display(Markdown(converted))
+
+        @line_magic("color_math_auto")
+        def color_math_auto(self, line: str) -> None:
+            """Toggle automatic semantic colorization for all IPython.display.Math outputs.
+
+            Usage:
+                %color_math_auto on
+                %color_math_auto off
+                %color_math_auto status
+            """
+            cmd = line.strip().lower()
+            if cmd in ("on", "enable", "1", "true"):
+                self.enable_auto_display()
+                print("Color Math: Automatic display coloring enabled for IPython.display.Math.")
+            elif cmd in ("off", "disable", "0", "false"):
+                self.disable_auto_display()
+                print("Color Math: Automatic display coloring disabled.")
+            else:
+                status = "ENABLED" if self._auto_hook_active else "DISABLED"
+                print(f"Color Math: Automatic display coloring is currently {status}.")
+
+        def enable_auto_display(self) -> None:
+            """Patch IPython.display.Math to automatically colorize its LaTeX payload."""
+            if self._auto_hook_active:
+                return
+            self._orig_math_repr = Math._repr_latex_
+
+            def _colorized_repr_latex(math_self: Math) -> str:
+                raw = self._orig_math_repr(math_self)  # type: ignore[misc]
+                if not raw:
+                    return raw
+                # Raw may be surrounded by $$ or not
+                if raw.startswith("$$") and raw.endswith("$$"):
+                    body = raw[2:-2]
+                    return f"$${colormath(body, is_fragment=True)}$$"
+                if raw.startswith("$") and raw.endswith("$"):
+                    body = raw[1:-1]
+                    return f"${colormath(body, is_fragment=True)}$"
+                return colormath(raw, is_fragment=True)
+
+            Math._repr_latex_ = _colorized_repr_latex  # type: ignore[assignment]
+            self._auto_hook_active = True
+
+        def disable_auto_display(self) -> None:
+            """Restore original IPython.display.Math behavior."""
+            if not self._auto_hook_active:
+                return
+            if self._orig_math_repr is not None:
+                Math._repr_latex_ = self._orig_math_repr  # type: ignore[assignment]
+            self._auto_hook_active = False
+
+
+def load_ipython_extension(ipython: Any) -> None:
+    """Standard IPython extension loader."""
+    if not HAS_IPYTHON:
+        return
+    magics = ColorMathMagics(ipython)
+    ipython.register_magics(magics)
+    # Store reference so it can be cleanly unloaded
+    ipython.custom_exceptions = getattr(ipython, "custom_exceptions", {})
+    setattr(ipython, "_color_math_magics", magics)
+
+
+def unload_ipython_extension(ipython: Any) -> None:
+    """Standard IPython extension unloader."""
+    if not HAS_IPYTHON:
+        return
+    magics = getattr(ipython, "_color_math_magics", None)
+    if magics is not None and hasattr(magics, "disable_auto_display"):
+        magics.disable_auto_display()

color_math/jupyter.py

@@ -0,0 +1,99 @@
+"""Jupyter Server & Notebook 7 integration for color-math.
+
+Provides automated pre-save formatting so that whenever a notebook is saved
+in Jupyter Notebook 7 or JupyterLab, all LaTeX formulas in Markdown cells
+are automatically colorized.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from .config import ColorMathOptions
+from .converters.block import convert_text
+from .undo import uncolor_text
+
+
+HOOK_SNIPPET = """
+# >>> color-math Jupyter pre-save hook >>>
+try:
+    from color_math.jupyter import notebook_pre_save_hook
+    c.FileContentsManager.pre_save_hook = notebook_pre_save_hook
+except ImportError:
+    pass
+# <<< color-math Jupyter pre-save hook <<<
+"""
+
+
+def notebook_pre_save_hook(
+    model: dict[str, Any],
+    os_path: str = "",
+    contents_manager: Any = None,
+    options: ColorMathOptions | None = None,
+    **kwargs: Any,
+) -> None:
+    """Jupyter FileContentsManager pre_save_hook.
+
+    Modifies the notebook model in-place before it is written to disk.
+    """
+    if model.get("type") != "notebook":
+        return
+
+    content = model.get("content")
+    if not isinstance(content, dict):
+        return
+
+    cells = content.get("cells")
+    if not isinstance(cells, list):
+        return
+
+    for cell in cells:
+        if not isinstance(cell, dict) or cell.get("cell_type") != "markdown":
+            continue
+
+        source = cell.get("source", "")
+        if isinstance(source, str):
+            joined = source
+        elif isinstance(source, list) and all(isinstance(part, str) for part in source):
+            joined = "".join(source)
+        else:
+            continue
+
+        converted = convert_text(joined, options=options)
+        if converted != joined:
+            if isinstance(source, str):
+                cell["source"] = converted
+            else:
+                cell["source"] = converted.splitlines(keepends=True) or ([""] if source else [])
+
+
+def get_jupyter_config_dir() -> Path:
+    """Locate the active Jupyter user configuration directory."""
+    env_dir = os.environ.get("JUPYTER_CONFIG_DIR")
+    if env_dir:
+        return Path(env_dir)
+    return Path.home() / ".jupyter"
+
+
+def install_jupyter_hook(config_dir: Path | str | None = None) -> Path:
+    """Install the pre-save hook into the user's Jupyter configuration."""
+    target_dir = Path(config_dir) if config_dir else get_jupyter_config_dir()
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # In modern Jupyter (Notebook 7 / JupyterLab 4), jupyter_server_config.py is preferred
+    config_file = target_dir / "jupyter_server_config.py"
+    if not config_file.exists():
+        legacy_file = target_dir / "jupyter_notebook_config.py"
+        if legacy_file.exists():
+            config_file = legacy_file
+
+    existing_content = config_file.read_text(encoding="utf-8") if config_file.exists() else ""
+    if "color_math.jupyter" in existing_content:
+        return config_file
+
+    with open(config_file, "a", encoding="utf-8") as f:
+        f.write(HOOK_SNIPPET + "\n")
+
+    return config_file

{python_color_math-0.2.12.dist-info → python_color_math-0.2.14.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-color-math
-Version: 0.2.12
+Version: 0.2.14
 Summary: A fast, local semantic LaTeX colorizer for Markdown, Jupyter, and LaTeX math equations.
 Author: Aditya
 License: MIT License
@@ -56,10 +56,13 @@ Requires-Dist: mcp>=1.0.0; extra == "mcp"
 Provides-Extra: tutorial
 Requires-Dist: rich>=13.0.0; extra == "tutorial"
 Requires-Dist: questionary>=2.0.0; extra == "tutorial"
+Provides-Extra: jupyter
+Requires-Dist: ipython>=8.0.0; extra == "jupyter"
 Provides-Extra: all
 Requires-Dist: mcp>=1.0.0; extra == "all"
 Requires-Dist: rich>=13.0.0; extra == "all"
 Requires-Dist: questionary>=2.0.0; extra == "all"
+Requires-Dist: ipython>=8.0.0; extra == "all"
 Dynamic: license-file
 
 # 🎨 Python Color Math

{python_color_math-0.2.12.dist-info → python_color_math-0.2.14.dist-info}/RECORD

@@ -1,4 +1,4 @@
-color_math/__init__.py,sha256=WfTE42IX0N4KjPXOJeIseaVrvyUwO-rehid3dwOOsp8,402
+color_math/__init__.py,sha256=t5MGubTUUxguT0lkBW4gAF83lqFYCQgMNAp9XeNRisE,591
 color_math/__main__.py,sha256=lU6t3BklI-5H9EdprlceWLr0UcDmfXUu3Th0tjk2ANA,81
 color_math/adapters.py,sha256=glMvD8Bma_865jmOvIGGkCRxQLIEGjToFDOqJy_WeWA,12293
 color_math/colormath.default.json,sha256=KmQb7BV7sMMIqPxR4x6i9RwuXuUqkpyiy4yHw84GxPQ,2756
@@ -7,6 +7,8 @@ color_math/config.py,sha256=z8Op8UzZz4D0jMaAd8GGYwAbTwqR_2ZUG4Lb9f03Ii0,20982
 color_math/custom_definitions.py,sha256=IYJ_L51d1vyFf5frbJoFMIagKRcI7TiNzELfoewZyjk,2392
 color_math/gui.py,sha256=cBsgNToQdZ7mNQ9JA5_jEv7QbELc4NGtgXowTxZ-IWQ,21413
 color_math/io.py,sha256=iCWMY1ufPZzFCwuHTn_axNetek8PRXGNnrmz59CrlGw,1591
+color_math/ipython.py,sha256=P-cvBogtb3N6NHrgr8gZcrLlbqyKO32FR9wjwNAxfBo,6929
+color_math/jupyter.py,sha256=CaCWNmtOPqUn0CVZdCie28M1324y0iU6ck2vxCvMn6w,3067
 color_math/main.py,sha256=Prk2pOGwqAlS9Yn62ACBnZv6XsQEco_NqrQYacU4kUo,34253
 color_math/mcp.py,sha256=M-JTnWC-xhJemIv2F0ZI4VBF5_MUmasid5B4PIIPgSo,1112
 color_math/mcp_server.py,sha256=AyDjwKVS-7nnaFu4hBNeBrFC542bs7_WuWosgMflvDg,16086
@@ -48,9 +50,9 @@ color_math/utils/latex_helpers.py,sha256=1cFj0zqv68mD-p0vej6yPrhwgqLfAWcIV1rX15F
 color_math/utils/spans.py,sha256=3Lq1_bN0s4vSYnS8Rz9tCHoFoJDY6Ff9CzawWWws3YE,3938
 python_color_math/__init__.py,sha256=Dj5YZXXjmNgbyhHKX2YQXvVggtB9UZy9zotLiV2j5So,329
 python_color_math/__main__.py,sha256=cqUM_fV0E6mtuHeBn2MjuozR2rlpev9AfXfcm2hSpi8,90
-python_color_math-0.2.12.dist-info/licenses/LICENSE,sha256=hveQNxqYFqK9Brs_ruH-8shF2D61hIVKYdCjiE-1wMY,1063
-python_color_math-0.2.12.dist-info/METADATA,sha256=5bhH05wLGgUGTVWeVTDwmf5q2zmEVuX2NGuikHCp2HY,14349
-python_color_math-0.2.12.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_color_math-0.2.12.dist-info/entry_points.txt,sha256=ZgzGbO_D3csr693Fd-tVGhls6WzsZiOhCau-liSkE_M,130
-python_color_math-0.2.12.dist-info/top_level.txt,sha256=dkfmCdtILDAgX4wwDW5DKHh9YRLt9Mh2RU0gh1mBDDA,29
-python_color_math-0.2.12.dist-info/RECORD,,
+python_color_math-0.2.14.dist-info/licenses/LICENSE,sha256=hveQNxqYFqK9Brs_ruH-8shF2D61hIVKYdCjiE-1wMY,1063
+python_color_math-0.2.14.dist-info/METADATA,sha256=ErCd5J70JgF4i5a0Nm1DwF1BvuMreS4AlVzEJaPdA4o,14469
+python_color_math-0.2.14.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_color_math-0.2.14.dist-info/entry_points.txt,sha256=ZgzGbO_D3csr693Fd-tVGhls6WzsZiOhCau-liSkE_M,130
+python_color_math-0.2.14.dist-info/top_level.txt,sha256=dkfmCdtILDAgX4wwDW5DKHh9YRLt9Mh2RU0gh1mBDDA,29
+python_color_math-0.2.14.dist-info/RECORD,,