LumiView

Pythonic webview desktop app framework — lightweight, out-of-the-box, async-first.

中文

---

⚠️ Early Development Stage — APIs May Change

LumiView is currently in pre-alpha. The API is functional but not yet stable — method names, parameter structures, and import paths may change between dev releases. We use dev releases to gather early feedback while retaining the flexibility to adjust the API.

Early adopters welcome! Try building an app with it and tell us what works well and what doesn't. Your feedback will directly shape the final stable API. When upgrading, please check the changelog and be prepared to adjust your code.

---

What is LumiView?

LumiView is an app development framework focused on system webviews. At the core layer, it wraps tao and wry (via wryview); at the top layer, it provides a clean, out-of-the-box, async-first Python API.

Architecture

flowchart TB
    subgraph py["Python Layer"]
        direction LR
        App ~~~ Window ~~~ Bridge ~~~ Task["Task[T]"] ~~~ Serve
    end

    subgraph rust["Rust Layer (PyO3)"]
        TaoWindow ~~~ EventLoop
    end

    subgraph plat["Platform WebView"]
        direction LR
        Win["Windows: WebView2"] ~~~ Mac["macOS: WKWebView"] ~~~ Linux["Linux: WebKitGTK"]
    end

    py --> rust --> plat

Loading

Threading model: Main thread (event loop + native ops) → Async thread (asyncio + user coroutines) → Thread pool (synchronous code).

Documentation

• Getting Started
• Architecture & Threading Model
• Custom Plugins
• Third-Party Integrations
• Serve Protocol

Installation

pip install --pre lumiview

Quick Start

from lumiview import App, Window, WindowOptions

app = App(name="HelloLumiView")

async def main():
    win = await Window.create(WindowOptions(
        title="Hello LumiView!",
        url="https://example.com",
        width=900, height=640,
        devtools=True,
    ))
    title = await win.eval_js("document.title")
    print(f"Page title: {title}")

app.run(main)

Key Features

• 🧵 Unified async/sync — All cross-thread / async operations return Task. await, .result(), or .on_done() — same API, your choice.
• 🌉 JS ↔ Python Bridge — Expose Python functions to JS via window.lumiview.invoke(). No HTTP server, no manual serialization required.
• 🪟 Native window effects — Acrylic, Mica, Vibrancy via window-vibrancy.
• 🎨 Custom titlebar — Declarative data-lumiview-drag-region drag areas + built-in lumiview.window.* JS API (minimize / maximize / close).
• 📋 Native menus — Per-item on_activate callbacks + global MenuItemActivatedEvent; macOS default app menu installed automatically, window menu bars on Windows.
• 🎛️ System tray — Cross-platform tray icons with context menus and click events; close-to-tray pattern.
• 📁 Static serving & WSGI & ASGI — Directly load local files, proxy to WSGI apps (Flask, Django, etc.), or run FastAPI/Starlette apps without external servers.

Logging

LumiView logs to the lumiview logger tree using the standard logging configuration. To see internal diagnostics, raise the level of the lumiview logger:

import logging

logging.getLogger("lumiview").setLevel(logging.INFO)   # lifecycle events
logging.getLogger("lumiview").setLevel(logging.DEBUG)  # + scheduling / dispatch

When reporting a bug, please include the DEBUG log output from your repro — it covers window / tray lifecycle and event dispatch, which usually pinpoints the issue. See CONTRIBUTING.md.

For runnable code, see the examples/ directory.

Examples

Example	Description
hello_world.py	Minimal app — create window, load URL (async)
hello_world_sync.py	Same as above, using .result() — pure synchronous style
bridge_demo.py	JS ↔ Python IPC — sync/async commands, error handling
multi_window.py	Multi-window + shared WebContext
custom_titlebar.py	Frameless window + native effects + drag regions
events.py	App/Window hook events + JS event emission
fastapi_demo.py	FastAPI running via source=ASGI(...)
django_demo.py	Django running via source=WSGI(...) — template rendering, form POST, JSON APIs
menu.py	Native menus — accelerators, on_activate callbacks, macOS app menu / Windows window menu bar
tray.py	System tray — close-to-tray pattern, tray context menu

Development Status

• Window management (TaoWindow + Window)
• WebView embedding (wryview)
• JS ↔ Python Bridge (invoke/listen IPC)
• Event class system (WindowEvent / AppEvent)
• Unified async/sync Task interface
• Static file serving + WSGI proxy
• ASGI adapter (FastAPI, Starlette, etc.)
• Native window effects (Acrylic / Mica / Vibrancy)
• Custom titlebar
• Native menus (muda)
• System tray (tray-icon)
• API stabilization (maybe 0.2.x)
• Complete documentation site

Contributing

This is an early-stage project — your feedback is crucial.

Due to limited personal time, some features may not be completed promptly — PRs and other contributions are warmly welcomed.

• 🐛 Report Bugs
• 💡 Share Ideas
• 🔧 Contribution Guide

Please read CONTRIBUTING.md before submitting PRs — the API is still in flux and significant changes require prior discussion.

License

Copyright (c) 2026 Xiaosu.

Distributed under the terms of the Mozilla Public License Version 2.0.