██   ██  █████  ████████ ██    ██ ███    ██    | by zek. @/zektrace. 
██  ██  ██   ██    ██    ██    ██ ████   ██    | ---------------->
█████   ███████    ██    ██    ██ ██ ██  ██    | Python desktop apps
██  ██  ██   ██    ██    ██    ██ ██  ██ ██    | using web tech with native window control.
██   ██ ██   ██    ██     ██████  ██   ████ ██ | (v1.1.1)

Katun is a Python framework that lets you build desktop applications using HTML, CSS, JavaScript (and even Node.js frameworks like Vue, React, or Next.js) while giving you full control over the native window via the Windows API (with cross‑platform support planned). It provides a bidirectional communication channel between your Python backend and the web frontend, enabling you to create rich, interactive apps with the simplicity of web development and the power of Python.

Key features:

• Native window control: customize title, size, resizable, frameless, always‑on‑top, and more.
• Bidirectional messaging: send JSON events between Python and JavaScript seamlessly.
• Modular architecture: clean, maintainable code with local relative imports; no installation needed – just clone and run.
• Ready‑to‑use examples: includes a simple “Hello World” app and a role‑based bank emulator.
• Full test suite: unit and integration tests with pytest.

Perfect for building tools like a modern web UI.

git clone https://github.com/zektrace/Katun.git
cd Katun
pip install -r requirements.txt

The framework uses pywebview (or WebView2 on Windows) as the underlying web view. No additional system‑wide installation is required.

Katun does not expose a CLI by itself. Instead, you run your application via the provided run.py entry point. Examples:

# Run the simple example
cd examples/simple_app
python run.py

# Run the bank emulator
cd examples/bank_emulator
python run.py

For your own projects, create a similar run.py that imports katun and launches your app.

Configuration is handled through an AppConfig object. You can set window properties, frontend paths, and more. Edit the configuration file in your project or pass parameters directly.

from katun import Window, Bridge, AppConfig

config = AppConfig(
    title="My App",
    width=1024,
    height=768,
    resizable=True,
    frameless=False,
    always_on_top=False,
    frontend_dir="./frontend"   # Path to your HTML/JS files
)

bridge = Bridge()
window = Window(config, bridge)
window.run()

For advanced customization, see the config module.

You can package your Katun application into a single executable using PyInstaller.

# Install PyInstaller
pip install pyinstaller

# Build as a folder (faster startup)
pyinstaller run.py --name MyApp --add-data "frontend;frontend"

# Build as a single file (easier distribution)
pyinstaller run.py --name MyApp --onefile --add-data "frontend;frontend"

Current: v1.1.1

• Initial release with core window management and bridge communication.
• Support for Windows WebView2 and fallback to pywebview.
• Two demo applications (simple app and bank emulator).
• Comprehensive documentation and test suite.

• Python 3.10+
• pywebview or WebView2 runtime (included in Windows 11, or download for older systems)
• PyInstaller for standalone builds. (Optional)