Desktop 0.86.x: silent callback crashes, ambiguous run_thread/run_task semantics, and focus() no-op via run_task
维护者通常 1 天内回复
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 25/100
- Issue 类型
- 文档
- 描述清晰度
- 基本清楚
- 活跃度
- 活跃
- 技术栈
- flutter, python
调研方向
Start by identifying the documentation pages for error handling, threading, desktop runtime lookup, and page updates; the issue does not name specific files or tests. The reporter offers to contribute documentation for run_thread/run_task semantics and update timing. Define the scope with the maintainers, then document the supported behavior and recommended usage based on the project’s implementation.
由索引模型根据 Issue 内容生成。
描述
Hi Flet team,
I have been maintaining a Python desktop application on Flet 0.86.5 for several
months. It runs on Windows with Python 3.14, uses background workers, periodic
timers and a system-tray callback, and is also opened in a web session for UI
verification. During that time I hit a handful of runtime and documentation
problems that cost a lot of debugging time. They are collected here as one
feedback issue so the details are not lost. I am happy to split them into
separate issues if that is more useful.
Environment
- Flet 0.86.5 (pinned), Python 3.14, Windows 11
- Desktop mode via
ft.run(imperative API), plus a web session used for screenshots - Packaged with PyInstaller; the tray integration uses pystray
- Uncaught exceptions in callbacks / background threads terminate the app silently
Symptom. A packaged build occasionally exited with no error shown to the
user. The application log ended with:
20:12:12 Session was garbage collected
and then stopped: no on_disconnect, no shutdown record, no cleanup, no
traceback. Plain try/except around individual handlers did not catch it.
Suspected cause. An unhandled exception raised inside a Flet event callback
or inside a background thread. Neither path reached the application's normal
logging.
Workaround I had to add. Three global hooks installed at startup:
sys.excepthookthreading.excepthookasyncio.get_running_loop().set_exception_handler(...)
After that, the next crash produced a full stack trace in the log. Before that,
the failure was effectively invisible.
Request. Could Flet either install a diagnostic exception hook by default in
desktop mode, or document the recommended pattern for capturing exceptions from
event callbacks and user-spawned background threads? A short note in the
"error handling" docs would already help a lot. Logging a pending exception
summary when a session is garbage-collected would also make these failures much
easier to report.
page.run_threadvspage.run_task: the threading contract is easy to misread
Observation. A lot of community examples (and code produced by AI assistants)
treat page.run_thread as "dispatch back onto the UI/session thread". In my
testing on 0.86.x it behaves the opposite way: it submits the callable to a
background thread pool, and it does not guarantee execution in the UI
session context. I also found that page.update() does not appear to take a
single global lock, so calling it from arbitrary threads is not safe even though
it often appears to work in small examples.
Consequence. Copying the common pattern — calling page.run_thread from a
threading.Timer callback or from a tray callback and then mutating controls —
can still produce threading bugs. The correct approach seems to be: do work off
the UI thread, then marshal only the UI mutation back to the session via
page.run_task (or an equivalent session-aware path).
Request. Please document explicitly, in one place:
- which thread
run_threadexecutes on, - which thread
run_taskexecutes on, - whether
page.update()is safe to call outside the session thread, - the officially recommended pattern for "background work -> UI update".
This is the single most confusing part of the API for a solo developer, because
getting it wrong does not fail loudly — it fails intermittently.
control.focus()wrapped inpage.run_tasksilently does nothing in a web session
Repro (simplified). In an async keyboard event handler of a custom input
widget, advancing focus to the next field:
# Does not work — no exception, focus just stays where it was:
page.run_task(lambda: next_field.focus())
# Works:
await next_field.focus()
Observed in a web session on 0.86.5. I verified it by adding a _nav["idx"]
marker: the index advanced, but the browser focus did not move.
Request. If focus() is only valid when awaited directly inside the async
handler, that should be documented. If run_task is supposed to be a valid
wrapper for control methods, this looks like a bug — it fails silently, which
is the hardest kind to diagnose.
- First desktop launch on a clean Windows machine tries to download the Flet view shell
Symptom. On a machine with no cached desktop runtime, startup hung on a
GitHub download and the app never showed a window. To make startup reliable I
had to locate an existing flet.exe at the earliest possible moment and set
FLET_VIEW_PATH myself, probing the bundled directory, the local vendor copy,
site-packages, and %USERPROFILE%/.flet/client/flet-desktop-*/flet.
Request. Please document the desktop runtime lookup order and the offline /
bundled-runtime story more prominently, and consider preferring an already
cached local shell over a network download by default. For students handing a
single .exe to a teacher, "double click and it starts without internet" is a
hard requirement.
- Painting a splash frame requires an explicit event-loop yield
Symptom. With page.add(splash); page.update() followed immediately by
several hundred milliseconds of setup work, the splash never appeared — the
window opened with the main UI already in place. It only rendered reliably after
yielding explicitly (a run_task with await asyncio.sleep(0.08) before the
heavy build).
Request. A short note on when page.update() actually flushes to the
screen, and whether a "update then yield" helper exists or should exist, would
save a lot of trial and error for cold-start screens.
Summary of suggested improvements
- Built-in or documented global exception hooks for desktop apps
- One authoritative table of
run_thread/run_task/page.update()thread semantics - Clarify or fix
focus()when called throughrun_task - Offline-first desktop runtime discovery, with the lookup order documented
- Clarify frame-flush timing around
page.update()
I can contribute a short documentation PR covering items 2 and 5 if that would
be useful — those two are pure docs and I already have the notes.
Thanks for the framework. The Python-only UI model made this project possible
for one person; the points above are all about making the last 10% (packaging,
threading, crash diagnostics) less painful.
No project-specific or personal data is included in this report; all examples
are generic and were rewritten for this issue.
- 主要语言
- Python
- 星标
- 17.6k
- 派生
- 753
- 平均合并
- 2 天 8 小时
- 30 天内合并 PR
- 64
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
flet-dev/flet 的其他 Issue
-
难度 2/5 1-3 小时 新手友好度 62/100
维护者通常 1 天内回复
-
feature request
难度 2/5 1-3 小时 新手友好度 66/100
flet-dev/flet#6985 · 3 条评论 · 1 个 reaction ·
维护者通常 1 天内回复
-
bug: dataclass_transform() uses should include `field_specifiers` argument可能已有人在做 关联的 PR 仍在进行中或已合并。 未关闭bug
难度 2/5 1-3 小时 新手友好度 72/100
维护者通常 1 天内回复
-
bug: InputFilter number checking可能已有人在做 @ndonkoHenri 今天认领。 未关闭bug
flet-dev/flet#7098 · 已指派 1 人 ·
维护者通常 1 天内回复
-
feature request
难度 3/5 1-2 天 新手友好度 56/100
维护者通常 1 天内回复
相似的 Issue
-
CI flake: test-windows times out spawning Node in tests/test_antigravity_node_hooks.py (develop red)未关闭area/ci P2
难度 2/5 1-3 小时 新手友好度 68/100
维护者通常 2 天内回复
-
benchmark
难度 1/5 1-3 小时 新手友好度 72/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 79/100
-
难度 2/5 1-3 小时 新手友好度 77/100
mozilla-ai/cq#601 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 68/100
维护者通常 1 天内回复