Skip to main content

PyWee Technical Specification

Version: 0.1-draft

PyWee is an open-source application runtime for trusted local GUI applications. It keeps normal HTML/CSS behavior and lets frontend logic be written in Python through <script type="python">.

This document separates the current MVP from the long-term product target. The current implementation is useful and graphical, but it is not yet the final native Chromium/Blink embedding architecture.

Current MVP State​

The current runtime:

  • is installed as the pywee Python package;
  • starts only the PyWee-managed Chromium runtime;
  • rejects selectable runtime backends and system-browser fallback;
  • loads app configuration from pywee.toml;
  • serves the app root through a local loopback server;
  • executes trusted <script type="python"> blocks and Python script files;
  • uses the Python interpreter/environment that launched pywee;
  • installs app dependencies from [python].requirements with pywee pip;
  • exposes Python DOM wrappers for selectors, text, attributes, classes, events, timers, storage, fetch, console, and selected window/document APIs;
  • forwards relevant browser and Python errors to the terminal;
  • keeps JavaScript available only when [javascript].enabled = true.

The current Python DOM layer controls the live Chromium page through CDP and private runtime bindings. This is an interim implementation detail. It is not a user-facing HTTP, WebSocket, IPC, JSON-RPC, or JavaScript bridge API.

Target Product Architecture​

The long-term product target is:

Chromium / Blink
+ V8 for JavaScript
+ embedded Python runtime in trusted renderer processes
+ native Python DOM/WebIDL bindings
+ app packaging around the managed Chromium runtime

In that target architecture, Python wrapper objects should bind directly to native Chromium/Blink DOM objects through the Python C API or an equivalent native binding layer:

Python object
    <-> Python native binding
    <-> Chromium/Blink DOM object

Goals​

  • Load local HTML/CSS applications.
  • Support Python scripts declared by <script type="python">.
  • Let Python replace JavaScript for frontend behavior in trusted local apps.
  • Keep JavaScript support available for apps that explicitly enable it.
  • Import regular pip packages, including native extension modules.
  • Expose direct Python bindings to DOM and selected Web APIs.
  • Package or download a locked Chromium-based runtime without using a system browser.
  • Block system Python execution for arbitrary remote web pages.

Non-Goals​

PyWee is not PyScript, Pyodide, a WebAssembly Python runtime, a backend server, pywebview/Eel, a QtWebEngine app, Electron, or a general web browser that executes system Python for normal HTTPS pages.

PyWee also does not implement a manifest permission layer for local Python code. Python is trusted application code and has the OS permissions of the process that launched it.

Runtime Strategy​

There is one supported runtime engine: Chromium. The normal package includes a locked Chromium download manifest, and PyWee downloads the runtime into its own cache. Offline bundled wheels may include Chromium directly in package data.

The final implementation should minimize Chromium patch surface by keeping PyWee-specific code in isolated modules where possible. Large upstream fork deltas make rebases and security updates harder.

MVP Completion Criteria​

The current MVP is considered useful when:

  • local HTML/CSS loads in managed Chromium;
  • normal JavaScript runs when enabled;
  • <script type="python"> executes in the active Python interpreter;
  • Python can update DOM text;
  • Python can register click and input event listeners;
  • Python uses the active environment that launched pywee;
  • import numpy works when installed into that environment;
  • Python is only available for trusted local PyWee apps;
  • Python/browser errors are visible in terminal output;
  • examples exist for basic UI, controls, 3D, games, camera/CV, charts, and simulation.