cactuscat 0.1.9

The ultra-fast, Rust-powered bridge between Python and the Web.

CactusCat

The ultra-fast, Rust-powered bridge between Python and the Web.

CactusCat is a modern, high-performance hybrid framework designed to build desktop applications using Python for logic and Modern Web Tech (React, Vue, Svelte, Next.js) for the UI. Rebuilt from the ground up in Rust, it provides a "Zero-Cost" abstraction layer for enterprise-grade applications.

---

Recent Evolution: The "Betrayal of Tauri"

CactusCat has evolved beyond a simple WebView wrapper. It is now a Multi-Engine Application Platform.

• CNB (Cactus Native Bundle): A new hybrid packaging paradigm. We use PyInstaller for dependency analysis (tree-shaking) but replace the actual bundling with a high-performance Rust Packer.
• Shielded VFS Bootloader: Applications run inside a memory-backed, isolated, and encrypted Virtual File System. Your source code never touches the disk in plain text.
• Multi-Engine Hotswapping: Hotswap your browser backend with a single CLI flag. Use the lightweight Native Engine (Tao/Wry) for performance, or the Chrome Engine (Enterprise Chromium stack) for full web compatibility.
• Aggressive Pruning: The native Rust packer prunes non-essential metadata (.dist-info, test suites, docs) resulting in binaries significantly smaller than standard Python bundlers.

---

Features

• Native Rust Engine: Built on tao and wry, eliminating legacy ctypes overhead.
• Multi-Engine Runtime: Choose between Native WebView or a full Chromium/Electron stack.
• Reactive State: Magic bi-directional sync between Python app.state and JavaScript ccat.state.
• Zstd-Compressed Archives: Custom .cat archive format for ultra-fast startup and small footprints.
• MetaEdit Integration: Powered by the brand new metaedit Rust crate for 1:1 binary metadata surgery.
• Powerhouse CLI: One-stop shop for initializing, running, and packaging your apps.

---

Quick Start

1. Installation

Install the development version (pre-compiled wheels available):

pip install cactuscat

2. Scaffold a New Project

cactuscat init MySweetApp --template react

3. Run with Engine Hotswapping

# Default Native Run
cactuscat run --dev

# Run with Enterprise Chrome Engine
cactuscat run --dev --engine chrome

---

Code Example

Python Backend (app.py)

from cactuscat import App

app = App()
app.state.counter = 0

@app.expose
def increment():
    app.state.counter += 1
    return f"Count is now {app.state.counter}"

app.run()

Frontend UI (App.jsx)

import ccat from 'ccat' // Unified CactusCat Client

async function handleAction() {
    // Dynamic Python calling
    const msg = await ccat.increment();
    console.log(msg);
    
    // Access reactive state directly
    console.log(ccat.state.counter); 
}

---

CLI Reference

Command	Description
init	Scaffold a project with React, Vue, Svelte, or Next.js.
run --dev	Launch backend + frontend dev server with hot-reload.
run --engine <name>	Launch with a specific engine (native or chrome).
package --native	Trigger the [CNB] workflow with aggressive Rust pruning.
package --secure	Build a native Rust bootloader with an encrypted payload.
engine install	Manage browser runtimes (e.g., download Chrome engine).
doctor	Comprehensive system health and dependency check.

---

Architecture: The CNB Paradigm

Unlike traditional "OneDir" or "OneFile" approaches, CactusCat's Native Bundle logic works in three stages:

1. Analysis: PyInstaller maps the dependency tree.
2. Pruning: Rust strips the "fat" (PDFs, tests, info folders) and Compresses.
3. Execution: A Rust Bootloader initializes a shielded environment, decrypts the ccat:// assets, and executes the entry point from memory.

---

License

CactusCat is open-source software licensed under the MIT License.