Metadata-Version: 2.4
Name: PKIPC
Version: 5.0.0
Summary: Standard-stream event channel for Python numerical executables
License-File: licenses/libuv.txt
License-File: licenses/nlohmann-json.txt
License-File: licenses/pybind11.txt
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.11
Provides-Extra: test
Requires-Dist: pytest>=8.2; extra == "test"
Requires-Dist: ruff>=0.12; extra == "test"
Requires-Dist: requests<3,>=2.32; extra == "test"
Provides-Extra: build
Requires-Dist: build>=1.2; extra == "build"
Provides-Extra: release
Requires-Dist: twine<8,>=6.2; extra == "release"
Requires-Dist: requests<3,>=2.32; extra == "release"
Requires-Dist: auditwheel<7,>=6.8; sys_platform == "linux" and extra == "release"
Requires-Dist: patchelf>=0.17.2; sys_platform == "linux" and extra == "release"
Description-Content-Type: text/markdown

# PKIPC 5 — Python

Python 数值程序的标准流事件通道，公开接口与 C++ v5 一致：`Channel()`、
`send(event, data=None)`、`stopping()`。Python 原生扩展直接编译 C++ 仓库的
`Channel.cpp`、公开头和 nlohmann/json 3.12.0，静态链接同版 libuv 1.51.0。
序号、管道、取消读取、背压与 IO 线程由这份 C++ 实现拥有。

```python
from pkipc import Channel

def main():
    with Channel() as channel:
        channel.send("progress", {"progress": 0.42})
        # 使用算法原有的 writer，返回前完成写入并关闭文件。
        write_result("outputs/solve/result.vtu")
        channel.send("artifact", {"path": "outputs/solve/result.vtu", "kind": "result"})
        return 7  # 宿主登记该程序认可的成功退出码。
```

`write_result` 是应用自己的函数；完整可运行示例见 [examples/solver.py](examples/solver.py)。
参数、计算循环、文件格式、事件名及 payload 含义由应用定义。

每进程只能创建一次 Channel。它保留原 stdout 管道发送事件，将普通 Python/C/native
stdout 重定向到 stderr；宿主须持续读取两路输出。事件是严格 UTF-8 JSONL，包含递增
uint64 `sequence`、非空字符串 `event` 和任意 JSON `data`，每条不含 LF 最多 1 MiB。
事件名支持中文、空格等合法 UTF-8，不套用旧版名称规则。Python 的 int 必须在 int64/
uint64 范围内；非有限浮点、bytes、tuple、自定义类型、非字符串键、循环引用及非法
Unicode 会被拒绝，拒绝的记录不消耗序号。

`send` 可以由多个线程调用，完整写入管道后返回；成功返回不代表宿主已处理或持久化。
正常背压没有固定写期限。绑定在调用 C++ send 时释放 GIL，独立 IO 线程继续读取 stdin
取消命令 `{"command":"cancel"}\n`。取消或通信故障使 `stopping()` 返回 True 并让
send 抛标准异常；应用自行结束计算和返回自己的退出码。未知/重复字段、无效 JSON、
超过 1024 字节的控制记录及 EOF 中的半条记录均为通信错误；控制流在完整记录边界
正常 EOF 不会被当作取消。细节见同步自 C++ 的 [PROTOCOL.md](pkipc/PROTOCOL.md)。

send 抛错时可能已有部分记录写出，不能自动重试并假设宿主只处理一次。输入错误使用
Python TypeError/ValueError/OverflowError 等标准异常，C++ 通信异常映射为 RuntimeError，
保留原 libuv 消息。不要吞掉通信错误后返回应用成功码。

在退出 `with` 或销毁对象前，收拢所有使用通道的线程。`with` 仅提供 Python 的确定性
资源释放，行为对应 C++ 作用域析构：关闭管道和 IO 线程，不发送完成事件，不改返回码。
宿主拥有进程启动、进程树终止、网络、结果封存和成功判定。SDK 没有 run/done、文件
writer、清单、RPC、握手、TLS、Client/Solver 或 Process，也没有旧版兼容入口。

## 安装与构建

```text
python -m pip install PKIPC==5.0.0
python -m pip install -e ".[test,build]"
python tools/sync_protocol.py --source /path/to/cpp/PKIPC --check
python tools/verify_sdk.py --cpp-source /path/to/cpp/PKIPC --cpp-build /path/to/cpp/build
python -m build
```

wheel 包含原生扩展，按 Python ABI 和平台构建，不依赖运行时 gRPC、protobuf、AnyIO
或外部 PKIPC DLL。源码安装需要 C++17 编译器、CMake 3.28+ 和 Python 开发头文件；
Windows 使用 MSVC 2022，Linux 使用 GCC/Clang。构建依赖由 pip 获取，libuv 源码归档
已随 sdist 提供并固定 SHA-256，构建不从网络拉取 C++ SDK/libuv。

`sync_protocol.py` 同步协议、版本、通道源码和第三方 JSON 头，`--check` 逐字节检查，
同时核对 Python/C++/libuv 版本。修改通道行为应先修改 C++ 唯一来源，再同步。
`verify_sdk.py` 构建并运行 C++ CTest，再将同一真实标准流测试同时用于 C++ 和 Python
执行程序；已有 C++ 构建可用 `--skip-build`。Python 扩展应先安装或重建。
测试覆盖真实并发输出、取消、背压、断管、JSON 数据及退出码；当前执行结果见
[VALIDATION.md](VALIDATION.md)。

`tools/release.py prepare` 要求完整验收后的干净提交，构建原生 wheel/sdist、检查安装
后的真实事件通道、元数据和 SHA-256 清单。使用前安装 `.[test,build,release]`。
Linux prepare 使用 auditwheel 按构建机实际 ABI 修复标签；CI 使用 manylinux_2_28
构建 CPython 3.11–3.14 的 x86_64/Windows amd64 wheel，并在独立环境测试安装包。
`publish` 仅上传已验证清单中的内容，
拒绝覆盖远端不同字节。升级到 v5 需要显式迁移；发布动作须单独执行。
