Metadata-Version: 2.1
Name: srndcipher
Version: 0.7.0
Summary: A simple way to encode plain text, keeps the result sortable and partly searchable.
Home-page: https://gitee.com/rRR0VrFP/srndcipher
Author: rRR0VrFP
Author-email: rrr0vrfp@qq.com
Maintainer: rRR0VrFP
Maintainer-email: rrr0vrfp@qq.com
License: MIT
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

# 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 | arm64 |
| Windows | AMD64, ARM64 |

## 本地构建

### macOS

```bash
./build.sh
```

### Windows

```bat
build.bat
```

### 国内网络说明

Linux 构建依赖 `quay.io/pypa/manylinux_*` 镜像（约 2GB），`build.sh` / `build.bat` 已通过 `CIBW_MANYLINUX_*_IMAGE` 环境变量配置了国内代理 `dockerproxy.com`，无需额外配置即可使用。

如果代理不可用，也可在容器引擎中配置 registry mirror（以 Podman 为例）：

```
# ~/.config/containers/registries.conf.d/mirror.conf
[[registry]]
prefix = "quay.io/pypa"
location = "dockerproxy.com/quay.io/pypa"
```

## 发布记录

### 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。
