Metadata-Version: 2.5
Name: wesktop
Version: 0.12.2
Summary: A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Project-URL: Homepage, https://smmh.dev/wesktop/
Project-URL: Documentation, https://smmh.dev/wesktop/
Project-URL: Repository, https://github.com/smm-h/wesktop
Project-URL: Issues, https://github.com/smm-h/wesktop/issues
Project-URL: Changelog, https://github.com/smm-h/wesktop/blob/main/CHANGELOG.md
Author-email: smm-h <smmh72@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: asgi,desktop,desktop-app,granian,gui,pywebview,rlsbl,web,webview
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: fastware[all]
Requires-Dist: pydantic
Requires-Dist: pywebview>=6.2.1
Requires-Dist: strictcli>=0.41.1
Description-Content-Type: text/markdown

<!-- Auto-generated by selfdoc from docs/_README.md — do not edit -->

# wesktop

wesktop is a Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview. It is for Python developers who want to ship a GUI application without Electron, Chromium bundling, or a JavaScript build step. The same app also runs headless as a plain ASGI server, so development, CI, and deployment load no GUI dependency at all.

![Version](https://img.shields.io/pypi/v/wesktop)
![Python](https://img.shields.io/pypi/pyversions/wesktop)
![License](https://img.shields.io/pypi/l/wesktop)
![PyPI](https://img.shields.io/pypi/dm/wesktop)
![npm](https://img.shields.io/npm/v/wesktop)

## What is wesktop?

wesktop combines [fastware](https://github.com/smm-h/fastware) (an ASGI framework) with [pywebview](https://pywebview.flowrl.com/) (native OS windows) to create desktop applications using Python and web technologies. Define routes in Python, serve them over HTTP, and open a native window -- no Electron, no Chromium bundling, no JavaScript build step required.

## Minimal desktop app

```python
import wesktop

router = wesktop.Router()

@router.get("/")
async def index(req: wesktop.Request):
    return wesktop.HTMLResponse("<h1>Hello from wesktop</h1>")

@router.get("/api/health")
async def health(req: wesktop.Request):
    return {"status": "ok"}

app = wesktop.create_app(router)

# Desktop mode: starts server + opens a native OS window
wesktop.run("myapp:app", title="My App", width=1024, height=768)
```

## Headless server

For development, CI, or server-only deployment -- no GUI dependency is loaded:

```python
wesktop.serve("myapp:app", foreground=True, host="127.0.0.1", port=8000)
```

## Why not Electron?

| | wesktop | Electron |
|---|---|---|
| Language | Python | JavaScript |
| Runtime | System Python + OS WebView | Bundled Chromium |
| Bundle size | ~50 KB (pip install) | ~150 MB+ |
| Memory | Shared OS WebView process | Dedicated Chromium per app |
| Native feel | Uses platform WebView (WebKit/Edge) | Chrome-based, uniform look |
| Installation | `pip install wesktop` | Custom installer per app |

## Architecture

wesktop is built on two layers:

- [**fastware**](https://github.com/smm-h/fastware) -- ASGI framework providing routing, SSE, middleware, dependency injection, authentication, and server lifecycle management via granian. fastware is a standalone package usable without wesktop for headless web services.
- **wesktop** -- Desktop integration layer: pywebview native windows, desktop entry creation, server-driven UI primitives, and CLI diagnostics. Imports fastware and adds everything needed to ship a desktop application.

## Key features

- Native OS windows via pywebview (WebKit on Linux/macOS, Edge WebView2 on Windows)
- ASGI micro-router with `{param}` placeholders and static file serving
- SSE broadcaster with typed events and per-client queues
- Granian (Rust-based) server lifecycle with PID management
- Desktop entry creation (Linux `.desktop`, macOS `.app`, Windows Start Menu)
- Server-driven UI primitives (40 SDUI components across 6 categories)
- Dependency injection, authentication, middleware, and feature flags
- MCP server support for role-based agent tool provisioning
- CLI diagnostics (`wesktop diagnose`)

## Installation

```bash
pip install wesktop
```

The CLI is also available as an npm shim:

```bash
npx wesktop diagnose
```

## CLI

| Command | Description |
| --- | --- |
| `diagnose` | Check runtime environment, installed dependencies, and configuration paths |
| **config** | Manage persistent configuration values stored in the config file |
| `config path` | Print the absolute path to this application's config file and nothing else, so the value can be piped straight into another command. The path is $XDG_CONFIG_HOME/<app>/config.<toml\|json> (falling back to ~/.config), or the explicit override the application was built with. Printing it does not create the file, and reports the same path whether or not one exists yet. |
| `config show` | Show every flag and config field with its effective value and where that value came from, resolved through the precedence chain environment variable, then config file, then declared default. Declared infrastructure roots, handshake and connection environment variables are listed too. Choose --plain for an aligned human-readable table; the framework-owned --json yields the same information as a machine-readable object carrying each entry's type, default and help text. |
| `config set` | Write a persistent value into the config file so it overrides a flag's declared default on every later run. The value is coerced to the flag's own type and rejected if it does not fit: repeatable flags take a comma-separated list (backslash-escape a literal comma) and are checked for duplicates, dict flags take a JSON object. Use --default to drop a key back to its default, and --clear to empty a repeatable flag. |
| `config edit` | Open this application's config file in the editor named by $EDITOR, falling back to vi. The parent directory and an empty config file are created first if they do not exist, so the editor always opens something. Launching the editor counts as a mutation: under --dry-run the command records the editor invocation and opens nothing. |
| `config init` | Create a starter config file listing every flag and config field the application declares, each commented with its help text, type and default value, so the file documents itself. The format follows whichever of TOML or JSON the application was built for. Refuses with an error if a config file already exists rather than overwriting it; the created path is printed on success. |

## Module layout

- **src.wesktop** (`src/wesktop/__init__.py`): wesktop — A Python framework for building web-based desktop applications.
- **src.wesktop.__main__** (`src/wesktop/__main__.py`): CLI entry point enabling `python -m wesktop` for diagnostics and configuration management via strictcli.
- **src.wesktop.asgi** (`src/wesktop/asgi.py`): Full-featured ASGI framework re-exported from fastware: Router, Request, response types, WebSocket, app factory, middleware, and type aliases.
- **src.wesktop.audit** (`src/wesktop/audit.py`): Append-only JSONL audit log writer re-exported from fastware for recording timestamped application events with structured payloads.
- **src.wesktop.auth** (`src/wesktop/auth.py`): Authentication module re-exported from fastware: JWT token creation and verification, bcrypt password hashing, user stores, CSRF, and rate limiting.
- **src.wesktop.cli** (`src/wesktop/cli.py`): wesktop CLI providing diagnostics (Python version, dependency versions, platform info) and configuration management via strictcli subcommands.
- **src.wesktop.config** (`src/wesktop/config.py`): Config loading utility re-exported from fastware: standalone TOML config file parsing with optional Pydantic validation and environment overrides.
- **src.wesktop.desktop** (`src/wesktop/desktop.py`): Native desktop window via pywebview, backed by a detached Granian ASGI server, with cross-process window refcounting and automatic server lifecycle.
- **src.wesktop.dev** (`src/wesktop/dev.py`): Development mode re-exported from fastware: combined Vite frontend and ASGI backend in a single command with hot reload and proxy routing.
- **src.wesktop.di** (`src/wesktop/di.py`): Dependency injection container re-exported from fastware: per-request resolution with automatic caching, generator cleanup, and override support.
- **src.wesktop.entries** (`src/wesktop/entries.py`): Cross-platform desktop entry creation and removal for Linux .desktop files, macOS .app bundles, and Windows Start Menu shortcuts.
- **src.wesktop.error_log** (`src/wesktop/error_log.py`): SQLite-backed error log re-exported from fastware for recording and querying 5xx server responses with request context and tracebacks.
- **src.wesktop.features** (`src/wesktop/features.py`): Boolean feature flags re-exported from fastware with per-machine JSON overrides, runtime toggle, enabled/disabled checks, and hot reload support.
- **src.wesktop.logging** (`src/wesktop/logging.py`): Structured logging configuration re-exported from fastware: structlog with automatic JSON output in production and colored console in development.
- **src.wesktop.mcp** (`src/wesktop/mcp.py`): wesktop's agent role registry plus the MCP server factory that wraps fastware: per-role tool provisioning for implementor, auditor, reviewer, and deployer agents.
- **src.wesktop.mcp_tools** (`src/wesktop/mcp_tools/__init__.py`): Tool implementations for the MCP agent server: filesystem access, git operations, testing, deployment, code review, and interactive user prompts.
- **src.wesktop.mcp_tools._http** (`src/wesktop/mcp_tools/_http.py`): Shared authenticated-HTTP helper for the HTTP-backed MCP tool modules.
- **src.wesktop.mcp_tools._paths** (`src/wesktop/mcp_tools/_paths.py`): Shared worktree path-traversal guard for the MCP tool modules.
- **src.wesktop.mcp_tools.ask_user** (`src/wesktop/mcp_tools/ask_user.py`): Ask-user MCP tool: posts a question to the wesktop dashboard via HTTP API and polls for the user's answer with configurable timeout.
- **src.wesktop.mcp_tools.deployment** (`src/wesktop/mcp_tools/deployment.py`): Deployment MCP tools that delegate staging, production PR creation, and pipeline status checks to the wesktop server API.
- **src.wesktop.mcp_tools.filesystem** (`src/wesktop/mcp_tools/filesystem.py`): Filesystem MCP tools scoped to an agent's worktree: read, write, edit, list, and search files with path traversal guard enforcement.
- **src.wesktop.mcp_tools.git** (`src/wesktop/mcp_tools/git.py`): Git MCP tools scoped to an agent's worktree: status, diff, commit, and log commands with timeout enforcement and -C path isolation.
- **src.wesktop.mcp_tools.review** (`src/wesktop/mcp_tools/review.py`): Review MCP tools for posting inline comments on code changes, delegating to the wesktop server API for persistent review storage.
- **src.wesktop.mcp_tools.testing** (`src/wesktop/mcp_tools/testing.py`): Testing MCP tools that delegate test suite execution, result collection, and coverage reporting to the wesktop server API endpoint.
- **src.wesktop.middleware** (`src/wesktop/middleware.py`): Pure ASGI middleware re-exported from fastware: request tracing, CORS headers, trusted-host validation, and Vite dev proxy routing.
- **src.wesktop.runtime_bridge** (`src/wesktop/runtime_bridge.py`): Host-side native bridge for reacting to fastware build changes.
- **src.wesktop.sdui** (`src/wesktop/sdui.py`): Pydantic schemas for all 40 SDUI (Server-Driven UI) primitives: layout containers, text, buttons, forms, tables, charts, and status indicators.
- **src.wesktop.server** (`src/wesktop/server.py`): Granian ASGI server lifecycle re-exported from fastware: PID file tracking, port availability checks, foreground and background serve modes.
- **src.wesktop.sse** (`src/wesktop/sse.py`): SSE (Server-Sent Events) broadcaster re-exported from fastware: typed events, per-client async queues, automatic disconnect pruning, and strict mode.
- **src.wesktop.tasks** (`src/wesktop/tasks.py`): Background task registry re-exported from fastware: feature-gated lifecycle management with start/stop protocol and graceful shutdown ordering.
- **src.wesktop.testing** (`src/wesktop/testing.py`): Sync and async test clients re-exported from fastware for exercising wesktop ASGI routes without starting a real network server or GUI window.

## Dependencies

| Package | Version Constraint |
| --- | --- |
| `fastware[all]` | * |
| `pywebview` | >=6.2.1 |
| `strictcli` | >=0.41.1 |
| `pydantic` | * |

## Documentation

Full documentation is available at [wesktop.smmh.dev](https://wesktop.smmh.dev).

## License

MIT
