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.
@@ -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
+ [![ci](https://github.com/lumen-fx/lumen/actions/workflows/ci.yml/badge.svg)](https://github.com/lumen-fx/lumen/actions/workflows/ci.yml)
26
+ ![python](https://img.shields.io/badge/python-3.9%2B-blue)
27
+ [![docs](https://img.shields.io/badge/docs-reference%2Fffi-blue)](https://docs.lumenfx.dev/reference/ffi/)
28
+ [![license](https://img.shields.io/badge/license-MPL--2.0-blue)](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.
@@ -0,0 +1,261 @@
1
+ # Lumen Python SDK
2
+
3
+ [![ci](https://github.com/lumen-fx/lumen/actions/workflows/ci.yml/badge.svg)](https://github.com/lumen-fx/lumen/actions/workflows/ci.yml)
4
+ ![python](https://img.shields.io/badge/python-3.9%2B-blue)
5
+ [![docs](https://img.shields.io/badge/docs-reference%2Fffi-blue)](https://docs.lumenfx.dev/reference/ffi/)
6
+ [![license](https://img.shields.io/badge/license-MPL--2.0-blue)](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()
@@ -0,0 +1,7 @@
1
+ [app]
2
+ entry = "main.lmn"
3
+ id = "dev.lumen.examples.python-counter"
4
+
5
+ [window]
6
+ title = "Lumen - Python Counter"
7
+ size = [480, 280]