Reference for flexx.webruntime

Webruntime introduction

The webruntime module can be used to launch a runtime for applications based on HTML/JS/CSS. This can be a browser or something that looks like a desktop app.


Webruntime API

flexx.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’. If not given uses the value of flexx.config.webruntime, which defaults to '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:

runtime (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, but generally faster. The other app runtimes are useful for testing or development, but should generally be avoided when distributing apps.


class flexx.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 flexx.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 flexx.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.

class flexx.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. Flexx 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, but is generally faster.

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

class flexx.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 flexx.ui; it is included for completeness but should generally be avoided.

class flexx.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 flexx.webruntime.GoogleChromeRuntime(icon=None, title=None, size=None, pos=None, windowmode=None, **kwargs)

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

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

Runtime based on the Chromium browser. Derives from ChromeRuntime.

class flexx.webruntime.EdgeRuntime(**kwargs)

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

class flexx.webruntime.IERuntime(**kwargs)

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

class flexx.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 Flexx (maybe the webbrowser module knows it).