python-cui 1.4.0.6__cp311-cp311-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cui/__init__.py +87 -0
- cui/__init__.pyi +757 -0
- cui/_api.cp311-win_amd64.pyd +0 -0
- cui/_api.pyi +425 -0
- cui/_cui.cp311-win_amd64.pyd +0 -0
- cui/_cui.pyi +160 -0
- cui/_gen/COVERAGE.md +151 -0
- cui/_gen/__init__.py +1 -0
- cui/_gen/constants.py +813 -0
- cui/_gen/model.py +202 -0
- cui/_types.py +287 -0
- cui/py.typed +0 -0
- cui/ui.py +606 -0
- python_cui-1.4.0.6.dist-info/METADATA +221 -0
- python_cui-1.4.0.6.dist-info/RECORD +16 -0
- python_cui-1.4.0.6.dist-info/WHEEL +5 -0
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: python-cui
|
|
3
|
+
Version: 1.4.0.6
|
|
4
|
+
Summary: Python bindings for CUI
|
|
5
|
+
Keywords: gui,ui,immediate-mode,cui,bindings,cython
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Classifier: Development Status :: 4 - Beta
|
|
8
|
+
Classifier: Intended Audience :: Developers
|
|
9
|
+
Classifier: Programming Language :: C
|
|
10
|
+
Classifier: Programming Language :: Cython
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Topic :: Software Development :: User Interfaces
|
|
13
|
+
Project-URL: Homepage, https://github.com/yappologistic/CUI
|
|
14
|
+
Requires-Python: >=3.9
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
|
|
17
|
+
# PYCUI — CUI 的 Python 绑定
|
|
18
|
+
|
|
19
|
+
[CUI](https://github.com/yappologistic/CUI) 是一个用 C99 写的立即模式原生 UI 库(约 190 个组件,
|
|
20
|
+
自带软件渲染器与 Win32 / Cocoa / X11 / SDL2 / GLFW 窗口后端)。PYCUI 把它做成一个可以直接
|
|
21
|
+
`import cui` 的 Python 包:界面由 C 绘制,逻辑写在 Python 里。
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
import cui
|
|
25
|
+
|
|
26
|
+
class State:
|
|
27
|
+
def __init__(self):
|
|
28
|
+
self.name = "Maya"
|
|
29
|
+
self.notify = True
|
|
30
|
+
|
|
31
|
+
state = State()
|
|
32
|
+
|
|
33
|
+
def frame(ui: cui.UI) -> None:
|
|
34
|
+
with ui.column(pad=24, gap=12):
|
|
35
|
+
ui.heading("Hello, CUI")
|
|
36
|
+
ui.text("The widgets are C; the logic is Python.")
|
|
37
|
+
state.notify = ui.switch("Notifications", value=state.notify)
|
|
38
|
+
state.name = ui.text_input("name", value=state.name, label="Name").text
|
|
39
|
+
if ui.button("Save", variant=cui.ButtonVariant.PRIMARY, icon=cui.Icon.CHECK):
|
|
40
|
+
ui.toast("Saved", tone=cui.Tone.SUCCESS)
|
|
41
|
+
|
|
42
|
+
cui.App().run(frame, title="Hello", width=900, height=600)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
本机已编译通过并跑完测试。CUI 官方的示例应用已经移植到 `examples/` 下;每个示例既能开原生窗口,
|
|
46
|
+
也能加 `--shot` 用软件渲染离屏输出 PNG(不需要窗口、X server 或 GPU):
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
python examples/todo.py # 原生窗口
|
|
50
|
+
python examples/todo.py --shot out.png # 离屏渲染
|
|
51
|
+
python examples/dashboard.py --dark --shot dark.png
|
|
52
|
+
python examples/notes.py --frames 5 --shot notes.png
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
| 示例 | 内容 |
|
|
56
|
+
| --- | --- |
|
|
57
|
+
| `hello.py` | 最小的窗口、标题、开关和按钮 |
|
|
58
|
+
| `todo.py` | 待办列表:过滤、确认对话框、保存到文件 |
|
|
59
|
+
| `settings.py` | 设置页:侧栏、表单、外观与危险操作 |
|
|
60
|
+
| `notes.py` | 笔记:分栏、搜索、上下文菜单、命令面板 |
|
|
61
|
+
| `dashboard.py` | 仪表盘:折线图、环形图、表格、响应式侧栏 |
|
|
62
|
+
| `assistant.py` | 聊天助手:推理、工具调用、计划、来源与输入框 |
|
|
63
|
+
| `mail.py` | 三栏邮件:自绘列表行、分栏、对话框、抽屉 |
|
|
64
|
+
| `music.py` | 音乐播放器:自绘封面与均衡器、滑杆、菜单 |
|
|
65
|
+
| `tracker.py` | 议题跟踪:自绘状态图标、活动时间线、命令面板 |
|
|
66
|
+
| `finance.py` | 财务总览:余额图、卡片、环形图、预算与进度环 |
|
|
67
|
+
| `caffeine.py` | 咖啡因曲线:点阵图、标注、可拖动事件轨、点阵显示 |
|
|
68
|
+
|
|
69
|
+
CUI 的 `gallery`(组件总览)没有整体移植:它覆盖了大量仍在 Phase 3 的组件
|
|
70
|
+
(终端、文件浏览器、代码编辑器、树表等);组件总览仍由 `examples/components.py`
|
|
71
|
+
提供。上面的 11 个应用示例是 `CUI/examples` 中除 `gallery` 外的全部应用。
|
|
72
|
+
|
|
73
|
+
<table>
|
|
74
|
+
<tr>
|
|
75
|
+
<td><img src="docs/images/examples/dashboard.png" width="420" alt="Dashboard"></td>
|
|
76
|
+
<td><img src="docs/images/examples/assistant.png" width="420" alt="Assistant"></td>
|
|
77
|
+
</tr>
|
|
78
|
+
<tr>
|
|
79
|
+
<td><img src="docs/images/examples/mail.png" width="420" alt="Mail"></td>
|
|
80
|
+
<td><img src="docs/images/examples/music.png" width="420" alt="Music"></td>
|
|
81
|
+
</tr>
|
|
82
|
+
<tr>
|
|
83
|
+
<td><img src="docs/images/examples/notes.png" width="420" alt="Notes"></td>
|
|
84
|
+
<td><img src="docs/images/examples/tracker.png" width="420" alt="Tracker"></td>
|
|
85
|
+
</tr>
|
|
86
|
+
<tr>
|
|
87
|
+
<td><img src="docs/images/examples/finance.png" width="420" alt="Finance"></td>
|
|
88
|
+
<td><img src="docs/images/examples/caffeine.png" width="420" alt="Caffeine"></td>
|
|
89
|
+
</tr>
|
|
90
|
+
<tr>
|
|
91
|
+
<td><img src="docs/images/examples/settings.png" width="420" alt="Settings"></td>
|
|
92
|
+
<td><img src="docs/images/examples/todo.png" width="420" alt="To do"></td>
|
|
93
|
+
</tr>
|
|
94
|
+
</table>
|
|
95
|
+
|
|
96
|
+
离屏渲染的组件总览仍是 `examples/components.py`(浅色/深色截图见
|
|
97
|
+
`docs/images/components-light.png` 与 `components-dark.png`):
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
python examples/components.py out.png # 浅色
|
|
101
|
+
python examples/components.py out.png --dark # 深色
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## 安装
|
|
105
|
+
|
|
106
|
+
仓库里已经以 git submodule 形式带上 CUI 源码,构建时静态链接进扩展,所以轮子里没有
|
|
107
|
+
`libcui.dll`,也不存在 DLL 搜索路径问题。
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
python -m pip install cython scikit-build-core cmake # 构建依赖
|
|
111
|
+
python -m pip install . # 编译并安装
|
|
112
|
+
python -m pip install -e . # 开发模式(改 Python 不用重装)
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
构建需要一个 C 编译器:Windows 上装 Visual Studio(Desktop development with C++),
|
|
116
|
+
macOS 上 `xcode-select --install`,Linux 上 `build-essential` 加 `libx11-dev`。
|
|
117
|
+
扩展是按头文件在编译期对齐的:换 CUI 小版本必须重新编译,不要指望换 `.so`/`.pyd` 就能跑。
|
|
118
|
+
|
|
119
|
+
## 公开 API
|
|
120
|
+
|
|
121
|
+
| 层 | 说明 |
|
|
122
|
+
| --- | --- |
|
|
123
|
+
| `cui.UI` | 面向应用的 Pythonic 门面:`with ui.column()`、`ui.button(...)`、`ui.text_input(...)`;容器用 `with`,可能不显示的重叠层用回调(`ui.dialog(..., body=...)`)。 |
|
|
124
|
+
| `cui.App` | 原生窗口与事件循环;`App.run(frame)` 在 C 侧循环里释放 GIL,帧回调里的 Python 异常会被捕获、退出循环后再抛回。 |
|
|
125
|
+
| `cui.Context` / `cui.SoftwareRenderer` | 离屏渲染:`begin_frame()` / `end_frame()` / `draw_data()` / `screenshot(path)`,不需要窗口和 GPU。 |
|
|
126
|
+
| `cui._api` | 生成的低层封装:**一个 CUI 函数对应一个函数**,选项结构体变成关键字参数,出参变成返回值。`ui` 上找不到的方法会自动从这一层取。 |
|
|
127
|
+
| `cui.Color` / `cui.Size` / `cui.Date` / `cui.TextResult` | C 结构体对应的 Python 值类型。颜色可以用 `Color(255,0,0)`、`Color.rgb(0xE5484D)` 或 `Color.token(cui.Token.ACCENT)`。 |
|
|
128
|
+
| `cui.Series` / `cui.DotSeries` / `cui.ChartAnnotation` | 图表数据:折线/柱状序列、点阵图序列和图表标注;`CanvasResult`、`EventTrackResult` 是 canvas / 事件轨的返回值。 |
|
|
129
|
+
| 枚举与图标 | `cui.ButtonVariant`、`cui.Tone`、`cui.ThemeMode`、`cui.Icon.CHECK`、`cui.ICON_PLUS` 等,全部从 CUI 头文件生成。 |
|
|
130
|
+
|
|
131
|
+
立即模式的约定和 CUI 一样:每帧调用组件函数,函数返回这一帧发生了什么;你的变量就是状态。
|
|
132
|
+
字符串按 UTF-8 编码,含 NUL 或以 `None` 传给必填参数会直接抛异常(而不是让 C 侧读空指针)。
|
|
133
|
+
|
|
134
|
+
出参一律变成返回值,例如:
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
on = ui.switch("Notifications", value=on) # bool
|
|
138
|
+
index = ui.select("fruit", items, index=index) # int
|
|
139
|
+
name = ui.text_input("name", value=name).text # TextResult,跨帧保留编辑状态
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## 代码结构
|
|
143
|
+
|
|
144
|
+
```text
|
|
145
|
+
src/cui/
|
|
146
|
+
__init__.py 公开命名空间(枚举、图标、App/UI/Context/数值类型)
|
|
147
|
+
ui.py Pythonic 门面(容器、约 60 个常用组件、回调式重叠层)
|
|
148
|
+
_types.py Color / Size / Date / TextResult / TextMetrics
|
|
149
|
+
_cui.pyx 手写 Cython 核心:上下文与 App 生命周期、GIL、字符串保活、软件渲染
|
|
150
|
+
_cui.pxd 核心对象的 C 侧声明,供生成的封装层直接调用
|
|
151
|
+
_trampoline.c cui_app_run 的帧回调 trampoline(进 Python 前重新拿 GIL)
|
|
152
|
+
cui_decl.pxd 生成:C 结构体 / 枚举 / 函数声明
|
|
153
|
+
_api.pyx 生成:每个可调用 CUI 函数一个封装
|
|
154
|
+
_gen/constants.py 生成:枚举、整数常量、图标字符串
|
|
155
|
+
_gen/model.py 生成:CUI 数据结构的 NamedTuple
|
|
156
|
+
_gen/sizes.h 生成:不透明句柄的 sizeof 与个别字段的 setter
|
|
157
|
+
_gen/COVERAGE.md 生成:哪些函数已封装、哪些留到下一阶段
|
|
158
|
+
tools/gen_cui.py 生成器(libclang 解析 cui.h / cui_render.h / cui_app.h)
|
|
159
|
+
tests/ pytest:转换、生命周期、离屏渲染、门面覆盖、生成物同步
|
|
160
|
+
examples/ 移植自 CUI/examples 的示例应用 + 共享的 _common.py 运行器
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
映射规则(由 `tools/gen_cui.py` 实现):
|
|
164
|
+
|
|
165
|
+
| C 形态 | Python |
|
|
166
|
+
| --- | --- |
|
|
167
|
+
| `const T *_opts` | 关键字参数;零值就是 CUI 的默认值 |
|
|
168
|
+
| `bool *` / `int *` / `float *` / `double *` 等出参 | 多一个返回值 |
|
|
169
|
+
| `char *buf, size_t cap` | `text=` 传进去,返回 `TextResult`;缓冲区按 id 跨帧保留 |
|
|
170
|
+
| `const char *const *items, int count` | `Sequence[str]` |
|
|
171
|
+
| `const float *values, int count` | `Sequence[float]` |
|
|
172
|
+
| `const T *items, int count`(T 是纯数据) | `Sequence[cui.T]`,自动打包成 C 数组 |
|
|
173
|
+
| `T *`(不透明句柄) | `cui.T()` 句柄对象,Python 侧持有并清零 |
|
|
174
|
+
| 返回 `cui_color` / `cui_size` / `cui_date` 等 | 对应的 Python 值类型 |
|
|
175
|
+
|
|
176
|
+
## 生成器
|
|
177
|
+
|
|
178
|
+
```sh
|
|
179
|
+
python tools/gen_cui.py # 重新生成 src/cui 下的生成物
|
|
180
|
+
python tools/gen_cui.py --check # CI:生成物与头文件不同步就以非 0 退出
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
`--check` 是升级 CUI 时的安全网:头文件新增函数、改结构体布局而没重新生成,CI 会失败。
|
|
184
|
+
生成物已提交到仓库,所以 `pip install` 不需要 libclang。
|
|
185
|
+
|
|
186
|
+
生成器解析时固定使用 `tools/clang-include/` 里的四个最小标准头文件(`-nostdinc` +
|
|
187
|
+
`-isystem`),不读宿主机的 C 库:pip 的 `libclang` 轮子不带标准头,Windows 上 libclang
|
|
188
|
+
碰巧能找到 MSVC 的头,Linux 上则一个都找不到,`bool` / `size_t` / `va_list` 会被当成
|
|
189
|
+
错误恢复类型,生成的 API 也就变了。如果 CUI 用到了新的标准类型,在这个目录里补上;
|
|
190
|
+
解析有错误时生成器会直接失败,而不是拿残缺的 AST 继续生成。
|
|
191
|
+
|
|
192
|
+
## 测试
|
|
193
|
+
|
|
194
|
+
```sh
|
|
195
|
+
python -m pytest tests -q
|
|
196
|
+
$env:PYCUI_WINDOW_TESTS = "1"; python -m pytest tests -q # 额外跑原生窗口测试
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
默认测试全部离屏(`cui_sw_*` 软件渲染),不需要窗口、X server 或 GPU,CI 上稳定。
|
|
200
|
+
`tests/test_examples.py` 会把 `examples/` 里的每个应用按 `--shot` 渲染一遍,检查它们没有
|
|
201
|
+
异常且确实写出了 PNG;`tests/test_charts.py` 覆盖 canvas 回调、图表和事件轨。
|
|
202
|
+
窗口测试需要一个可交互的桌面会话,因此用环境变量显式开启。
|
|
203
|
+
|
|
204
|
+
## 当前范围与已知限制
|
|
205
|
+
|
|
206
|
+
- CUI 的 500 个公开函数里,**429 个已经封装**(369 个由生成器封装,60 个在 `_cui.pyx` 手写,
|
|
207
|
+
包括 canvas 绘制回调、折线/柱状/点阵图、事件轨、分栏等),其余 71 个在
|
|
208
|
+
`src/cui/_gen/COVERAGE.md` 里逐条列了原因:
|
|
209
|
+
需要 C 回调(`cui_tree_sort`、`cui_state_on_free` 等)、变参(`cui_textf` 等)、
|
|
210
|
+
调用方分配的结构体数组(日志/终端/差异视图/树表等数据密集组件)、返回结构体的组件,
|
|
211
|
+
以及 GL 渲染器接口。这些是计划里的 Phase 3 内容。
|
|
212
|
+
- 没有内置无障碍与输入法支持:CUI 本身没有,绑定只能继承这个限制。
|
|
213
|
+
- 一个 `cui.Context` 只能在一个线程里用(macOS 上还必须是主线程),越界会抛 `RuntimeError`。
|
|
214
|
+
- CUI 的事件循环是事件驱动的:静态画面会睡到下一个输入事件。需要定时刷新时在帧回调里调用
|
|
215
|
+
`ctx.request_wakeup(seconds)`(示例见 `tests/test_app.py`)。
|
|
216
|
+
- 平台:本机(Windows 11 + MSVC 19.52 + Python 3.14)已编译并测试通过;macOS / Linux 需要
|
|
217
|
+
对应的 CUI 后端依赖(Cocoa / X11),构建脚本已按 CUI 的 CMake 选项接好。
|
|
218
|
+
|
|
219
|
+
## 许可
|
|
220
|
+
|
|
221
|
+
绑定代码 MIT。CUI 也是 MIT,字体与图标许可见 `CUI/THIRD_PARTY.md` 与 `CUI/LICENSE`。
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
cui/__init__.py,sha256=2cTzh9m2bBADYymqJuQZYIABYcAdE3OJyQAfB1MhULI,2288
|
|
2
|
+
cui/__init__.pyi,sha256=8IxOENM3rH-EQmI-aPrdmE3Vc3V1AUFvtVnu8S6Zp50,14632
|
|
3
|
+
cui/_api.cp311-win_amd64.pyd,sha256=PzwxZRbJefoq-4GPUP_lewv56QY-V2deCPOYNoGPf6U,1938432
|
|
4
|
+
cui/_api.pyi,sha256=SMmCZEWV40RjWY0vEOzkV2UK6i83iFZnJIx-UyWV4Lw,49535
|
|
5
|
+
cui/_cui.cp311-win_amd64.pyd,sha256=nOQkl7keeIoI0v-4_75uDxg_LbZnxmDE_8gVGmlfNnc,582656
|
|
6
|
+
cui/_cui.pyi,sha256=I0HrU2K_RgUzEYubqCdwIYLm3XmcBmhb2uF6bJ-ifJ4,5643
|
|
7
|
+
cui/_gen/__init__.py,sha256=9nxRGco2CCTV3j1k7cHr73aVsY-Drv139_tl5chNk7Y,70
|
|
8
|
+
cui/_gen/constants.py,sha256=-ne4ahvggjqB41nltQkzQ-tCYILp28aYQYdINrLvs9c,25755
|
|
9
|
+
cui/_gen/COVERAGE.md,sha256=DyVbNMU90MwaTiUhrSHeqnEZ5DCaHw1_F9u0DoP2IQE,8560
|
|
10
|
+
cui/_gen/model.py,sha256=NPwXqg9hLJKLikefL_VzvtUsS6UIOYqMqT9kn4enRlg,9149
|
|
11
|
+
cui/_types.py,sha256=Oooiq6nloaM2r3O1hdc397d5nDTi_Vu-s2YbkevntqI,7327
|
|
12
|
+
cui/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
13
|
+
cui/ui.py,sha256=roUB9Y0Rs6ChoOlIPzra665fgua2W1phWdd_glzXl5U,23476
|
|
14
|
+
python_cui-1.4.0.6.dist-info/METADATA,sha256=T9cSzn3kwJB42voCvaRpp_pj8VwkG1mqgkCQqVbRD18,11762
|
|
15
|
+
python_cui-1.4.0.6.dist-info/WHEEL,sha256=p900zCxVwNE_l97IewvpikgL9eLYv_okLSJlXrR1udA,105
|
|
16
|
+
python_cui-1.4.0.6.dist-info/RECORD,,
|