Metadata-Version: 2.4
Name: python-color-math
Version: 0.2.0
Summary: A fast, local semantic LaTeX colorizer for Markdown, Jupyter, and LaTeX math equations.
Author: Aditya
License: MIT License
        
        Copyright (c) 2026 Aditya
        
        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.
        
Project-URL: Homepage, https://github.com/36ty-blip/python-color-math
Project-URL: Documentation, https://github.com/36ty-blip/python-color-math#readme
Project-URL: Repository, https://github.com/36ty-blip/python-color-math
Project-URL: Issues, https://github.com/36ty-blip/python-color-math/issues
Project-URL: Changelog, https://github.com/36ty-blip/python-color-math/releases
Keywords: obsidian,latex,math,markdown,jupyter,colorizer,katex,mathjax,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 🎨 Python Color Math

> Semantic color for LaTeX equations in Markdown, Jupyter notebooks, and native TeX documents — without handing your notation to a computer algebra system.

`python-color-math` parses mathematical expressions and inserts MathJax/KaTeX-compatible `\textcolor{...}{...}` wrappers. It operates completely locally, preserves existing LaTeX structure, and leaves prose, fenced code, TeX comments, and `\verb` payloads untouched.

---

## 🌈 Before & After

**Input:**
```latex
$$ \frac{d}{dx} f(g(y)) = f'(g(y)) \cdot g'(y)y' $$
```

**Output:**
```latex
$$ \frac{d}{dx}\textcolor{#7aa2f7}{f(g(y))} \textcolor{white}{=} \textcolor{#bb9af7}{f'(g(y))}\textcolor{white}{\cdot} \textcolor{#9ece6a}{g'(y)}\textcolor{#9ece6a}{y'} $$
```

---

## 🚀 Quick Start

### Installation

```bash
pip install python-color-math
```

*(Or locally from cloned source: `pip install -e .`)*

> [!TIP]
> **Commands & PATH**:
> - Registers both the short **`color-math`** and full **`python-color-math`** commands.
> - If Python's `Scripts/` folder is not on your `PATH`, run directly via Python without touching environment variables:
>   `python -m color_math [options]` *(or `python -m python_color_math`)*.
> - *Linux users*: Python's standard GUI library is available via `sudo apt install python3-tk`.

---

## ⚡ Three Ways to Use

### 1. 🎓 Interactive Terminal Tutorial
New to Color Math? Take the 2-minute paced CLI tour with live examples:
```bash
color-math --tutorial
```

### 2. 🖥️ Graphical Pop-up Window (GUI)
Prefer visual controls? Launch the native High-DPI pop-up window:
```bash
color-math --ui
# or:
color-math --gui
```
- **Preview vs Write Toggle**: Inspect diffs safely or write directly to disk.
- **Visual Color Picker**: Click color chips to select custom hex values.
- **Theme & Preset Selectors**: Switch curated palettes and engine toggles in 1 click.
- **1-Click Reset**: Restore factory Tokyo Night defaults anytime.

### 3. ⌨️ Fast Terminal Commands
```bash
# Safe preview in terminal (leaves notes unchanged)
color-math note.md

# Save changes directly back to the note
color-math note.md -w

# Process an entire folder recursively
color-math notes/ -r -w

# Color a raw LaTeX string directly
color-math "$$\frac{d}{dx} x^2 = 2x$$"

# Read and color from standard input pipeline
cat note.md | color-math -

# Inspect syntax-colored unified diff without touching disk
color-math note.md --diff
```

---

## 📋 Cheat Sheet (Command Reference)

| Task | Command | Description |
| :--- | :--- | :--- |
| **Visual Window** | `color-math --ui` *(or `--gui`)* | Open interactive High-DPI GUI |
| **Interactive Tour** | `color-math --tutorial` | 2-minute interactive terminal guide |
| **Preview** | `color-math note.md` | Safe preview (leaves disk untouched) |
| **Save / Write** | `color-math note.md -w` *(or `-i`)* | Write changes in-place |
| **Batch Folder** | `color-math notes/ -r -w` | Recursively color directory |
| **Unified Diff** | `color-math note.md --diff` | Inspect exact line changes (colorized) |
| **Linter / CI Mode** | `color-math notes/ -r --check` | Exit `0` if clean, `1` if notes need coloring |
| **Machine JSON** | `color-math notes/ -r --check --json` | Structured JSON output for CI and pipelines |
| **Stdin Pipeline** | `cat note.md \| color-math -` | Read and color math from standard input |
| **Curated Themes** | `color-math note.md --theme catppuccin -w` | Select `default`, `catppuccin`, `nord`, or `light` |
| **Feature Preset** | `color-math note.md --preset minimal -w` | Presets: `all` (default), `minimal` |
| **Custom Colors** | `color-math note.md -c unit=#73daca -w` | Override any of 12 individual color roles |
| **Reset Palette** | `color-math --reset-colors` | Restore factory Tokyo Night palette |
| **Inspect Colors** | `color-math --show-colors` | Display palette, descriptions, & terminal swatches |
| **Undo / Strip** | `color-math note.md --undo -w` | Strip color wrappers back to plain LaTeX |
| **Export Config** | `color-math --init-config` | Generate a documented `.colormath.json` |

---

## 🧠 Engine Features & Disambiguation

Control recognition features with `--preset {all,minimal}` (default: `all`) or individual flags:

- **Calculus Differentials (`--differentials`)**: Disambiguates `dx`, `dt`, `d\theta`, and derivatives (`\frac{d}{dx}`, `\frac{\partial \psi}{\partial t}`) while leaving standalone distance variables `$d$` untouched.
- **Physical Units (`--units`)**: Recognizes metric prefixes and unit compounds (`\mu m`, `m/s`, `kg`, `nm`).
- **Rainbow Delimiters (`--rainbow-delimiters`)**: Recursively colors nested brackets `()`, `[]`, `{}` by depth to eliminate delimiter blindness.
- **Quantum Bra-Ket (`--braket`)**: Dirac notation (`|\psi\rangle`, `\langle\phi|`, `\langle\phi|\psi\rangle`).
- **Dimensionless Groups (`--dimensionless`)**: Recognizes engineering numbers (`Re`, `Ma`, `Pr`, `Nu`).
- **Semantic Taxonomy (`--taxonomy`)**: Colors constants ($\pi, \hbar, \infty$), Greek parameters ($\alpha, \theta$), and standard functions ($\sin, \cos, \ln$).
- **Variable Data-Flow (`--variable-data-flow`)**: Deterministically hashes variable names to track variable flow across equations.

---

## 📁 Supported File Formats

`python-color-math` automatically detects file formats by extension:
- **Markdown**: `.md`, `.markdown`, `.qmd` (Quarto)
- **Jupyter Notebooks**: `.ipynb` (transforms only Markdown cells)
- **Native LaTeX**: `.tex`, `.latex` (adds `\usepackage{xcolor}` compatibility)
- **Anki Flashcards**: `.tsv`, `.txt` (select via `--format anki`)

---

## ↩️ Complete Reversibility (Undo)

Never worry about locking your documents into color wrappers:
```bash
# Preview what plain LaTeX would look like
color-math note.md --undo

# Restore plain LaTeX back to disk
color-math note.md --undo -w

# Strip colors from an entire vault
color-math notes/ -r --undo -w
```
*Undo cleanly removes generated `\textcolor{...}{...}` and compatible legacy `\color{...}{...}` wrappers.*

---

## 🐚 Shell Autocompletion

Generate fast, native completions with full support for all flags, themes, presets, and file formats:

```bash
# Bash
color-math --generate-completion bash >> ~/.bash_completion

# Zsh
color-math --generate-completion zsh > ~/.zsh/completion/_color-math

# Fish
color-math --generate-completion fish > ~/.config/fish/completions/color-math.fish

# PowerShell
color-math --generate-completion powershell | Out-String | Invoke-Expression
# Or persist to your $PROFILE:
Add-Content $PROFILE "`ncolor-math --generate-completion powershell | Out-String | Invoke-Expression"
```

---

## 🪝 Pre-commit Integration

Integrate `color-math` into your git workflow using [pre-commit](https://pre-commit.com):

```yaml
repos:
  - repo: https://github.com/36ty-blip/color-math
    rev: v0.2.0
    hooks:
      # Formatter: colorizes modified Markdown, LaTeX, and Jupyter files in-place
      - id: color-math
      # Linter: verifies math formatting without modifying files (fails if uncolored)
      # - id: color-math-check
```

---

## ⚙️ Configuration & Standards

`python-color-math` adheres to modern CLI standards ([clig.dev](https://clig.dev/)):
- **Config Hierarchy**: `--config <file>` > `./.colormath.json` (project local) > Global user config (`%APPDATA%\color-math\config.json` on Windows or `~/.config/color-math/config.json` on Linux/macOS) > Factory defaults.
- **Color Standards**: Honors `NO_COLOR` ([no-color.org](https://no-color.org)), `FORCE_COLOR`, and `TERM=dumb`.
- **CI / Pre-commit**: Combine `--check --json` for structured reporting in automated pipelines.

---

## 🤝 Obsidian Companion Plugin

Looking for dynamic real-time equation coloring inside Obsidian without modifying notes on disk? Check out the sister plugin:
👉 [**Obsidian Color Math**](https://github.com/36ty-blip/obsidian-color-math) *(Pure TypeScript, runs natively on Obsidian Desktop & Mobile).*

---

## 📄 License

Released under the [MIT License](LICENSE).
