Metadata-Version: 2.4
Name: ctb
Version: 0.2.0
Summary: 化学工具箱核心库：化学方程式配平 + 相对原子/分子质量计算
Author: 123IOPjklbnm
License: MIT License
        
        Copyright (c) 2026 123IOPjklbnm
        
        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/123IOPjklbnm/Chemistry-Toolbox
Project-URL: Repository, https://github.com/123IOPjklbnm/Chemistry-Toolbox
Project-URL: Issues, https://github.com/123IOPjklbnm/Chemistry-Toolbox/issues
Keywords: chemistry,balancer,equation,mass,ctb
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# ctb

化学工具箱核心库。目前提供：

- **`balance(equation)`** — 化学方程式配平（支持离子）
- **`mass(name, mode=1)`** — 相对原子 / 分子质量计算

## 安装

```bash
pip install ctb
```

## 用法

### 配平方程式

```python
from ctb import balance

balance("H2+O2=H2O")                 # '2H2+O2=2H2O'
balance("Fe2O3+CO=Fe+CO2")           # 'Fe2O3+3CO=2Fe+3CO2'
balance("H^1++OH^1-=H2O")            # 'H^1++OH^1-=H2O'
balance("CO3^2-+H^1+=HCO3^1-")       # 'CO3^2-+H^1+=HCO3^1-'
```

### 计算相对原子 / 分子质量

```python
from ctb import mass

# mode=1（默认）：精确值
mass("H")               # 1.008
mass("Ag")              # 107.87
mass("CO2")             # 44.009
mass("Fe2(SO4)3")       # 399.858

# mode=2：近似值（四舍五入，氯除外为 35.5）
mass("H", 2)            # 1.0
mass("CO2", 2)          # 44.0
mass("NaCl", 2)         # 58.5   ← 氯按 35.5 处理
mass("Fe2(SO4)3", 2)    # 400.0
```

## 输入格式

| 符号 | 含义 |
|------|------|
| `=` / `->` / `→` | 反应箭头（配平用） |
| `+` | 分隔化合物 |
| `^n+` | 带 n 个正电荷（如 `H^1+`、`Fe^3+`） |
| `^n-` | 带 n 个负电荷（如 `CO3^2-`） |
| `()` / `[]` | 支持括号，可嵌套 |
| 大小写 | 严格区分，如 `Co`（钴）≠ `CO`（一氧化碳） |

## API

### `balance(equation: str) -> str`

返回配平后的方程式字符串（不含空格）。失败抛 `ValueError`。

### `mass(name: str, mode: int = 1) -> float`

返回相对原子质量 / 相对分子质量（float，保留 4 位小数）。

- `mode=1`：精确值
- `mode=2`：近似值（四舍五入到整数，Cl 固定为 35.5）

失败抛 `ValueError`（无效化学式 / 非法 mode）或 `KeyError`（未知元素）。

## 更新日志

### v0.2.0
- 新增 `mass(name, mode=1)` 函数
- 相对原子质量改用 IUPAC 精确值

### v0.1.0
- 首个版本，提供 `balance(equation)`

## 许可证

MIT © 2026 123IOPjklbnm
