Metadata-Version: 2.4
Name: ui-stream
Version: 0.1.0a1
Summary: Bounded UI event streaming with host-owned durable results
Author-email: raja <rajawwang@foxmail.com>
Maintainer-email: raja <rajawwang@foxmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/0RAJA/ui-stream
Project-URL: Repository, https://github.com/0RAJA/ui-stream
Project-URL: Documentation, https://github.com/0RAJA/ui-stream/tree/main/docs
Project-URL: Issues, https://github.com/0RAJA/ui-stream/issues
Project-URL: Changelog, https://github.com/0RAJA/ui-stream/blob/main/CHANGELOG.md
Keywords: sse,streaming,snapshot,ui
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.upstream
License-File: NOTICE
Provides-Extra: json
Requires-Dist: pydantic<3,>=2.10; extra == "json"
Provides-Extra: redis
Requires-Dist: pydantic<3,>=2.10; extra == "redis"
Requires-Dist: redis>=3.5.3; extra == "redis"
Dynamic: license-file

# ui-stream

[English](https://github.com/0RAJA/ui-stream/blob/main/README.en.md) · [文档](https://github.com/0RAJA/ui-stream/blob/main/docs/README.md) · [CI](https://github.com/0RAJA/ui-stream/actions/workflows/ci.yml)

**把后台任务的进度发给 UI，定期保存快照，让最终结果由业务自己的事务提交。**
核心同步、无第三方依赖；通过三个端口接入业务事件、实时通道和持久存储。

## 快速上手

Python ≥3.11，在虚拟环境中从源码运行：

```sh
python -m pip install --no-deps .
python -m examples.counter
python -m demos.sqlite --database ./demo.sqlite3 --port 8765
```

打开 `http://127.0.0.1:8765`。Demo 仅用标准库 HTTP/SQLite 和合成数据；macOS/Linux 可运行。
Counter 和 Demo 位于仓库的 `examples/`、`demos/`，需在仓库根目录运行；默认 wheel 只含核心。
发布到 PyPI 后可安装 `ui-stream==0.1.0a1`；import 名为 `ui_stream`。

## 适用边界

| 适合 | 由宿主负责 / 不保证 |
| --- | --- |
| 任务进度、最新快照、尽力实时尾流 | 权限、跨进程 fencing、任务重试与业务结果事务 |
| 有界缓冲、checkpoint、提交后再发终态 | 完整历史重放、断线无损、exactly-once |
| 同步 Python 宿主，自定义事件与存储 | 自动续跑、读者断开即取消、生产级 Demo 服务 |

## 扩展入口

实现 `EventCodec`、`LivePublisher`、`ArchiveStore` 即可接入，无须继承或修改 `StreamRuntime`。
内存 Counter 展示自定义事件与结果；SQLite Demo 展示持久快照、SSE 与故障恢复。

```python
from ui_stream import StreamPolicy
from examples.counter import make_counter

runtime, channel, store = make_counter(policy=StreamPolicy(checkpoint_event_count=1))
runtime.send(4)
runtime.send(9)
runtime.finish(status="DONE", completion=13)
assert store.snapshot.latest == 9 and store.snapshot.result == 13
```

| 安装范围 | 依赖 |
| --- | --- |
| 核心 wheel | 标准库 |
| 仓库 Counter / SQLite Demo | 标准库 + 已安装核心 |
| `[json]` | Pydantic ≥2.10,<3 |
| `[redis]` | Pydantic ≥2.10,<3，redis-py ≥3.5.3 |

![组件边界：任务调用 Runtime，宿主实现三个端口，UI读取实时尾流和快照](https://raw.githubusercontent.com/0RAJA/ui-stream/main/docs/diagrams/architecture.png)

[架构与完成顺序](https://github.com/0RAJA/ui-stream/blob/main/docs/architecture.md) · [API 契约](https://github.com/0RAJA/ui-stream/blob/main/docs/api.md) · [Demo](https://github.com/0RAJA/ui-stream/blob/main/demos/sqlite/README.md) ·
[性能图表](https://github.com/0RAJA/ui-stream/blob/main/docs/performance.md) · [方案选型](https://github.com/0RAJA/ui-stream/blob/main/docs/comparison.md) · [贡献](https://github.com/0RAJA/ui-stream/blob/main/CONTRIBUTING.md) · [安全](https://github.com/0RAJA/ui-stream/blob/main/SECURITY.md) · [发布](https://github.com/0RAJA/ui-stream/blob/main/docs/releasing.md)

CI 的源码矩阵覆盖 Python 3.11–3.14 / Linux、macOS；wheel、sdist 与 README 验证在 Linux 执行。
维护者：`raja <rajawwang@foxmail.com>`（GitHub [0RAJA](https://github.com/0RAJA)）。
[MIT 及来源说明](https://github.com/0RAJA/ui-stream/blob/main/docs/license.md)；原版权声明保持不变。
