Metadata-Version: 2.4
Name: pyczan
Version: 0.1.0
Summary: C++ high-performance Python acceleration toolkit
Author-email: zan <13667605889@139.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# pyczan

**Windows 多进程共享内存，dict 即用，零配置。**

```python
from pyczan import shmem

d = shmem.Dict()
d.OpenOrCreate("config")

# 和普通 dict 一样用
d["host"] = "localhost"
d["port"] = 8080          # 自动类型
d["ratio"] = 0.95         # int/float/bytes/dict 都支持
d["cfg"] = {"key": "val"} # 自动 pickle

print(d["host"])           # "localhost"
print(len(d))              # 3
del d["port"]
print("host" in d)         # True
d.Close()
```

---

## 为什么用 pyczan？

### 跨进程共享，不需要 Redis

```
两个 Python 进程要共享数据：
  Redis      → 要装服务、配置、占端口
  Manager()  → 慢 10-35x（序列化+pipe）
  文件        → 没同步、要轮询
  raw shmem  → 只有 bytes，自己管索引

  pyczan     → pip install，dict 即用
```

### 性能

```
                写入 10 条 × 10B          写入 100 条 × 10B         写入 10 条 × 100KB
                写/读                    写/读                     写/读
pyczan          0.0000/0.0000            0.0002/0.0000             0.0005/0.0001
Manager()       0.0022/0.0003  (慢 55x)  0.0035/0.0025  (慢 18x)   0.0022/0.0012  (慢 4x)
file JSON       0.0001/0.0001  (慢 3x)   0.0003/0.0001  (慢 2x)    0.0029/0.0014  (慢 6x)
file pickle     0.0001/0.0000  (同层)    0.0001/0.0001  (同层)     0.0004/0.0001  (同层)
raw shmem       0.0000/0.0000  (同层)    0.0001/0.0001  (同层)     0.0005/0.0000  (同层)
```

pyczan 与原始共享内存性能相当，大幅快于 Manager() 和 JSON 文件 IPC。
与 pickle 文件相比在大数据量下持平，小数据量略优。

### numpy 零拷贝

```python
buf = d.Alloc(24 * 1024 * 1024)     # 24MB 连续内存
arr = np.frombuffer(buf, dtype=np.uint8)  # 零拷贝
```

---

## 安装

```bash
pip install pyczan
```

需要 Windows 10/11 64 位 + Python 3.8+。

## 使用

```python
from pyczan import shmem

d = shmem.Dict()
d.OpenOrCreate("config", total_size=1024*1024*1024)

# dict 协议：自动类型
d["count"] = 42                # int
d["ratio"] = 3.14              # float
d["data"] = b"\x00\x01\xff"   # bytes
d["user"] = {"name": "zan"}    # dict → pickle

# 零拷贝缓冲区
buf = d.Alloc(1024 * 1024)
arr = np.frombuffer(buf, dtype=np.uint8)
# ... 写入数据 ...
d.Free(buf)

# 状态监控
print(d.Status())
# → {"entries": 5, "total_blocks": 61440, "used_blocks": 12, ...}

# 崩溃后恢复
if d.Status()["was_crashed"]:
    print("注意：检测到上次异常退出，数据已被保留")
    print("如有需要可调用 d.Clear() 手动清空")

d.Close()
```

## 文档

| 文档 | 说明 |
|------|------|
| [API 参考](doc/api.md) | 完整 API 文档，含参数、返回值、异常 |
| [使用教程](doc/tutorial.md) | 从入门到生产，含多进程实战、性能调优 |
| [设计文档](doc/pyczan_shmem%20设计文档.md) | 架构设计、算法、数据布局（旧版，仅供参考） |

## 开发

从源码构建：

```bash
git clone https://gitee.com/weiyunnote/pyczan.git
cd pyczan
src\cpp\build_release.bat
pytest tests\test_shmem.py -v
```

需要 VS2022（MSVC v143）。

## 许可证

MIT
