cutec-chris/native_web_app

Use native browsers for Electron-style apps!

native-web-app

A drop-in replacement for Python's webbrowser.open() that opens a native browser window without browser controls. Build Electron-style apps without shipping Electron!

import native_web_app

url = "http://localhost:8000/"

try:
    native_web_app.open(url)
except Exception:
    print(f"No web browser found. Please open a browser and point it to {url}.")

Demo

There is an example app in the repository.

API Documentation

This module exposes a single open function:

def open(url: str, try_app_mode: bool = True) -> None:
    """
    Open a URL in a modern browser.
    In contrast to webbrowser.open, this method gracefully degrades
    to a no-op on headless servers, where webbrowser.open would otherwise open lynx.

    Args:
        url:
            The URL to open, e.g. http://localhost:1234.
        try_app_mode:
            If True, try to open the URL in "app mode", i.e. without browser controls.
            This allows for Electron-like apps without having to deal with Electron.
            If no suitable browser is found, it gracefully falls back to a regular browser instance.

    Raises:
        RuntimeError, if no suitable browser is found.
        OSError, if the browser executable could not be executed.

        For robustness, implementors should catch any Exception and take that as a signal that opening the URL failed.
    """

Compatibility

OS	Browser	Status (✅ app mode, ☑️ regular browser)
Windows 10 (2004)	Google Chrome 84	✅
Windows 10 (2004)	Microsoft Edge 84	✅
Windows 10 (2004)	Windows Subsystem for Linux	☑️
Windows 10 (2004)	Default Browser	☑️
Ubuntu 20.04	Google Chrome 84	✅
Ubuntu 20.04	Default Browser	☑️
macOS Catalina	Google Chrome 84	✅
macOS Catalina	Default Browser	☑️

Firefox implemented app mode ("site-specific browser functionality") in 2020, but enabled it only for https:// URLs. This means it does not work with http://localhost:1234 or file:// URLs. This makes it unsuitable for inclusion in native_web_app.

Changelog

This project follows semantic versioning.

native_web_app 1.0.2 (2020-08-12)

• Add support for Python 3.5 and 3.6.

native_web_app 1.0.1 (2020-08-12)

• Enforce browsers to start in background. This fixes compatibility with Microsoft Edge on Windows 10.
• Extend documentation on compatibility.

native_web_app 1.0.0 (2020-08-11)

• Initial Release

FAQ

How do I detect when the browser window is closed?

Monitoring the spawned browser process does not work reliably across platforms. We recommend you use JavaScript to notify your backend:

window.addEventListener('unload', function() {
    navigator.sendBeacon("/shutdown");
}, false);