xbot-form 0.2.6

Windows-only Python SDK for rendering JSON Schema forms in WebView2

XBot Form

Windows-only Python SDK for rendering JSON Schema forms in WebView2.

Features

• 🎨 JSON Schema Forms - Render dynamic forms from JSON Schema definitions
• 🖥️ Native Windows UI - Uses WebView2 for modern, native-feeling interfaces
• 🎯 Type-Safe API - Configuration classes with IDE autocompletion support
• 🔗 Fluent Builder - Chainable API for easy form configuration
• 🌙 Theme Support - Light and dark mode themes
• 🪟 Frameless Windows - Optional borderless windows with rounded corners

Installation

pip install xbot-form

Requirements:

• Windows 10/11
• Python 3.8+
• WebView2 Runtime (usually pre-installed on Windows 10/11)

Quick Start

Basic Usage

from xbot_form import show_form

# Window title is automatically extracted from schema["title"]
schema = {
    "type": "object",
    "title": "User Registration",  # <- This becomes the window title
    "properties": {
        "name": {"type": "string", "title": "Name"},
        "email": {"type": "string", "title": "Email", "format": "email"},
    },
    "required": ["name", "email"]
}

result = show_form(schema=schema)
print(f"User submitted: {result}")

# Or override with explicit title parameter
result = show_form(schema=schema, title="Custom Window Title")

Builder Pattern (Recommended)

from xbot_form import form_builder, FormCancelledError

try:
    result = (
        form_builder()
        .schema({
            "type": "object",
            "properties": {
                "username": {"type": "string", "title": "Username"},
                "password": {"type": "string", "title": "Password"},
            }
        })
        .ui_schema({
            "password": {"ui:widget": "password"}
        })
        .title("Login")
        .size(600, 400)
        .frameless(corner_radius=16)
        .theme("dark")
        .show()
    )
    print(f"Login: {result}")
except FormCancelledError:
    print("Login cancelled")

Configuration Classes

from xbot_form import (
    show_form_with_config,
    FormConfig,
    WindowOptions,
    DisplayOptions,
    FormCancelledError
)

config = FormConfig(
    schema={
        "type": "object",
        "properties": {
            "task": {"type": "string", "title": "Task Name"},
            "priority": {
                "type": "string",
                "title": "Priority",
                "enum": ["Low", "Medium", "High"]
            }
        }
    },
    window=WindowOptions(
        width=800,
        height=600,
        title="New Task",
        frameless=True,
        corner_radius=12
    ),
    display=DisplayOptions(
        theme="light",
        debug=False
    )
)

try:
    result = show_form_with_config(config)
    print(f"Task created: {result}")
except FormCancelledError:
    print("Cancelled")

API Reference

Functions

Function	Description
show_form(...)	Display a form with individual parameters
show_form_with_config(config)	Display a form using FormConfig object
form_builder()	Create a FormBuilder for fluent configuration

Configuration Classes

Class	Description
FormConfig	Complete form configuration
FormSchema	JSON Schema with optional UI schema
WindowOptions	Window size, title, frameless settings
DisplayOptions	Theme, debug mode, locale settings
FormBuilder	Fluent builder for form configuration

Exceptions

Exception	Description
XBotFormError	Base exception for all SDK errors
FormCancelledError	User cancelled or closed the form
FormTimeoutError	Form display timed out
WebViewError	WebView2 initialization error
WebViewNotAvailableError	WebView2 runtime not installed
WindowError	Window creation error

Parameters

show_form()

Parameter	Type	Default	Description
schema	dict	None	JSON Schema for the form (supports title for window title)
title	str	None	Window title. Priority: title > schema["title"] > "应用配置"
width	int	1000	Window width in pixels
height	int	800	Window height in pixels
frameless	bool	True	Borderless window mode
corner_radius	int	32	Corner radius for frameless windows
debug	bool	False	Enable DevTools
theme	str	"light"	Color theme ("light" or "dark")

License

MIT License - see LICENSE for details.