lumenui 0.0.7__tar.gz
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.
- lumenui-0.0.7/.gitignore +58 -0
- lumenui-0.0.7/PKG-INFO +283 -0
- lumenui-0.0.7/README.md +261 -0
- lumenui-0.0.7/examples/counter.py +70 -0
- lumenui-0.0.7/examples/counter_app/lumen.toml +7 -0
- lumenui-0.0.7/examples/counter_app/src/main.css +40 -0
- lumenui-0.0.7/examples/counter_app/src/main.lmn +18 -0
- lumenui-0.0.7/examples/todo.py +73 -0
- lumenui-0.0.7/examples/todo_app/lumen.toml +7 -0
- lumenui-0.0.7/examples/todo_app/src/main.css +18 -0
- lumenui-0.0.7/examples/todo_app/src/main.lmn +22 -0
- lumenui-0.0.7/lumen/__init__.py +90 -0
- lumenui-0.0.7/lumen/_ffi.py +985 -0
- lumenui-0.0.7/lumen/_lib.py +48 -0
- lumenui-0.0.7/lumen/_version.py +10 -0
- lumenui-0.0.7/lumen/api.py +472 -0
- lumenui-0.0.7/lumen/dom.py +719 -0
- lumenui-0.0.7/lumen/errors.py +199 -0
- lumenui-0.0.7/lumen/model.py +173 -0
- lumenui-0.0.7/lumen/py.typed +0 -0
- lumenui-0.0.7/lumen/raw.py +212 -0
- lumenui-0.0.7/lumen/signals.py +369 -0
- lumenui-0.0.7/pyproject.toml +63 -0
- lumenui-0.0.7/tests/test_dom.py +68 -0
- lumenui-0.0.7/tests/test_ergonomics.py +78 -0
- lumenui-0.0.7/tests/test_version.py +44 -0
lumenui-0.0.7/.gitignore
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/target
|
|
2
|
+
# The `lumenc new` templates, which tools/fetch-templates.sh downloads from
|
|
3
|
+
# the repository each one is maintained in. They belong to no checkout: by
|
|
4
|
+
# default they land in cargo's target directory, ignored above, and this
|
|
5
|
+
# covers a fetch pointed at the checkout instead.
|
|
6
|
+
/templates
|
|
7
|
+
# Where `wasm-bindgen` puts the browser runtime module and its JS glue.
|
|
8
|
+
/web-dist
|
|
9
|
+
**/*.rs.bk
|
|
10
|
+
Cargo.lock.bak
|
|
11
|
+
.DS_Store
|
|
12
|
+
*.swp
|
|
13
|
+
.idea/
|
|
14
|
+
.vscode/
|
|
15
|
+
/lumen.toml.lock
|
|
16
|
+
|
|
17
|
+
# Profiler captures (chrome trace JSON).
|
|
18
|
+
/lumen-trace.json
|
|
19
|
+
|
|
20
|
+
# VS Code extension build artifacts
|
|
21
|
+
tools/vscode-lumen/node_modules/
|
|
22
|
+
tools/vscode-lumen/out/
|
|
23
|
+
tools/vscode-lumen/package-lock.json
|
|
24
|
+
tools/vscode-lumen/*.vsix
|
|
25
|
+
|
|
26
|
+
# Tree-sitter grammar tooling
|
|
27
|
+
tools/tree-sitter-lumen/node_modules/
|
|
28
|
+
tools/tree-sitter-lumen/package-lock.json
|
|
29
|
+
|
|
30
|
+
# Zed extension build artifacts (Zed compiles the extension in place)
|
|
31
|
+
tools/zed-lumen/target/
|
|
32
|
+
tools/zed-lumen/grammars/
|
|
33
|
+
tools/zed-lumen/Cargo.lock
|
|
34
|
+
tools/zed-lumen/extension.wasm
|
|
35
|
+
|
|
36
|
+
# C/C++ FFI consumer build dirs
|
|
37
|
+
apps/sysmon/build/
|
|
38
|
+
__pycache__/
|
|
39
|
+
*.pyc
|
|
40
|
+
.claude/
|
|
41
|
+
|
|
42
|
+
# Docs site build artifacts (Zensical)
|
|
43
|
+
/docs/site/
|
|
44
|
+
/docs/.venv/
|
|
45
|
+
/docs/.cache/
|
|
46
|
+
|
|
47
|
+
# Native libraries built by an app's [[hooks]] into its lib/ (see apps/notes).
|
|
48
|
+
apps/*/lib/
|
|
49
|
+
|
|
50
|
+
# Compiler-plugin emit outputs, regenerated by every compile.
|
|
51
|
+
.lumen/
|
|
52
|
+
|
|
53
|
+
# public/lumen-dylib is its own Cargo workspace, deliberately left without a
|
|
54
|
+
# committed lockfile: tools/verify-engine-crate-graph.py resolves it fresh
|
|
55
|
+
# on every run and compares that against the root workspace's committed
|
|
56
|
+
# Cargo.lock, rather than trusting a second lockfile to stay in step with
|
|
57
|
+
# the first one by hand.
|
|
58
|
+
/public/lumen-dylib/Cargo.lock
|
lumenui-0.0.7/PKG-INFO
ADDED
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: lumenui
|
|
3
|
+
Version: 0.0.7
|
|
4
|
+
Summary: Python SDK for the Lumen UI framework, over its C ABI via ctypes
|
|
5
|
+
Project-URL: Homepage, https://lumenfx.dev
|
|
6
|
+
Project-URL: Documentation, https://docs.lumenfx.dev
|
|
7
|
+
Project-URL: Repository, https://github.com/lumen-fx/lumen
|
|
8
|
+
Author: Lumen contributors
|
|
9
|
+
License-Expression: MPL-2.0
|
|
10
|
+
Keywords: ctypes,ffi,gui,lumen,ui
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Rust
|
|
15
|
+
Classifier: Topic :: Software Development :: User Interfaces
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Provides-Extra: dev
|
|
18
|
+
Requires-Dist: mypy>=1.8; extra == 'dev'
|
|
19
|
+
Requires-Dist: pytest>=7; extra == 'dev'
|
|
20
|
+
Requires-Dist: ruff>=0.5; extra == 'dev'
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# Lumen Python SDK
|
|
24
|
+
|
|
25
|
+
[](https://github.com/lumen-fx/lumen/actions/workflows/ci.yml)
|
|
26
|
+

|
|
27
|
+
[](https://docs.lumenfx.dev/reference/ffi/)
|
|
28
|
+
[](https://github.com/lumen-fx/lumen/blob/main/LICENSE)
|
|
29
|
+
|
|
30
|
+
Typed Python bindings for the [Lumen](https://lumenfx.dev) UI framework, over
|
|
31
|
+
the C ABI (`include/lumen.h`). State is declarative and reactive: you write a
|
|
32
|
+
`Model` whose fields are typed signals, mutate them with plain Python, and the
|
|
33
|
+
runtime keeps the UI in sync.
|
|
34
|
+
|
|
35
|
+
Stdlib only: `ctypes`, no `cffi`, no compiled extension, no build step of its
|
|
36
|
+
own. The only thing to build is the Rust side, once.
|
|
37
|
+
|
|
38
|
+
## Quickstart
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
import lumen
|
|
42
|
+
|
|
43
|
+
class Counter(lumen.Model): # dataclass-style: each field is a signal
|
|
44
|
+
count: int = 0
|
|
45
|
+
label: str = "0 clicks"
|
|
46
|
+
|
|
47
|
+
app = lumen.App("counter_app", title="Counter")
|
|
48
|
+
state = Counter(app)
|
|
49
|
+
|
|
50
|
+
@app.on_click("bump") # decorator; handler takes no args
|
|
51
|
+
def bump():
|
|
52
|
+
state.count += 1 # typed, autocompleted, syncs to the runtime
|
|
53
|
+
state.label = f"{state.count} clicks"
|
|
54
|
+
|
|
55
|
+
app.run() # blocks until the window closes
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Handlers may take the clicked `element_id` string or no argument at all;
|
|
59
|
+
`def bump():` and `def bump(element_id):` both work, mirroring the C++ SDK's
|
|
60
|
+
`void()` and `void(std::string)` overloads. You can also register without the
|
|
61
|
+
decorator: `app.on_click("bump", bump)`.
|
|
62
|
+
|
|
63
|
+
`state.count` and `state.label` *are* signals: reading a field reads the
|
|
64
|
+
signal, writing it pushes the new value to the runtime, and markup bound
|
|
65
|
+
with `bind-text="label"` reflects it next tick. Field names are the
|
|
66
|
+
binding names; override with `Field(name="other")`.
|
|
67
|
+
|
|
68
|
+
## The surface, most to least abstract
|
|
69
|
+
|
|
70
|
+
| You want... | Reach for |
|
|
71
|
+
|---|---|
|
|
72
|
+
| Declarative reactive state | `lumen.Model` + `lumen.Field` |
|
|
73
|
+
| A single typed signal | `lumen.Signal[T]` |
|
|
74
|
+
| A derived value | `lumen.computed(name, fn, *deps)` |
|
|
75
|
+
| To react to a change | `signal.watch(fn)` |
|
|
76
|
+
| To query / mutate the live element tree | `lumen.dom` |
|
|
77
|
+
| A raw `lumen_signal_*` C call | `lumen.raw` (appendix) |
|
|
78
|
+
|
|
79
|
+
### Dynamic DOM (`lumen.dom`)
|
|
80
|
+
|
|
81
|
+
`lumen.dom` reaches the live element tree the way a browser script does:
|
|
82
|
+
query and traverse nodes, read and write attributes / classes / text /
|
|
83
|
+
inline style, build and rearrange subtrees, read post-layout geometry, and
|
|
84
|
+
bind event handlers. A `dom.Node` is a cheap handle; reads return `None` /
|
|
85
|
+
empty for a stale handle and mutations chain.
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from lumen import dom
|
|
89
|
+
|
|
90
|
+
row = dom.spawn("row").add_class("item").set_text("hello")
|
|
91
|
+
list_node = dom.get_by_id("list")
|
|
92
|
+
if list_node:
|
|
93
|
+
list_node.append(row)
|
|
94
|
+
|
|
95
|
+
row.on("click", lambda e: print("clicked", e.target().handle, e.type()))
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### `Model` / `Field`
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
class TodoList(lumen.Model):
|
|
102
|
+
items: list = lumen.Field(default_factory=list) # array signal (<for>)
|
|
103
|
+
summary: str = "0 items"
|
|
104
|
+
|
|
105
|
+
state = TodoList(app)
|
|
106
|
+
state.items = state.items + [{"id": "t1", "text": "Buy milk"}] # re-renders <for>
|
|
107
|
+
state.summary = f"{len(state.items)} items"
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
- Annotated fields become typed signals (`int`->int64, `float`->float64,
|
|
111
|
+
`bool`, `str`, `lumen.Color`, `list`->array).
|
|
112
|
+
- Defaults are applied on construction; use `Field(default_factory=...)`
|
|
113
|
+
for mutable defaults (lists).
|
|
114
|
+
- Signals are global by name, so one `Model` instance per app is the
|
|
115
|
+
intended shape (the field names are the binding names markup reads).
|
|
116
|
+
- `state.signal("count")` returns the underlying `Signal` handle - for
|
|
117
|
+
`.watch()` or to pass into `computed()`.
|
|
118
|
+
|
|
119
|
+
### `Signal[T]` - standalone typed handles
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
count = lumen.Signal("count", 0) # kind inferred from the initial value
|
|
123
|
+
count += 1 # typed operators where they make sense
|
|
124
|
+
count.value = 10 # .value / .get() / .set()
|
|
125
|
+
tint = lumen.Signal("tint", lumen.Color(255, 128, 0))
|
|
126
|
+
|
|
127
|
+
@count.watch # decorator or count.watch(fn)
|
|
128
|
+
def _(new_value):
|
|
129
|
+
print("count is now", new_value)
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
`Signal(name, initial=None, *, type=...)` - pass `type=` when there is no
|
|
133
|
+
initial value, or to widen an `int` literal to `float`.
|
|
134
|
+
|
|
135
|
+
### `watch` and `computed`
|
|
136
|
+
|
|
137
|
+
`signal.watch(fn)` is an ABI subscription (`lumen_signal_watch`), not a
|
|
138
|
+
polling loop: `fn(new_value)` fires on the Lumen tick thread each time the
|
|
139
|
+
value commits. A freshly-registered watch also fires once with the current
|
|
140
|
+
value on the first tick it is observed. Watches only fire while an app is
|
|
141
|
+
running (`run` or `run_headless`), because that is when ticks happen.
|
|
142
|
+
|
|
143
|
+
`computed(name, fn, *deps)` derives a signal from `fn()`, recomputing
|
|
144
|
+
whenever any dependency commits. Direct or decorator form:
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
count = lumen.Signal("count", 0)
|
|
148
|
+
|
|
149
|
+
# direct
|
|
150
|
+
lumen.computed("label", lambda: f"{count.value} clicks", count)
|
|
151
|
+
|
|
152
|
+
# decorator (deps first, then decorate the recompute fn)
|
|
153
|
+
@lumen.computed("label", count)
|
|
154
|
+
def label():
|
|
155
|
+
return f"{count.value} clicks"
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Colors
|
|
159
|
+
|
|
160
|
+
`lumen.Color` is an RGBA tuple with named channels and CSS-style hex:
|
|
161
|
+
|
|
162
|
+
```python
|
|
163
|
+
lumen.Color(255, 128, 0) # r, g, b (, a=255)
|
|
164
|
+
lumen.Color("#ff8000") # hex string (also #f80 / #ff8000ff)
|
|
165
|
+
lumen.Color.from_hex("#ff8000ff") # explicit
|
|
166
|
+
c = lumen.Color("#ff8000"); c.r, c.g, c.b, c.a
|
|
167
|
+
c.to_hex() # "#ff8000ff"
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### Typing
|
|
171
|
+
|
|
172
|
+
The package ships a PEP 561 `py.typed` marker, so once installed the
|
|
173
|
+
inline annotations are visible to `mypy` / Pyright and drive IDE
|
|
174
|
+
completion for `Model` fields, `Signal[T]`, and the `App` methods.
|
|
175
|
+
|
|
176
|
+
## Requirements
|
|
177
|
+
|
|
178
|
+
- Python 3.9+ (stdlib `ctypes` only).
|
|
179
|
+
- The Lumen C library, `liblumen`, built as a shared library.
|
|
180
|
+
- `App.run()` opens an OS window and a GPU surface. For CI or a no-display
|
|
181
|
+
environment, `App.run_headless(ticks)` drives the full app (scripts,
|
|
182
|
+
bindings, `<for>` and `<if>` reconciliation, and `watch` firing) for a
|
|
183
|
+
fixed number of ticks with no window.
|
|
184
|
+
|
|
185
|
+
## Build the C library
|
|
186
|
+
|
|
187
|
+
From the Lumen workspace root:
|
|
188
|
+
|
|
189
|
+
```sh
|
|
190
|
+
cargo build -p lumen # -> target/debug/liblumen.{so,dylib,dll}
|
|
191
|
+
cargo build -p lumen --release # -> target/release/...
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## Run the examples
|
|
195
|
+
|
|
196
|
+
```sh
|
|
197
|
+
LUMEN_LIBRARY_PATH=target/debug python sdk/python/examples/counter.py
|
|
198
|
+
LUMEN_LIBRARY_PATH=target/debug python sdk/python/examples/todo.py
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Both scripts add their parent directory to `sys.path`, so they run
|
|
202
|
+
straight from a checkout with no `pip install`. `counter.py` is the
|
|
203
|
+
quickstart above; `todo.py` exercises a `Model` with a `list` field
|
|
204
|
+
driving a `<for>` block (array signals).
|
|
205
|
+
|
|
206
|
+
## Installing the package
|
|
207
|
+
|
|
208
|
+
```sh
|
|
209
|
+
pip install -e sdk/python
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Registers the `lumen` package; the distribution is named `lumenui`, which is
|
|
213
|
+
also the name it carries on PyPI. The distribution is pure Python: it holds no
|
|
214
|
+
compiled extension and bundles no `liblumen`, so one install works on every
|
|
215
|
+
platform and the runtime it binds is whichever one the machine already has.
|
|
216
|
+
That means something has to provide `liblumen`: either the Lumen toolchain
|
|
217
|
+
install (`curl -fsSL https://lumenfx.dev/install.sh | sh`, which puts the
|
|
218
|
+
library in `~/.lumen/bin` next to `lumenc`) or a checkout you built with
|
|
219
|
+
`cargo build -p lumen`.
|
|
220
|
+
|
|
221
|
+
## Locating the library
|
|
222
|
+
|
|
223
|
+
`load_library()` (called on first use) searches, in order:
|
|
224
|
+
|
|
225
|
+
1. `LUMEN_LIBRARY_PATH` - a direct path to the library file, or a
|
|
226
|
+
directory containing it.
|
|
227
|
+
2. `LUMEN_LIB_DIR` - the same override `lumenc` honours, so one setting
|
|
228
|
+
points both at the same runtime.
|
|
229
|
+
3. `target/{debug,release}` relative to the current working directory.
|
|
230
|
+
4. `target/{debug,release}` relative to the workspace root (found by
|
|
231
|
+
walking up for the workspace `Cargo.toml`).
|
|
232
|
+
5. An installed toolchain: the directory holding the `lumenc` on `PATH`,
|
|
233
|
+
then `$LUMEN_PREFIX/bin`, default `~/.lumen/bin`.
|
|
234
|
+
6. The system loader's own search paths (`LD_LIBRARY_PATH`, `/usr/lib`, ...).
|
|
235
|
+
|
|
236
|
+
A checkout you are working in therefore wins over an installed toolchain, and
|
|
237
|
+
either one is found without setting anything.
|
|
238
|
+
|
|
239
|
+
The loaded library's `lumen_abi_version()` is checked against the version
|
|
240
|
+
this SDK targets, ABI 0.14. A major mismatch or an older minor raises
|
|
241
|
+
`LumenAbiVersionError`.
|
|
242
|
+
|
|
243
|
+
## Threading
|
|
244
|
+
|
|
245
|
+
`@app.on_click` handlers and `watch` callbacks fire on **Lumen's tick
|
|
246
|
+
thread**, not necessarily the thread that called `run`. `ctypes` acquires
|
|
247
|
+
the GIL for you, so touching Python state is safe; a slow or blocking
|
|
248
|
+
handler stalls the whole event loop (rendering, input, timers). Keep
|
|
249
|
+
handlers fast; hand real work to a Python thread you spawn yourself.
|
|
250
|
+
|
|
251
|
+
State you mutate from your own threads is still your responsibility to
|
|
252
|
+
synchronise. `Signal` set/get themselves are thread-safe (each maps to one
|
|
253
|
+
thread-safe C call).
|
|
254
|
+
|
|
255
|
+
## Errors
|
|
256
|
+
|
|
257
|
+
Every `lumen_*` call maps a non-OK `LumenStatus` onto a dedicated
|
|
258
|
+
exception under `lumen.LumenError` (`LumenBadPathError`, `LumenCssError`,
|
|
259
|
+
`LumenScriptError`, ...), so you can `except LumenCssError` instead of
|
|
260
|
+
string-matching. `LumenLibraryNotFoundError` and `LumenAbiVersionError`
|
|
261
|
+
cover the two pre-call failures.
|
|
262
|
+
|
|
263
|
+
## Appendix - the raw layer (`lumen.raw`)
|
|
264
|
+
|
|
265
|
+
`lumen.raw.Signal` is the thin surface every abstraction above is built
|
|
266
|
+
on: each method is exactly one `lumen_signal_*` C call. Reach for it only
|
|
267
|
+
when you need the raw ABI, for example the array setter.
|
|
268
|
+
|
|
269
|
+
```python
|
|
270
|
+
from lumen import raw
|
|
271
|
+
|
|
272
|
+
raw.Signal.set_int64("count", 5) # typed scalar setters/getters
|
|
273
|
+
raw.Signal.get_int64("count") # -> 5
|
|
274
|
+
raw.Signal.set_str("label", "hi") # string scalar
|
|
275
|
+
raw.Signal.set_array("rows", [{"id": "a", "name": "x"}]) # <for> array
|
|
276
|
+
raw.Signal.get_str("label") # read back what the FFI last pushed
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Read-back caveat: `get_str`, `array_len`, and `array_field` return what the
|
|
280
|
+
*embedder* last pushed through the FFI, not live in-app state. A write from
|
|
281
|
+
the app's own script, or a two-way input binding, is not visible through
|
|
282
|
+
them. The number, bool, and color getters do see in-app writes. The typed
|
|
283
|
+
layer above hides all of this.
|
lumenui-0.0.7/README.md
ADDED
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# Lumen Python SDK
|
|
2
|
+
|
|
3
|
+
[](https://github.com/lumen-fx/lumen/actions/workflows/ci.yml)
|
|
4
|
+

|
|
5
|
+
[](https://docs.lumenfx.dev/reference/ffi/)
|
|
6
|
+
[](https://github.com/lumen-fx/lumen/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
Typed Python bindings for the [Lumen](https://lumenfx.dev) UI framework, over
|
|
9
|
+
the C ABI (`include/lumen.h`). State is declarative and reactive: you write a
|
|
10
|
+
`Model` whose fields are typed signals, mutate them with plain Python, and the
|
|
11
|
+
runtime keeps the UI in sync.
|
|
12
|
+
|
|
13
|
+
Stdlib only: `ctypes`, no `cffi`, no compiled extension, no build step of its
|
|
14
|
+
own. The only thing to build is the Rust side, once.
|
|
15
|
+
|
|
16
|
+
## Quickstart
|
|
17
|
+
|
|
18
|
+
```python
|
|
19
|
+
import lumen
|
|
20
|
+
|
|
21
|
+
class Counter(lumen.Model): # dataclass-style: each field is a signal
|
|
22
|
+
count: int = 0
|
|
23
|
+
label: str = "0 clicks"
|
|
24
|
+
|
|
25
|
+
app = lumen.App("counter_app", title="Counter")
|
|
26
|
+
state = Counter(app)
|
|
27
|
+
|
|
28
|
+
@app.on_click("bump") # decorator; handler takes no args
|
|
29
|
+
def bump():
|
|
30
|
+
state.count += 1 # typed, autocompleted, syncs to the runtime
|
|
31
|
+
state.label = f"{state.count} clicks"
|
|
32
|
+
|
|
33
|
+
app.run() # blocks until the window closes
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Handlers may take the clicked `element_id` string or no argument at all;
|
|
37
|
+
`def bump():` and `def bump(element_id):` both work, mirroring the C++ SDK's
|
|
38
|
+
`void()` and `void(std::string)` overloads. You can also register without the
|
|
39
|
+
decorator: `app.on_click("bump", bump)`.
|
|
40
|
+
|
|
41
|
+
`state.count` and `state.label` *are* signals: reading a field reads the
|
|
42
|
+
signal, writing it pushes the new value to the runtime, and markup bound
|
|
43
|
+
with `bind-text="label"` reflects it next tick. Field names are the
|
|
44
|
+
binding names; override with `Field(name="other")`.
|
|
45
|
+
|
|
46
|
+
## The surface, most to least abstract
|
|
47
|
+
|
|
48
|
+
| You want... | Reach for |
|
|
49
|
+
|---|---|
|
|
50
|
+
| Declarative reactive state | `lumen.Model` + `lumen.Field` |
|
|
51
|
+
| A single typed signal | `lumen.Signal[T]` |
|
|
52
|
+
| A derived value | `lumen.computed(name, fn, *deps)` |
|
|
53
|
+
| To react to a change | `signal.watch(fn)` |
|
|
54
|
+
| To query / mutate the live element tree | `lumen.dom` |
|
|
55
|
+
| A raw `lumen_signal_*` C call | `lumen.raw` (appendix) |
|
|
56
|
+
|
|
57
|
+
### Dynamic DOM (`lumen.dom`)
|
|
58
|
+
|
|
59
|
+
`lumen.dom` reaches the live element tree the way a browser script does:
|
|
60
|
+
query and traverse nodes, read and write attributes / classes / text /
|
|
61
|
+
inline style, build and rearrange subtrees, read post-layout geometry, and
|
|
62
|
+
bind event handlers. A `dom.Node` is a cheap handle; reads return `None` /
|
|
63
|
+
empty for a stale handle and mutations chain.
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
from lumen import dom
|
|
67
|
+
|
|
68
|
+
row = dom.spawn("row").add_class("item").set_text("hello")
|
|
69
|
+
list_node = dom.get_by_id("list")
|
|
70
|
+
if list_node:
|
|
71
|
+
list_node.append(row)
|
|
72
|
+
|
|
73
|
+
row.on("click", lambda e: print("clicked", e.target().handle, e.type()))
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### `Model` / `Field`
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
class TodoList(lumen.Model):
|
|
80
|
+
items: list = lumen.Field(default_factory=list) # array signal (<for>)
|
|
81
|
+
summary: str = "0 items"
|
|
82
|
+
|
|
83
|
+
state = TodoList(app)
|
|
84
|
+
state.items = state.items + [{"id": "t1", "text": "Buy milk"}] # re-renders <for>
|
|
85
|
+
state.summary = f"{len(state.items)} items"
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- Annotated fields become typed signals (`int`->int64, `float`->float64,
|
|
89
|
+
`bool`, `str`, `lumen.Color`, `list`->array).
|
|
90
|
+
- Defaults are applied on construction; use `Field(default_factory=...)`
|
|
91
|
+
for mutable defaults (lists).
|
|
92
|
+
- Signals are global by name, so one `Model` instance per app is the
|
|
93
|
+
intended shape (the field names are the binding names markup reads).
|
|
94
|
+
- `state.signal("count")` returns the underlying `Signal` handle - for
|
|
95
|
+
`.watch()` or to pass into `computed()`.
|
|
96
|
+
|
|
97
|
+
### `Signal[T]` - standalone typed handles
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
count = lumen.Signal("count", 0) # kind inferred from the initial value
|
|
101
|
+
count += 1 # typed operators where they make sense
|
|
102
|
+
count.value = 10 # .value / .get() / .set()
|
|
103
|
+
tint = lumen.Signal("tint", lumen.Color(255, 128, 0))
|
|
104
|
+
|
|
105
|
+
@count.watch # decorator or count.watch(fn)
|
|
106
|
+
def _(new_value):
|
|
107
|
+
print("count is now", new_value)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`Signal(name, initial=None, *, type=...)` - pass `type=` when there is no
|
|
111
|
+
initial value, or to widen an `int` literal to `float`.
|
|
112
|
+
|
|
113
|
+
### `watch` and `computed`
|
|
114
|
+
|
|
115
|
+
`signal.watch(fn)` is an ABI subscription (`lumen_signal_watch`), not a
|
|
116
|
+
polling loop: `fn(new_value)` fires on the Lumen tick thread each time the
|
|
117
|
+
value commits. A freshly-registered watch also fires once with the current
|
|
118
|
+
value on the first tick it is observed. Watches only fire while an app is
|
|
119
|
+
running (`run` or `run_headless`), because that is when ticks happen.
|
|
120
|
+
|
|
121
|
+
`computed(name, fn, *deps)` derives a signal from `fn()`, recomputing
|
|
122
|
+
whenever any dependency commits. Direct or decorator form:
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
count = lumen.Signal("count", 0)
|
|
126
|
+
|
|
127
|
+
# direct
|
|
128
|
+
lumen.computed("label", lambda: f"{count.value} clicks", count)
|
|
129
|
+
|
|
130
|
+
# decorator (deps first, then decorate the recompute fn)
|
|
131
|
+
@lumen.computed("label", count)
|
|
132
|
+
def label():
|
|
133
|
+
return f"{count.value} clicks"
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Colors
|
|
137
|
+
|
|
138
|
+
`lumen.Color` is an RGBA tuple with named channels and CSS-style hex:
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
lumen.Color(255, 128, 0) # r, g, b (, a=255)
|
|
142
|
+
lumen.Color("#ff8000") # hex string (also #f80 / #ff8000ff)
|
|
143
|
+
lumen.Color.from_hex("#ff8000ff") # explicit
|
|
144
|
+
c = lumen.Color("#ff8000"); c.r, c.g, c.b, c.a
|
|
145
|
+
c.to_hex() # "#ff8000ff"
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Typing
|
|
149
|
+
|
|
150
|
+
The package ships a PEP 561 `py.typed` marker, so once installed the
|
|
151
|
+
inline annotations are visible to `mypy` / Pyright and drive IDE
|
|
152
|
+
completion for `Model` fields, `Signal[T]`, and the `App` methods.
|
|
153
|
+
|
|
154
|
+
## Requirements
|
|
155
|
+
|
|
156
|
+
- Python 3.9+ (stdlib `ctypes` only).
|
|
157
|
+
- The Lumen C library, `liblumen`, built as a shared library.
|
|
158
|
+
- `App.run()` opens an OS window and a GPU surface. For CI or a no-display
|
|
159
|
+
environment, `App.run_headless(ticks)` drives the full app (scripts,
|
|
160
|
+
bindings, `<for>` and `<if>` reconciliation, and `watch` firing) for a
|
|
161
|
+
fixed number of ticks with no window.
|
|
162
|
+
|
|
163
|
+
## Build the C library
|
|
164
|
+
|
|
165
|
+
From the Lumen workspace root:
|
|
166
|
+
|
|
167
|
+
```sh
|
|
168
|
+
cargo build -p lumen # -> target/debug/liblumen.{so,dylib,dll}
|
|
169
|
+
cargo build -p lumen --release # -> target/release/...
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## Run the examples
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
LUMEN_LIBRARY_PATH=target/debug python sdk/python/examples/counter.py
|
|
176
|
+
LUMEN_LIBRARY_PATH=target/debug python sdk/python/examples/todo.py
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Both scripts add their parent directory to `sys.path`, so they run
|
|
180
|
+
straight from a checkout with no `pip install`. `counter.py` is the
|
|
181
|
+
quickstart above; `todo.py` exercises a `Model` with a `list` field
|
|
182
|
+
driving a `<for>` block (array signals).
|
|
183
|
+
|
|
184
|
+
## Installing the package
|
|
185
|
+
|
|
186
|
+
```sh
|
|
187
|
+
pip install -e sdk/python
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Registers the `lumen` package; the distribution is named `lumenui`, which is
|
|
191
|
+
also the name it carries on PyPI. The distribution is pure Python: it holds no
|
|
192
|
+
compiled extension and bundles no `liblumen`, so one install works on every
|
|
193
|
+
platform and the runtime it binds is whichever one the machine already has.
|
|
194
|
+
That means something has to provide `liblumen`: either the Lumen toolchain
|
|
195
|
+
install (`curl -fsSL https://lumenfx.dev/install.sh | sh`, which puts the
|
|
196
|
+
library in `~/.lumen/bin` next to `lumenc`) or a checkout you built with
|
|
197
|
+
`cargo build -p lumen`.
|
|
198
|
+
|
|
199
|
+
## Locating the library
|
|
200
|
+
|
|
201
|
+
`load_library()` (called on first use) searches, in order:
|
|
202
|
+
|
|
203
|
+
1. `LUMEN_LIBRARY_PATH` - a direct path to the library file, or a
|
|
204
|
+
directory containing it.
|
|
205
|
+
2. `LUMEN_LIB_DIR` - the same override `lumenc` honours, so one setting
|
|
206
|
+
points both at the same runtime.
|
|
207
|
+
3. `target/{debug,release}` relative to the current working directory.
|
|
208
|
+
4. `target/{debug,release}` relative to the workspace root (found by
|
|
209
|
+
walking up for the workspace `Cargo.toml`).
|
|
210
|
+
5. An installed toolchain: the directory holding the `lumenc` on `PATH`,
|
|
211
|
+
then `$LUMEN_PREFIX/bin`, default `~/.lumen/bin`.
|
|
212
|
+
6. The system loader's own search paths (`LD_LIBRARY_PATH`, `/usr/lib`, ...).
|
|
213
|
+
|
|
214
|
+
A checkout you are working in therefore wins over an installed toolchain, and
|
|
215
|
+
either one is found without setting anything.
|
|
216
|
+
|
|
217
|
+
The loaded library's `lumen_abi_version()` is checked against the version
|
|
218
|
+
this SDK targets, ABI 0.14. A major mismatch or an older minor raises
|
|
219
|
+
`LumenAbiVersionError`.
|
|
220
|
+
|
|
221
|
+
## Threading
|
|
222
|
+
|
|
223
|
+
`@app.on_click` handlers and `watch` callbacks fire on **Lumen's tick
|
|
224
|
+
thread**, not necessarily the thread that called `run`. `ctypes` acquires
|
|
225
|
+
the GIL for you, so touching Python state is safe; a slow or blocking
|
|
226
|
+
handler stalls the whole event loop (rendering, input, timers). Keep
|
|
227
|
+
handlers fast; hand real work to a Python thread you spawn yourself.
|
|
228
|
+
|
|
229
|
+
State you mutate from your own threads is still your responsibility to
|
|
230
|
+
synchronise. `Signal` set/get themselves are thread-safe (each maps to one
|
|
231
|
+
thread-safe C call).
|
|
232
|
+
|
|
233
|
+
## Errors
|
|
234
|
+
|
|
235
|
+
Every `lumen_*` call maps a non-OK `LumenStatus` onto a dedicated
|
|
236
|
+
exception under `lumen.LumenError` (`LumenBadPathError`, `LumenCssError`,
|
|
237
|
+
`LumenScriptError`, ...), so you can `except LumenCssError` instead of
|
|
238
|
+
string-matching. `LumenLibraryNotFoundError` and `LumenAbiVersionError`
|
|
239
|
+
cover the two pre-call failures.
|
|
240
|
+
|
|
241
|
+
## Appendix - the raw layer (`lumen.raw`)
|
|
242
|
+
|
|
243
|
+
`lumen.raw.Signal` is the thin surface every abstraction above is built
|
|
244
|
+
on: each method is exactly one `lumen_signal_*` C call. Reach for it only
|
|
245
|
+
when you need the raw ABI, for example the array setter.
|
|
246
|
+
|
|
247
|
+
```python
|
|
248
|
+
from lumen import raw
|
|
249
|
+
|
|
250
|
+
raw.Signal.set_int64("count", 5) # typed scalar setters/getters
|
|
251
|
+
raw.Signal.get_int64("count") # -> 5
|
|
252
|
+
raw.Signal.set_str("label", "hi") # string scalar
|
|
253
|
+
raw.Signal.set_array("rows", [{"id": "a", "name": "x"}]) # <for> array
|
|
254
|
+
raw.Signal.get_str("label") # read back what the FFI last pushed
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
Read-back caveat: `get_str`, `array_len`, and `array_field` return what the
|
|
258
|
+
*embedder* last pushed through the FFI, not live in-app state. A write from
|
|
259
|
+
the app's own script, or a two-way input binding, is not visible through
|
|
260
|
+
them. The number, bool, and color getters do see in-app writes. The typed
|
|
261
|
+
layer above hides all of this.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Runnable counter app - the Lumen Python SDK's "hello world".
|
|
3
|
+
|
|
4
|
+
Shows the effortless surface: a :class:`lumen.Model` whose fields are
|
|
5
|
+
typed reactive signals, ``@app.on_click`` handlers that mutate them with
|
|
6
|
+
plain Python (``state.count += 1``), and the model's ``label`` field
|
|
7
|
+
driving the ``bind-text="label"`` markup in ``counter_app/src/main.lmn``.
|
|
8
|
+
|
|
9
|
+
Run from the Lumen workspace root (build the C library first):
|
|
10
|
+
|
|
11
|
+
cargo build -p lumen
|
|
12
|
+
LUMEN_LIBRARY_PATH=target/debug python sdk/python/examples/counter.py
|
|
13
|
+
|
|
14
|
+
See sdk/python/README.md for why LUMEN_LIBRARY_PATH is needed and the
|
|
15
|
+
callback-thread gotcha.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import sys
|
|
21
|
+
from pathlib import Path
|
|
22
|
+
|
|
23
|
+
# Let this script run straight from a checkout without `pip install -e .`.
|
|
24
|
+
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
|
25
|
+
|
|
26
|
+
import lumen # noqa: E402 (see sys.path tweak above)
|
|
27
|
+
|
|
28
|
+
APP_DIR = Path(__file__).resolve().parent / "counter_app"
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class Counter(lumen.Model):
|
|
32
|
+
"""Reactive state: each annotated field is a typed signal."""
|
|
33
|
+
|
|
34
|
+
count: int = 0
|
|
35
|
+
label: str = "0 clicks"
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def main() -> None:
|
|
39
|
+
app = lumen.App(APP_DIR, title="Lumen - Python Counter", size=(480, 280))
|
|
40
|
+
state = Counter(app)
|
|
41
|
+
|
|
42
|
+
# `label` is *derived* from `count`: whenever the count signal commits,
|
|
43
|
+
# this recomputes and pushes the new text. No manual refresh() to keep
|
|
44
|
+
# in sync - the reactive graph does it.
|
|
45
|
+
count = state.signal("count")
|
|
46
|
+
|
|
47
|
+
@lumen.computed(state.signal("label"), count)
|
|
48
|
+
def _label() -> str:
|
|
49
|
+
n = count.value
|
|
50
|
+
return f"{n} clicks" if n != 1 else "1 click"
|
|
51
|
+
|
|
52
|
+
# Handlers take no arguments - just mutate state, the UI follows.
|
|
53
|
+
@app.on_click("increment")
|
|
54
|
+
def _increment() -> None:
|
|
55
|
+
state.count += 1
|
|
56
|
+
|
|
57
|
+
@app.on_click("decrement")
|
|
58
|
+
def _decrement() -> None:
|
|
59
|
+
state.count -= 1
|
|
60
|
+
|
|
61
|
+
@app.on_click("reset")
|
|
62
|
+
def _reset() -> None:
|
|
63
|
+
state.count = 0
|
|
64
|
+
|
|
65
|
+
with app:
|
|
66
|
+
app.run() # blocks until the window closes
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
if __name__ == "__main__":
|
|
70
|
+
main()
|