#API Reference

wesktop exposes 116 public symbols via import wesktop. Most of these are re-exports from fastware -- the ASGI micro-framework that provides routing, responses, SSE, middleware, auth, dependency injection, config, testing, server lifecycle, background tasks, feature flags, audit logging, error logging, and MCP support. For documentation on those symbols, see the fastware API reference.

This page documents the symbols that are native to wesktop -- the desktop shell, entry management, SDUI primitives, GUI backend detection, and dev mode. The library is validated by 131 tests across 8 test modules.

#Desktop Window

The desktop module provides the run() function for launching native OS windows backed by a Granian ASGI server in a daemon thread. The pywebview dependency is late-imported, so headless deployments that only use serve() never load the GUI library.

#src.wesktop.desktop

Native desktop window via pywebview, backed by a Granian ASGI server in a daemon thread, with automatic server lifecycle and window close handling.

#ensure_gui_backend

def ensure_gui_backend() -> bool

Make pywebview's GUI backend importable in isolated venvs.

If gi (PyGObject) is not importable, searches common system site-packages locations and adds the first one found to sys.path. Returns True if a backend is available, False otherwise.

#_has_gui_backend

def _has_gui_backend() -> bool

Probe whether pywebview can load a GUI backend (GTK or Qt).

Returns True if at least one backend is loadable, False otherwise. On non-Linux platforms, always returns True (pywebview uses native APIs).

#_entry_exists

def _entry_exists(name: str) -> bool

Check whether a desktop entry already exists for name on the current platform.

#_auto_register_entry

def _auto_register_entry(title: str, icon: str | None) -> None

Create a desktop entry for this app if one doesn't exist.

Self-heals: if an existing entry points to a missing launcher script (e.g. the package was reinstalled to a different venv), remove the broken entry so it can be recreated with the current launcher path.

#run

def run(target: str | Callable, *, title: str='wesktop', width: int=1280, height: int=800, icon: str | None=None, host: str | None=None, port: int | None=None, pid_path: Path | None=None, name: str='WESKTOP', pre_serve: Callable[[], None] | None=None, reload: bool=False, js_api: object | None=None, single_instance: bool=True) -> None

Start server + open native desktop window. Blocks until window closes.

#wesktop.run(target, *, title, width, height, icon, host, port, pid_path, name, pre_serve, reload, js_api, single_instance)

Start a granian server in a background thread and open a native desktop window via pywebview. Blocks until the user closes the window. This is the primary entry point for desktop applications.

The target parameter is an ASGI import path (e.g., "myapp:app") or a callable. pywebview is late-imported so headless environments that only use serve() never load the GUI dependency. In desktop mode the server binds to a random available port by default (port 0), so multiple instances do not collide.

When single_instance=True (the default) and a pid_path is provided, run() checks for an already-running server. If found, it opens a new window pointing at the existing server instead of starting a second one.

#wesktop.ensure_gui_backend()

Make pywebview's GUI backend importable in isolated virtual environments. If gi (PyGObject) is not importable, searches common system site-packages locations (Linux, macOS Homebrew, macOS Framework) and adds the first match to sys.path. Returns True if a backend is available, False otherwise. Called automatically by run().

#Desktop Entries

Cross-platform desktop shortcut creation and removal for all 3 major operating systems. On Linux, creates freedesktop-compliant .desktop files in ~/.local/share/applications/ with optional icon installation to ~/.local/share/icons/. On macOS, generates .app bundles in ~/Applications/ with Info.plist and launcher scripts. On Windows, creates Start Menu shortcuts via COM automation with a PowerShell fallback.

#src.wesktop.entries

Cross-platform desktop entry creation and removal for Linux .desktop files, macOS .app bundles, and Windows Start Menu shortcuts.

#create_entry

def create_entry(name: str, command: str, *, icon: str | Path | None=None, comment: str='', categories: str='Utility;') -> Path

Create a platform-native desktop entry. Returns the path of the created entry.

#remove_entry

def remove_entry(name: str) -> bool

Remove a desktop entry. Returns True if something was removed.

#wesktop.create_entry(name, command, *, icon, comment, categories)

Create a platform-native desktop entry so users can launch a wesktop application from their OS application launcher. On Linux, this writes a freedesktop-compliant .desktop file with optional icon installation; on macOS, it creates an .app bundle with an Info.plist and launcher shell script; on Windows, it creates a Start Menu shortcut using COM automation with a PowerShell fallback:

Returns the Path of the created entry.

#wesktop.remove_entry(name)

Remove a previously created desktop entry by its registered name. Searches the platform-specific location (Linux ~/.local/share/applications/, macOS ~/Applications/, Windows Start Menu folder) and deletes both the entry and any installed icon. Returns True if the entry was found and removed, False if no entry with that name existed.

#Development Mode

#wesktop.dev(target, *, vite_command, vite_port, host, port, pid_path, name, pre_serve)

Development mode with Vite frontend hot-reload. Starts a Vite dev server as a subprocess alongside the granian ASGI backend, proxying unmatched frontend requests through ViteDevProxy middleware. Polls the Vite port for readiness (up to 15 seconds) and terminates the Vite process automatically when the server shuts down.

#SDUI Primitives

The SDUI system provides 39 Pydantic-validated node types organized into 6 categories (layout, display, data, input, feedback, overlay) for building dynamic dashboards entirely from the server without shipping custom frontend code.

#SDUINode

Base class for all SDUI nodes.

Every node serialises to {"type": ..., "props": ..., "children": [...]} with an optional "if" key for conditional rendering.

wesktop includes 39 server-driven UI node types for building dynamic dashboards without shipping frontend code. Each model serializes to the {"type", "props", "children"} dict shape expected by the SDUI renderer.

For the full list of SDUI primitives (layout, display, data, input, feedback, overlay), see the auto-generated SDUI reference.

#Grouping

#Quick example

from wesktop.sdui import Stack, Button, Heading, node

# Using model classes
layout = Stack(children=[
    Heading(text="Dashboard", level=1).to_node(),
    Button(label="Deploy", variant="primary", command="deploy").to_node(),
])

# Using the node() helper
tree = node("stack", [node("heading", text="Hello", level=2)])

#Fastware Re-exports

The following 15 modules are re-exported from fastware, providing the full ASGI framework stack (routing, responses, middleware, auth, DI, testing, server lifecycle, and more) without requiring a separate import fastware statement. See the fastware API docs for full documentation.

#Metadata

#__version__

Package version string, read from importlib.metadata at import time. Follows semantic versioning (currently 0.x.x, pre-stable). Available via import wesktop; wesktop.__version__ in Python code and wesktop --version from the command line. The version is set in pyproject.toml and bumped automatically by rlsbl during releases.