pytron-kit 0.2.5

An Electron-like library for Python

Pytron

Pytron is a modern framework for building desktop applications using Python for the backend and web technologies (React, Vite) for the frontend. It combines the power of Python's ecosystem with the rich user interfaces of the web.

Features

• Type-Safe Bridge: Automatically generate TypeScript definitions (.d.ts) from your Python code.
• Reactive State: Synchronize state seamlessly between Python and JavaScript.
• Advanced Serialization: Built-in support for Pydantic models, PIL Images, UUIDs, and more.
• System Integration: Native file dialogs, notifications, and shortcuts.
• Developer Experience: Hot-reloading, automatic virtual environment management, and easy packaging.

Prerequisites

• Python 3.7+
• Node.js & npm (for frontend development)

Linux (Ubuntu/Debian) Requirements

Pytron relies on standard system libraries for the webview. You must install them using your package manager:

sudo apt install libwebkit2gtk-4.1-0 

If you encounter ImportError or OSError related to gobject or glib (especially on Ubuntu 24.04+), you may also need:

sudo apt install libcairo2-dev pkg-config python3-dev libgirepository1.0-dev libgirepository-2.0-dev

Quick Start

1. Install Pytron: Windows:

   pip install pytron-kit
   

   Linux / macOS (Recommended):

   pipx install pytron-kit
   

   Note: On modern Linux distros (Ubuntu 23.04+), pipx involves less risk of breaking system packages (PEP 668).

2. Initialize a New Project: This command scaffolds a new project, creates a virtual environment (env/), installs initial dependencies, and sets up a frontend.

   # Default (React + Vite)
   pytron init my_app
   
   # Using a specific template (vue, svelte, next, etc.)
   pytron init my_app --template next
   

   Supported templates: react (default), vue, svelte, next (Next.js), vanilla, preact, lit, solid, qwik.

3. Install project dependencies (recommended): After cloning or when you need to install/update dependencies for the project, use the CLI-managed installer which will create/use the env/ virtual environment automatically:

   # Creates env/ if missing and installs from requirements.txt
   pytron install
   

   Notes:

   • This creates an env/ directory in the project root (if not already present) and runs pip install -r requirements.txt inside it.
   • All subsequent pytron commands (run, package, etc.) will automatically prefer the project's env/ Python when present.

4. Run the App: Start the app in development mode (hot-reloading enabled). The CLI will use env/ Python automatically if an env/ exists in the project root.

   • Windows: run.bat
   • Linux/Mac: ./run.sh

   Or manually via the CLI:

   pytron run --dev
   

Core Concepts

1. Exposing Python Functions

Use the @app.expose decorator to make Python functions available to the frontend.

from pytron import App
from pydantic import BaseModel

app = App()

class User(BaseModel):
    name: str
    age: int

@app.expose
def get_user(user_id: int) -> User:
    return User(name="Alice", age=30)

app.generate_types() # Generates frontend/src/pytron.d.ts
app.run()

2. Calling from Frontend

Import the client and call your functions with full TypeScript support. any registered function with "pytron_" prefix will be available as pytron_{function_name} and will not be proxied into the pytron object.

import pytron from 'pytron-client';

async function loadUser() {
    const user = await pytron.get_user(1);
    console.log(user.name); // Typed as string
}

3. Reactive State

Sync data automatically.

Python:

app.state.counter = 0

JavaScript:

console.log(pytron.state.counter); // 0

// Listen for changes
pytron.on('pytron:state-update', (change) => {
    console.log(change.key, change.value);
});

4. Window Management

Control the window directly from JS.

pytron.minimize();
pytron.toggle_fullscreen();
pytron.close();

5. Development Workflow (--dev)

The development mode in Pytron is designed for modern web development workflows.

pytron run --dev

• Dual Hot Reloading:
  • Frontend: Pytron detects your npm run dev script (Vite/Next/WebPack) and proxies the window to your local dev server (e.g., localhost:5173). This gives you Hot Module Replacement (HMR)—UI changes update instantly without a reload.
  • Backend: Pytron watches your Python files. If you change backend logic, the Python application performs a Hot Restart automatically.
• Debug Logging: If debug: true is set in settings.json, Pytron switches to verbose logging, showing bridge messages and binding invocations.
• Non-Blocking UI: Pytron automatically runs synchronous Python functions in a background thread pool, ensuring that heavy Python tasks never freeze the UI.

Configuration (settings.json)

Pytron uses a settings.json file in your project root to manage application configuration.

Example settings.json:

{
    "title": "pytron app",
    "pytron_version": "0.2.2",
    "frontend_framework": "react",
    "dimensions":[800,600],
    "frameless": false,
    "debug": true,
    "url": "frontend/dist/index.html",
    "icon": "assets/icon.ico",
    "version": "1.0.0"
}

• title: The window title and the name of your packaged executable.
• debug: Set to true to enable verbose logging and dev tools.
• url: Entry point for the frontend (usually the built index.html). In --dev mode, this is overridden by the dev server URL.
• icon: Path to your application icon (relative to project root).

UI Components

Pytron provides a set of UI components to help you build a modern desktop application. They have preimplemented window controls and are ready to use.

Usage

npm install pytron-ui

then import the webcomponents into your frontend app

import "pytron-ui/webcomponents/TitleBar.js";
//usage
<pytron-title-bar></pytron-title-bar>
//for react
import { TitleBar } from "pytron-ui/react";
//usage
<TitleBar></TitleBar>

Packaging

Distribute your app as a standalone executable. Pytron automatically reads your settings.json to determine the app name, version, and icon. Note on File Permissions: When your app is installed in Program Files, it is read-only. If your app writes logs or databases using relative paths (e.g., logging.basicConfig(filename='app.log')), it will crash with PermissionError. Pytron Solution: When running as a packaged app, Pytron automatically changes the Current Working Directory (CWD) to a safe user-writable path (e.g., %APPDATA%/MyApp). Your relative writes will safely end up there.

1. Build:

   pytron package
   

CLI Reference

• pytron init <name> [--template <name>]: Create a new project.
• pytron install [package]: Install dependencies.
  • Pin versions in requirements.json.
  • Smartly resolving local path installs to package names.
• pytron frontend install [package]: Install npm packages for the frontend (auto-detects directory).
• pytron run [--dev]: Run the application.
• pytron show: List installed Python packages and versions.
• pytron package: Build standalone executable.

---

Happy Coding with Pytron!