Metadata-Version: 2.4
Name: bitool_core
Version: 0.1.15
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Requires-Dist: maturin>=1.0,<2.0
Summary: Bitool-Core - Rust core for Bitool
Author-email: gooker_young <gooker_young@qq.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Bitool-core

Bitool 的 Rust 核心模块，通过 [PyO3](https://pyo3.rs) + [Maturin](https://www.maturin.rs) 将高性能 Rust 实现暴露为 Python 可调用的扩展模块。

## 定位

Bitool 采用 Rust + Python 混合架构，`bitool-core` 负责处理**性能关键路径**上的计算密集型任务：

| 模块 | 功能 | 关键依赖 |
|------|------|----------|
| `file_ops` | 文件扫描、目录遍历、文件操作 | `walkdir`, `rayon` |
| `text_proc` | 正则搜索、文本处理 | `regex`, `rayon` |
| `pdf_ops` | PDF 合并、拆分、压缩、页面转图片 | `lopdf`, `pdfium-render`, `image` |
| `crypto` | AES 加密/解密、SHA2 哈希 | `aes`, `sha2` |
| `cmd_exec` | 外部命令执行 | `tokio` |
| `profiler` | 高精度性能分析 | `chrono` |
| `config` | 全局配置管理 | `serde`, `serde_json`, `dirs` |

## 安装

### 作为 Bitool 的一部分安装

```bash
pip install bitool
```

### 开发模式安装

```bash
cd bitool-core
maturin develop
```

### 构建发布包

```bash
cd bitool-core
maturin build -r
```

## Python API

安装后通过 `import bitool_core` 即可使用所有 Rust 实现的功能：

### 配置管理

```python
import bitool_core

# 全局配置
config = bitool_core.PyBitoolConfig()
config.get("key", "default_value")

# 工作区配置
ws_config = bitool_core.PyWorkspaceConfig()
ws_config.workspace_path = "/path/to/project"
```

### 文件操作

```python
import bitool_core

ops = bitool_core.PyFileOps()

# 扫描目录
files = ops.scan_directory("/path/to/dir")

# 文件读写
content = ops.read_file("input.txt")
ops.write_file("output.txt", content)

# 文件复制/移动/删除
ops.copy_file("src.txt", "dst.txt")
ops.move_file("old.txt", "new.txt")
ops.delete_file("temp.txt")
```

### 文本处理

```python
import bitool_core

processor = bitool_core.PyTextProcessor()

# 正则搜索
results = processor.regex_search(r"\d{4}-\d{2}-\d{2}", text)

# 文本替换
new_text = processor.regex_replace(pattern, replacement, text)

# 批量处理（利用 rayon 并行加速）
results = processor.batch_search(patterns, texts)
```

### PDF 操作

```python
import bitool_core

pdf = bitool_core.PyPdfOps()

# 合并 PDF
pdf.merge_pdfs(["part1.pdf", "part2.pdf"], "merged.pdf")

# 拆分 PDF
pdf.split_pdf("input.pdf", "output_dir", pages_per_split=10)

# 压缩 PDF
pdf.compress_pdf("large.pdf", "small.pdf")

# PDF 转图片
images = pdf.to_images("document.pdf", dpi=150, format="png")
```

### 加密功能

```python
import bitool_core

# AES 加密/解密
encrypted = bitool_core.encrypt(data, key)
decrypted = bitool_core.decrypt(encrypted, key)

# SHA2 哈希
hash_value = bitool_core.sha256(data)
```

### 命令执行

```python
import bitool_core

executor = bitool_core.PyCommandExecutor()

# 执行外部命令
result = executor.run("git status")
print(result.stdout)
print(result.return_code)

# 异步执行（基于 tokio）
result = executor.run_async("long_running_command")
```

### 性能分析

```python
import bitool_core

profiler = bitool_core.PyPerformanceProfiler()

# 计时
profiler.start("task_name")
# ... 执行任务 ...
record = profiler.stop("task_name")

print(f"耗时: {record.elapsed_ms:.2f} ms")

# 获取所有记录
all_records = profiler.records
```

## 项目结构

```
bitool-core/
├── src/
│   ├── lib.rs                 # 库入口，注册所有 PyO3 模块
│   ├── core/                  # Rust 核心实现
│   │   ├── mod.rs             #   模块聚合
│   │   ├── cmd_exec.rs        #   外部命令执行（tokio 异步）
│   │   ├── config.rs          #   配置管理（serde 序列化）
│   │   ├── crypto.rs          #   加密功能（AES-256 / SHA2）
│   │   ├── file_ops.rs        #   文件操作（rayon 并行）
│   │   ├── pdf_ops.rs         #   PDF 处理（lopdf / pdfium-render）
│   │   ├── profiler.rs        #   高精度性能分析
│   │   └── text_proc.rs       #   文本处理（regex / rayon）
│   ├── plugins/               # 插件系统
│   │   ├── mod.rs             #   插件框架
│   │   ├── loader.rs          #   动态插件加载
│   │   └── registry.rs        #   插件注册表
│   └── python/                # PyO3 Python 绑定
│       ├── mod.rs             #   绑定聚合
│       ├── py_cmd_exec.rs     #   命令执行器绑定
│       ├── py_config.rs       #   配置管理绑定
│       ├── py_file_ops.rs     #   文件操作绑定
│       ├── py_pdf_ops.rs      #   PDF 操作绑定
│       ├── py_profiler.rs     #   性能分析器绑定
│       └── py_text_proc.rs    #   文本处理器绑定
├── .cargo/
│   └── libs/                  # 链接库
├── Cargo.toml                 # Rust 依赖配置
└── pyproject.toml             # Maturin 构建配置
```

## 技术栈

| 组件 | 技术 | 用途 |
|------|------|------|
| Python 绑定 | [PyO3](https://pyo3.rs) 0.28 | Rust ↔ Python FFI |
| 构建工具 | [Maturin](https://www.maturin.rs) | Rust Python 包构建 |
| 并行计算 | [Rayon](https://github.com/rayon-rs/rayon) | 数据并行处理 |
| 异步运行时 | [Tokio](https://tokio.rs) | 异步命令执行 |
| 正则引擎 | [regex](https://github.com/rust-lang/regex) | 高性能正则匹配 |
| 序列化 | [serde](https://serde.rs) + serde_json | JSON 配置序列化 |
| 加密 | [aes](https://github.com/RustCrypto/AES) + [sha2](https://github.com/RustCrypto/hashes) | AES-256 加密 / SHA2 哈希 |
| PDF 处理 | [lopdf](https://github.com/J-F-Liu/lopdf) + [pdfium-render](https://github.com/aldanor/pdfium-render) | PDF 读写与渲染 |
| 图像处理 | [image](https://github.com/image-rs/image) | 图像编解码 |
| 目录遍历 | [walkdir](https://github.com/TheDan64/walkdir) | 递归目录扫描 |

## 许可证

MIT License

