Metadata-Version: 2.4
Name: srndcipher
Version: 0.7.0
Summary: A simple way to encode plain text, keeps the result sortable and partly searchable.
Author-email: rRR0VrFP <rrr0vrfp@qq.com>
Maintainer-email: rRR0VrFP <rrr0vrfp@qq.com>
License: MIT
Project-URL: Homepage, https://gitee.com/rRR0VrFP/srndcipher
Project-URL: Bug Tracker, https://gitee.com/rRR0VrFP/srndcipher/issues
Project-URL: Source, https://gitee.com/rRR0VrFP/srndcipher
Keywords: cipher,SrndCipher,result sortable and partly searchable
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.14
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: zenutils
Dynamic: license-file

# srndcipher

一种简单的文本编码方案，编码后保持字符串的相对排序不变，允许局部搜索。

> **⚠️ 这不是安全加密方案。** 本库不提供任何机密性、完整性或身份验证保障，**不可用于保护敏感数据**。它是有确定性的字节编码，在混淆内容的同时保持排序和搜索能力 — 适用于日志、调试输出等非安全场景的数据混淆。

## 算法原理

每个字节值（0-255）被映射为一个唯一的随机字符串（seed）。编码时将每个字节替换为对应的 seed，解码时按最长匹配拆分还原。

为了保持搜索结果的可嵌入性（每个字节的编码结果必须是整体编码结果的子串），seed 的生成需满足以下约束：

- 每个 seed 不能是另一个 seed 的子串
- 任意两个 seed 的相邻首尾字符拼接后，不能成为第三个 seed 的子串

这些约束使得编码后每个字节的密文片段可以被独立搜索定位，同时整体排序保持不变。

## 安装

```shell
pip install srndcipher
```

## 使用

```python
import os
import srndcipher

cipher1 = srndcipher.SrndCipher(password="Your password")
data1 = os.urandom(1024)
data2 = cipher1.encrypt(data1)
data3 = cipher1.decrypt(data2)
assert data1 == data3

cipher2 = srndcipher.SrndCipher(password="Your password", force_text=True)
data1 = "your plain message"
data2 = cipher2.encrypt(data1)
data3 = cipher2.decrypt(data2)
assert data1 == data3
```

## 性能

从 v0.7.0 开始，seed 生成的热路径使用 C++ 原生扩展实现。

| 版本 | Seed 生成耗时 | 加速比 |
|---|---|---|
| **v0.7.0+ (C++ 原生)** | **~38ms** | **6.3x** |
| v0.6.x (纯 Python) | ~240ms | 1x |

C++ 扩展在从 wheel 安装或从源码编译时自动启用。当扩展不可用时，自动回退到纯 Python 实现。

## 支持平台

提供预编译 wheel：

| 平台 | 架构 |
|---|---|
| Linux | x86_64, aarch64 |
| macOS | x86_64, arm64, universal2 |
| Windows | AMD64, ARM64 |

## 本地构建

```bash
# macOS wheels
./build-macos.sh

# Linux wheels (需要 podman)
./build-linux.sh

# Windows wheels (macOS 交叉编译，供本地验证)
./build-win.sh

# 源码包
./build-src.sh
```

> macOS 上的 `build-win.sh` 通过 mingw-w64 + llvm-mingw 交叉编译生成 Windows wheel，**仅用于本地验证**。正式发布使用独立的 `build-win.ps1`（x86_64）/ `build-arm64.ps1`（ARM64），在 Windows CI 上以 MSVC 编译，开发完成后会并入代码库。

## 发布记录

### v0.5.0

- 首次发布。

### v0.6.2

- 默认编码器设为 cipherutils.Utf8Encoder()。
- 适配 fastutils>=0.42.11。

### v0.6.3

- 文档更新。
- 依赖迁移至 zenutils。

### v0.6.4

- 文档更新。

### v0.7.0

- C++ 原生扩展加速 seed 生成（~6x 提升）。
- 使用 pyproject.toml + cibuildwheel 多平台打包。
- 支持 Python 3.8 ~ 3.14。
