Metadata-Version: 2.4
Name: math-step-to-step
Version: 0.2.0
Summary: Step-by-step solutions for math expressions and equations (1 + 2 x 3 -> ['1 + 6', '7']), plus text-to-symbol helpers (6^6 -> 6⁶).
Author: VVT
License-Expression: MIT
Keywords: math,steps,solver,equation,calculator,superscript,education
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Education
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: gui
Requires-Dist: pillow>=10.1; extra == "gui"
Requires-Dist: customtkinter>=5.2; extra == "gui"
Dynamic: license-file

# math-step-to-step

Giải biểu thức / phương trình **từng bước** và trả về danh sách các bước.
Không phụ thuộc thư viện ngoài, dùng phân số chính xác (`fractions.Fraction`) nên không bị sai số.

*Step-by-step solver for math expressions and equations. Pure Python, zero dependencies, exact arithmetic.*

```bash
pip install math-step-to-step
```

## Dùng nhanh

```python
from math_step_to_step import steps, solve, evaluate, prettify

steps("1 + 2 x 3")              # ['1 + 6', '7']
steps("(1 + 2) x 3 + 4 x 5")    # ['3 × 3 + 4 × 5', '9 + 20', '29']
steps("2 + 3 x (4 - 1)^2")      # ['2 + 3 × 3²', '2 + 3 × 9', '2 + 27', '29']
steps("1/2 + 1/3")              # ['1/2 + 1/3', '5/6']

# tìm x
steps("2x + 3 = 7")             # ['2x = 7 - 3', '2x = 4', 'x = 4 ÷ 2', 'x = 2']
steps("2(x + 3) = 10")          # ['2x + 6 = 10', '2x = 10 - 6', '2x = 4', 'x = 4 ÷ 2', 'x = 2']
steps("x^2 - 3x + 2 = 0")       # a, b, c -> Δ -> x₁, x₂ (từng bước)

# kết quả có cấu trúc
sol = solve("x^2 - 3x + 2 = 0")
sol.kind, sol.values            # ('roots', (2, 1))

evaluate("2 + 3 x 4")           # 14   (nhanh, không tạo chuỗi bước)

# đổi chuỗi thành ký hiệu
prettify("6^6")                 # '6⁶'
prettify("x^2 + y^(n+1) <= sqrt(2)*pi")   # 'x² + yⁿ⁺¹ ≤ √2×π'
prettify("a//b")                # 'ᵃ√b'  (căn bậc a của b)
prettify("(a/b)")               # 'a⁄b'  (a phần b);  prettify("(3/7)") -> '³⁄₇'
prettify("a^b^c")               # 'aᵇᶜ'  (lũy thừa chồng lũy thừa)
prettify("a**")                 # 'a▫'   (thiếu số mũ -> ô vuông rỗng)
```

## Cú pháp nhập

| Viết | Ý nghĩa |
|---|---|
| `+ - * x × · / ÷ :` | cộng, trừ, nhân, chia |
| `x` giữa hai toán hạng, vd `2 x 3` | **phép nhân**; còn `2x`, `x + 1`, `x²` thì `x` là **biến** |
| `^`, `**`, `²` `³` | lũy thừa (số mũ nguyên) |
| `sqrt(…)`, `√9`, `//9` | căn bậc hai |
| `a//b` | căn bậc **a** của **b** (`3//27` = 3) |
| `(a/b)` | phân số "a phần b" (hai vế là một số/biến/lũy thừa/nhóm trong ngoặc, vd `((1+2)/(3+4))`) |
| `pi`, `π` | số π = 3.14159265359 (`2pi`, `a*pi`, `api` = a × π) |
| `( )`, `[ ]`, `{ }` | ngoặc |
| `2x`, `3(x+1)`, `(a)(b)` | nhân ngầm |
| `1,5` hoặc `1.5` | số thập phân |
| `=` | phương trình (1 biến, bậc 1 hoặc 2) |

## Tùy chọn của `steps()` / `solve()`

| Tham số | Mặc định | Ý nghĩa |
|---|---|---|
| `include_original` | `False` | thêm biểu thức gốc làm bước đầu |
| `detailed` | `False` | mỗi bước chỉ làm 1 phép (`1+2+3` → `3 + 3` → `6`) thay vì gộp |
| `pretty` | `True` | dùng `× ÷ ² √`; `False` ra ASCII (`* / ^ sqrt()`), có thể đưa lại vào thư viện |
| `style` | `"auto"` | `"fraction"`, `"decimal"` hoặc `"auto"` (thập phân nếu đầu vào có số thập phân) |
| `lang` | `"vi"` | ngôn ngữ thông báo: `"vi"` / `"en"` |

Cách chọn bước: ngoặc trước → lũy thừa/căn → nhân chia → cộng trừ; các phép độc lập được làm **cùng một bước**
và chuỗi cộng/nhân liên tiếp được gộp để lời giải ngắn nhất. Với phương trình: rút gọn → chuyển vế → chia hệ số;
bậc 2 dùng Δ.

## Ký hiệu

`prettify()` đổi `^`→mũ trên, `a//b`→`ᵃ√b`, `(a/b)`→`a⁄b`, thiếu phần nào thì hiện `▫`
(đổi được bằng `placeholder="□"`). Mũ chồng mũ `a^b^c` hiện `aᵇᶜ`; với số như `2^3^2`
sẽ hiện `2³²` (dễ đọc nhầm), nên khi cần rõ ràng hãy dùng `steps("2^3^2", include_original=True)`
→ `2^(3²)`.

```python
from math_step_to_step import superscript, subscript, prettify
superscript("123")        # '¹²³'
subscript("12")           # '₁₂'
prettify("H_2O, 6^6, x^(n+1), 1/2, a<=b, a!=b, +-3, alpha")
# 'H₂O, 6⁶, xⁿ⁺¹, ½, a≤b, a≠b, ±3, α'
```

## Hiển thị như trong sách giáo khoa (CTkLabel)

`prettify()` chỉ đổi sang ký tự Unicode nên mũ/phân số/căn bị giới hạn bởi font. Muốn đúng ký hiệu
lớp học (phân số có gạch ngang, mũ & chỉ số thật, căn có gạch trên đầu, ngoặc co giãn theo chiều cao,
biến in nghiêng) thì dùng `MathLabel` — bản thân nó là một `CTkLabel` (biểu thức được vẽ thành ảnh
rồi gán vào `image=`, tự đổi màu sáng/tối, nét sắc trên màn hình HiDPI, kèm sẵn font STIX nên máy nào cũng giống nhau):

```bash
pip install "math-step-to-step[gui]"      # pillow + customtkinter
```

```python
import customtkinter as ctk
from math_step_to_step import steps
from math_step_to_step.mathlabel import MathLabel

root = ctk.CTk()
MathLabel(root, "x_1 = (-b +- sqrt(b^2 - 4ac)) / (2a)", font_size=26).pack(padx=20, pady=20)
for st in steps("2 + 3 x (4 - 1)^2", pretty=False):      # pretty=False: ASCII, dễ vẽ nhất
    MathLabel(root, st).pack(anchor="w", padx=20)
root.mainloop()
```

Cú pháp giống `prettify` (và nhận cả đầu ra Unicode của `steps()` như `x²`, `√3`, `³√8`):

| Viết | Hiện |
|---|---|
| `(a/b)`, `a/b`, `(x+1)/(x-1)`, `(3+1) / 2` | phân số xếp chồng (không có chuỗi `a/b/c`) |
| `(1/2)^2`, `3(1/2)` | giữ ngoặc, ngoặc tự cao theo phân số |
| `x^2`, `x^(n+1)`, `a^b^c` | mũ thật; `a^b^c` = tháp mũ a^(b^c) |
| `x_1`, `x_(n+1)`, `x_1^2` | chỉ số dưới / cả hai |
| `sqrt(x)`, `//x`, `√x`, `a//b` | căn có gạch trên đầu; `a//b` có chỉ số căn |
| `*`, `-`, `<=`, `>=`, `!=`, `+-`, `=>`, `pi` | `×`, `−`, `≤`, `≥`, `≠`, `±`, `⇒`, `π` |
| `a^`, `a**`, `a//`, `(a/)` | thiếu phần nào hiện ô vuông rỗng □ |

Đổi nội dung: `label.set_math("...")` hoặc `label.configure(math=..., font_size=..., text_color=("#000", "#fff"))`.
Chỉ cần ảnh (PIL) thì dùng `from math_step_to_step.mathrender import render_math`.
Chạy thử: `python examples/gui_demo.py`.

## Giới hạn (cố ý, để ít lỗi)
Một biến; phương trình bậc ≤ 2; số mũ nguyên; không có số phức; không rút gọn căn phức tạp
(căn không chính phương được rút gọn dạng `2 × √3` và cho giá trị gần đúng). Đầu vào sai/không hỗ trợ
luôn ném `MathStepError` (kế thừa `ValueError`) với thông báo rõ ràng.

## Dòng lệnh

```bash
math-step-to-step "(1 + 2) x 3 + 4 x 5"
python -m math_step_to_step "2x + 3 = 7" --en
```

MIT License.
