Skip to main content

Architecture

PyWee is an Electron-like runtime for trusted local GUI applications where frontend behavior can be written in Python.

PyWee app
  ├── pywee.toml
  ├── web/index.html
  ├── web/style.css
  └── python/main.py

PyWee runtime
  ├── managed Chromium runtime
  ├── pywee-browser-engine launcher
  ├── Python execution host running in the launcher process
  └── Python DOM/Web API bindings

Runtime Flow​

  1. pywee run <app> loads pywee.toml.
  2. The CLI starts pywee-browser-engine.
  3. The engine resolves Chromium from package data or the PyWee runtime cache.
  4. Chromium loads the local app entry through a loopback app server.
  5. Python scripts are executed for trusted apps.
  6. Python DOM wrappers mutate the live Chromium page and receive events.

The loopback app server serves the whole app root, not only web/. This lets HTML entries refer to project-local assets such as ../assets/logo.svg while still keeping paths relative to the app root.

PyWee never searches for a system Chromium binary. If the managed runtime is not present, PyWee downloads the locked artifact from chromium.lock.json.

Current Binding Layer​

The current implementation uses an internal Python host to control the live Chromium page. This is not the final architecture, but it gives a real graphical renderer, normal CSS, normal JS when enabled, WebGL, and Python-driven DOM updates.

Current Python DOM calls are routed through Chrome DevTools Protocol and private runtime bindings installed into the page. That is an implementation detail of the MVP, not the final binding model. Application code imports browser and uses Python wrapper objects for document, window, events, storage, fetch, console, and selected DOM APIs.

The target binding layer is native:

Python object
    <-> Python C API binding
    <-> Chromium/Blink DOM object

Python Execution​

For pywee run, application Python uses the same Python interpreter environment that launched the pywee CLI. Package requirements are declared in pywee.toml and installed into that active environment with:

pywee pip <app> install-deps

Each app execution adds the app root and app Python directory to sys.path. App-local modules are cleaned from sys.modules after execution so examples and reloaded apps do not accidentally reuse modules from a different app.

Process And Permissions​

Python code is trusted app code. PyWee does not restrict filesystem, network, or subprocess access in its manifest. The process has the same OS rights as the user/environment that launched it.