Create a cross-platform, native, webview-based GUI using Rust and pure Python asyncio.

[AriBermeki]

PyOrion

Hello everyone 👋
I’m posting this here because maybe you’re interested in trying it out or even contributing.

I’ve developed PyOrion – a framework that enables Python developers to build fully asynchronous, native, web-based GUIs.
The idea was born because existing solutions like pywebview, PySide/Qt, or wxWidgets always run into the same problem:
the GUI event loop blocks the Python main thread or makes asynchronous programming unnecessarily complicated.

So I took a different approach:
The GUI loop runs entirely in a separate Rust process, while communication with Python happens asynchronously via Unix Domain Sockets or Named Pipes.
This allows us to leverage the system’s native WebView engines – with no separate servers, no blocking, and true cross-platform support.

---

🚨 The Problem with Existing Solutions

• pywebview

  • Uses native WebViews, but runs the event loop in the same process as Python.
  • Result: The Python main thread is blocked.
  • Asynchronous workflows are possible, but only through queues or callbacks → messy and hard to maintain.

• PySide / Qt

  • Powerful, but heavyweight: huge runtimes, complex dependencies.
  • Async support only via hacks or threading.

• wxWidgets / Tkinter

  • Outdated, minimal web support, blocking event loops.

Core Issue:
All these frameworks tightly couple the GUI loop to the Python main thread → blocking Python’s modern async world (asyncio, FastAPI, etc.).

---

✅ My Approach: PyOrion

• Multiprocessing with Rust
  The GUI is built using pyo3 and the Tauri Toolkit, running in its own Rust process.
  Each process has its own main thread → the event loop runs system-conformant, without blocking Python.

• Native WebView Engine

  • macOS → WKWebView
  • Windows → WebView2
  • Linux → WebKitGTK
  • Android → System WebView
    → No additional HTTP or WebSocket server required.

• Asynchronous Communication

  • Currently implemented with a WebSocket bridge.
  • Soon to be replaced with wry’s ipc_handler → more direct, higher performance, no script injection overhead.

• Cross-Platform Uniformity
  macOS, Linux, Windows, Android, iOS → the same architecture everywhere:
  Rust handles the GUI event loop, Python stays 100% async.

---

⚙️ Architecture Overview

• Startup Phase
  Python launches the Rust process and passes initial configuration (window, options, ports).

• IPC Layer
  Bidirectional communication between Python and Rust.

  • Windows → Named Pipes
  • Unix → UDS file descriptors
    Deeply integrated with Rust’s GUI event loop.

• Script Injection
  At startup, Rust injects a small script into the WebView (JS) to provide the PyOrion API.

• WebView Runtime

  • Window management: TAO
  • WebView rendering: WRY
  • Unified access to WKWebView, WebView2, WebKitGTK, Android WebView.

---

📚 API Reference

WindowBuilder Methods

Used to configure and initialize a window.

• with_always_on_bottom()
• with_always_on_top()
• with_closable()
• with_content_protection()
• with_decorations()
• with_focused()
• with_fullscreen()
• with_inner_size()
• with_inner_size_constraints()
• with_max_inner_size()
• with_maximizable()
• with_maximized()
• with_min_inner_size()
• with_minimizable()
• with_position()
• with_resizable()
• with_theme()
• with_title()
• with_transparent()
• with_visible()
• with_visible_on_all_workspaces()
• with_window_icon()

Window Methods

Runtime operations for window instances (controllable via IPC).

• available_monitors()
• current_monitor()
• cursor_position()
• drag_resize_window()
• drag_window()
• fullscreen()
• id()
• inner_position()
• inner_size()
• is_closable()
• is_decorated()
• is_focused()
• is_maximizable()
• is_maximized()
• is_minimizable()
• is_minimized()
• is_resizable()
• is_visible()
• monitor_from_point()
• outer_position()
• outer_size()
• primary_monitor()
• request_redraw()
• request_user_attention()
• scale_factor()
• set_*() methods (e.g. set_title, set_resizable, set_visible, …)
• theme()
• title()

WebViewBuilder Methods

Used to configure and initialize a WebView.

• with_accept_first_mouse()
• with_asynchronous_custom_protocol()
• with_autoplay()
• with_back_forward_navigation_gestures()
• with_background_color()
• with_bounds()
• with_clipboard()
• with_devtools()
• with_document_title_changed_handler()
• with_download_*_handler()
• with_drag_drop_handler()
• with_focused()
• with_headers()
• with_hotkeys_zoom()
• with_html()
• with_incognito()
• with_initialization_script()
• with_navigation_handler()
• with_new_window_req_handler()
• with_on_page_load_handler()
• with_proxy_config()
• with_transparent()
• with_url()
• with_user_agent()
• with_visible()
• with_web_context()

WebView Methods

Runtime operations for WebViews.

• bounds()
• clear_all_browsing_data()
• close_devtools()
• evaluate_script()
• focus()
• is_devtools_open()
• load_url()
• open_devtools()
• print()
• set_background_color()
• set_bounds()
• set_visible()
• url()
• zoom()

Native Capabilities

Planned or partially implemented extensions:

• clipboard
• controlcenter
• dialog
• dirs
• webview
• window
• os_info
• tray-icon
• global-hotkey
• menu

---

🔗 Command System & JavaScript API

Inspired by Tauri:

• JavaScript can call Python commands via window.invoke().
• Python can send events and commands to JS (and vice versa).
• Fully asynchronous, IPC-based, isolated from existing frameworks.

Integration with Python Frameworks

PyOrion can be embedded into existing Python web frameworks, e.g.:

• Reflex
• NiceGUI
• Rio
• NextPy
• Dara
• Streamlit
• Gradio
• Dash
• Workcell

Example: JS → Python

window.invoke("get_user", { id: 42 }).then(user => {
  console.log("User:", user);
});

from pyorion import command

@command
async def get_user(id: int):
    return {"id": id, "name": "Alice"}

---

🔑 Key Features

• 🚀 Ultra-lightweight
• 🖥 📱 Cross-Platform (macOS, Windows, Linux, Android, iOS)
• 🦀 Modern Core: Rust (TAO + WRY)
• 🔒 Security-focused
• ⚡ High Performance, small binaries
• 🔌 Native integrations
• 🔄 Async Command System (Tauri-style)

---

🤝 Community & Support

• ⭐ Star the project on GitHub
• 🐛 Report bugs or open issues
• 💡 Propose new features
• 🔧 Submit pull requests
• 📣 Share PyOrion with your network

---

📜 Conclusion

While frameworks like pywebview, Qt, or wxWidgets block Python or add unnecessary overhead, PyOrion takes a new approach:

• GUI loop in a separate process
• Async IPC (soon ipc_handler instead of WebSocket)
• Native WebView integration
• Command system for Python ↔ JavaScript communication (Tauri-inspired)

With PyOrion, it’s finally possible to build truly asynchronous, native, web-based GUIs in Python – lightweight, modern, and cross-platform.