Welcome to Webruntime’s documentation!

Introduction

The webruntime module can be used to launch applications based on HTML/JS/CSS. This can be a browser or a runtime that looks like a desktop app, such as XUL (based on Firefox) or NW.js.

Example:

>>> from webruntime import launch
>>> rt = launch('http://xkcd.com', 'app')
...
>>> rt.close()

The only function you need

webruntime.launch(url, runtime=None, **kwargs)

Launch a web runtime in a new process.

Parameters:
  • url (str) – The url to open, e.g. 'http://python.org'. To open a local file use 'file://...'.
  • runtime (str) – The runtime(s) to use. E.g. ‘app’ will open in a desktop-app-like runtime, ‘browser’ in a browser runtime. One can target specific runtimes, e.g. ‘nw-app’ or ‘edge-browser’, or a selection, e.g. ‘chrome-browser or firefox-browser’. Default is 'app or browser'. See below for more information on available runtimes.
  • kwargs – addition arguments specific to the runtime. See the docs of the runtime classes.
Returns:

An object that represents the runtime. For Desktop runtimes it can be used to close the runtime.

Return type:

BaseRuntime

Browser runtimes:

  • browser: open in a browser. Firefox, Chrome and Edge are prefered over the default browser.
  • default-browser: open in the system default browser.
  • firefox-browser: open in Firefox browser.
  • chrome-browser: open in Chrome/Chromium browser.
  • googlechrome-browser or chromium-browser: like chrome-browser, but specific.
  • edge-browser: open in Microsoft Edge browser.
  • ie-browser: open in Microsoft Internet Explorer browser.
  • xx-browser: use webbrowser module to open in browser “xx”.

App runtimes:

  • app: open as desktop app, using firefox-app or nw-app (and chrome-app on Windows).
  • firerox-app: open as desktop app, using Firefox’ app framework (Xul).
  • nw-app: open as desktop app using NW.js.
  • chrome-app: open as desktop-like app via Chrome/Chromium (only works well on Windows).
  • pyqt-app: open as desktop-like app using PyQt/PySide.

The most developed app runtimes are Firefox and NW. The former requires the user to have Firefox installed. The latter can be installed by the user simply by downloading the archive. Firefox is lighter (memory-wise), while NW is based on Chromium, making it heavier. The other app runtimes are useful for testing or development, but should generally be avoided when distributing apps.

Details for each runtime

class webruntime.BaseRuntime(**kwargs)

Base class for all runtimes.

close()

Close the runtime, or kill it if the process does not respond. Note that closing only works for runtimes launched as an app (using launch_app()).

get_exe()

Get the executable corresponding to the runtime. This is usually the path to an executable file, but it can also be a command, or even a stub. Can be None if the runtime is not (yet) installed.

get_install_instuctions()

Get instructions on how a runtime can be installed. Used internally to show useful dialogs.

get_name()

Get the name of the runtime.

get_version()

Get the version of the available runtime (as a string). Can be None if the version cannot be retrieved (e.g. for Edge and IE), or if the runtime is not available on this system.

is_available()

Get whether this runtime appears to be available on this machine.

launch_app(url)

Launch the given url as a desktop application. Only works for runtimes that derive from DeskopRuntime (e.g. not Edge). Apps launched this way can usually be terminated using the close() method.

launch_tab(url)

Launch the given url in a new browser tab. Only works for runtimes that are browsers (e.g. not NW).

class webruntime.DesktopRuntime(icon=None, title=None, size=None, pos=None, windowmode=None, **kwargs)

A base class for runtimes that launch a desktop-like app.

Parameters:
  • title (str) – Text shown in the title bar.
  • icon (str | Icon) – Icon instance or path to an icon file (png or ico). The icon will automatically be converted to png/ico/icns, depending on what’s needed by the runtime and platform.
  • size (tuple of ints) – The size (in pixels) of the window.
  • pos (tuple of ints) – The position (in pixels) of the window.
  • windowmode (str) – the initial window mode, e.g. ‘normal’, ‘maximized’, ‘fullscreen’, ‘kiosk’. Note that not all modes are supported by all runtimes.
get_cached_version()

Get (version, path) for the (highest) version of this runtime that we currently have locally installed.

get_frozen_version()

Get (version, path) for the (highest) version of this runtime that is shipped along with the executable.

get_runtime_dir()

Get the directory of the (up-to-date) local version of the runtime. If necessary, the runtime is cached/installed.

get_system_version()

Get (version, path) for the version of the runtime available on the system. Can be an application, but also an archive or installer. This information is used internally to install or update a runtime.

class webruntime.FirefoxRuntime(icon=None, title=None, size=None, pos=None, windowmode=None, **kwargs)

Runtime based on Mozilla Firefox. Can be used to open an app in Firefox, as well as launch desktop-like apps via Mozilla’s XUL framework. Available if Firefox is installed.

This runtime is visible in the task manager under a custom process name (sys.executable + '-ui'), making it easy to spot in the task manager, and avoids task-bar grouping. Compared to the NW runtime, this runtime is leaner in terms of memory and number of processes, and is also faster.

class webruntime.NWRuntime(icon=None, title=None, size=None, pos=None, windowmode=None, **kwargs)

Desktop runtime based on NW.js (http://nwjs.io, formerly node-webkit), which uses the Chromium engine. We will install/update the runtime if it finds a suitable archive in a few common locations like the desktop, download dir and temp dir. That way, the end-user only has to download the archive to make this runtime work.

This runtime is visible in the task manager under a custom process name (sys.executable + '-ui'), making it easy to spot in the task manager, and avoids task-bar grouping. Compared to the Firefox app runtime, this runtime uses more processes and memory. Chrome used to be faster, but since Firefox Quantum this is no longer the case.

The supported windowmode values are ‘normal’, ‘fullscreen’, ‘kiosk’ (‘maximized’ is ignored).

class webruntime.PyQtRuntime(icon=None, title=None, size=None, pos=None, windowmode=None, **kwargs)

Desktop runtime based on qt-webkit. Launches a new Python process (the same version as the current), and uses PyQt4, PyQt5 or PySide to display the page.

This runtime is not suited for hosting apps created with e.g. flexx.ui; it is included for completeness but should generally be avoided.

class webruntime.ChromeRuntime(icon=None, title=None, size=None, pos=None, windowmode=None, **kwargs)

Runtime representing either the Google Chrome or Chromium browser. This runtime does support desktop-like apps, which works pretty well on Windows, but not so much on OS X and Linux:

  • On Linux it has the Chrome/Chromium icon.
  • On OSX and Linux it groups with the Chrome/Chromium browser.
  • Fullscreen mode does not work on OS X.
class webruntime.GoogleChromeRuntime(icon=None, title=None, size=None, pos=None, windowmode=None, **kwargs)

Runtime based on the Google Chrome browser. Derives from ChromeRuntime.

class webruntime.ChromiumRuntime(icon=None, title=None, size=None, pos=None, windowmode=None, **kwargs)

Runtime based on the Chromium browser. Derives from ChromeRuntime.

class webruntime.EdgeRuntime(**kwargs)

Runtime based on Edge, only for launching in the browser.

class webruntime.IERuntime(**kwargs)

Runtime based on IE (Internet Explorer), only for launching in the browser.

class webruntime.BrowserRuntime(type=None, **kwargs)

Runtime based on the Python webbrowser module. This runtime is used to open a url in the system default browser, and to attempt to handle a given browser name that is unknown to the webruntime module (maybe the webbrowser module knows it).

CLI

Webruntime CLI

Usage:
  webruntime url runtime  launch the url in the given runtime
  webruntime --help       show this help text
  webruntime --version    show webruntime version number

Configuration

webruntime.config

Configuration object for webruntime

The options below can be set from different sources, and are evaluated in the following order:

  • From the default value.
  • From .cfg or .ini file, or a string in cfg format.
  • From environment variables, e.g. WEBRUNTIME_FOO=3.
  • From command-line arguments, e.g. --webruntime-foo=3.
  • From setting the config option directly, e.g. config.foo = 3.

Use print(config) to get a summary of the current values and from which sources they were set.

Parameters:
  • chrome_exe (str) – The location of the Chrome/Chromium executable. Auto-detect by default. (default ‘’)
  • firefox_exe (str) – The location of the Firefox executable. Auto-detect by default. (default ‘’)
  • nw_exe (str) – The location of the NW.js executable. Auto-install by default. (default ‘’)

Indices and tables