How r0x0r/pywebview works
Project type and purpose
• This is an open-source Python library (“pywebview”) that provides a native desktop GUI window hosting a webview. It exposes a Python API to create windows, serve HTML/JS content (including via a built-in HTTP server), manage the DOM, handle events, and support two-way JS⇄Python communication across multiple OS platforms (Windows, macOS, Linux, Android).
File structure
• Top-level directories
• webview: core Python modules implementing API, window management, HTTP server, DOM wrappers, JS bridging, error handling, menus, state, utility functions
• webview/platforms and webview/__pyinstaller: platform-specific backends (WinForms, Cocoa, GTK, Qt, EdgeChromium, MSHTML, CEF, Android Java interop) and pyinstaller hooks
• interop: example Java and C# code for Android and MSHTML embedding
• examples: sample scripts and mini-apps demonstrating usage, including a Flask integration
• docs and docs/.vuepress: site source and generated static HTML for documentation
• tests: unit and integration tests validating functionality on each platform
• Configuration/build files
• pyproject.toml, requirements.txt: dependencies and packaging
• MANIFEST.in, setup metadata for PyPI
• GitHub workflows, appveyor.yml: CI for builds/tests
README for additional insights
• Confirms cross-platform support, built-in HTTP server, DOM support, JS API, window manipulation, event system.
• Points to architecture guide in docs (“docs/guide/architecture.md”).
Key components
a. Core Python API Layer
• webview.create_window, webview.start, event handlers
b. Built-in HTTP Server
• Serves local HTML/JS, optional Python back end for dynamic content
c. DOM & JS Bridge
• Python DOM wrappers (webview.dom.*), JS API scripts injected into the webview, two-way communication channel
d. Native GUI Backends
• Platform modules under webview/platforms: WinForms (Windows), Cocoa (macOS), GTK/Qt (Linux), EdgeChromium, CEF, Android WebView
• Each wraps the OS’s native web component
e. Interop Layer
• JNI/JInterface for Android, COM interop for MSHTML (Windows)
f. External Dependencies
• Python interpreter, platform libraries (GTK, Qt), Java (Android), .NET (WinForms), WebView2 runtime (EdgeChromium)
Relationships and interactions
• The Python API Layer calls into the Native GUI Backends via the Interop Layer
• When serving dynamic content, the Built-in HTTP Server supplies pages to the webview
• Injected JS API establishes a bidirectional channel:
Python ←→ JS within the webview
• DOM wrappers allow Python code to query and manipulate the in-page DOM
• Events generated in JS or on the native window propagate back to Python event handlers
Architectural patterns and design principles
• Modular platform-abstraction: a common API delegates to platform backends via a plugin-like directory (single responsibility per module)
• Adapter pattern: each platform module adapts the native web component to the unified Python API
• Facade pattern: the top-level webview module hides underlying complexity
• Two-way binding/event system for JS⇄Python communication
Essential architectural elements to capture
• Unified Python API façade
• Platform adapter modules (for each OS/renderer)
• Interop layer for language/ABI bridging
• JS injection and DOM bridge
• Optional HTTP server serving content to the webview
• Data flows: API→Native, Native events→API, JS↔Python