creation-framework 0.1.0a2

A Python-first UI framework that runs in the browser using Pyodide. This is a fork of Evolve by Parag Ghatage.

🌍 Creation

The Python-Native Frontend Framework

Build high-performance, reactive web applications entirely in Python.
Powered by Pyodide (WASM) and a fine-grained Solid.js-style reactive engine.

---

Highlights

• ⚡ Zero Virtual DOM: Uses fine-grained signals for direct DOM updates (O(1) complexity).
• 🐍 Python Native: Write components, routing, and logic in pure Python.
• 📦 Tiny Bundle: A minimal JS kernel coupled with an optimized Python environment.
• 🌐 Static Deployment: Builds to pure HTML/CSS/WASM. Deploy to Vercel, Netlify, or GitHub Pages.

---

Creation is a paradigm shift for Python web development. Unlike traditional frameworks that render HTML on the server (Django, Flask) or wrap heavy JS runtimes, Creation runs natively in the browser via WebAssembly.

It features a radical 2KB JavaScript micro-kernel that handles DOM operations, while your application logic, state management, and component rendering happen entirely in Python.

This is a fork of Evolve by Parag Ghatage.

Installation

Requires Python 3.11+.

pip install creation

---

Quick Start

Get a reactive app running in seconds.

1. Initialize a Project

creation init my-app
cd my-app

This creates a simple app.py with example routes.

2. Run the Dev Server

creation run

Visit http://localhost:3000 to see your app.

3. Build for Production

creation build

This compiles your app into .creation/dist/, ready for static hosting.

---

The "Hello World" Component

Creation uses a FastAPI-style decorator syntax. Create an app.py anywhere:

from creation.router.router import page
from creation.src.html import div, h1, button, p
from creation.reactive.reactive import signal

@page("/")
def Home():
    # Reactive state (Signals)
    count = signal(0)

    def increment(ev=None):
        count(count() + 1)

    return div(
        h1("Welcome to Creation 🌍"),
        p(lambda: f"Count: {count()}"),  # Reactive text
        button("Increment", on_click=increment),
        style={"textAlign": "center", "fontFamily": "sans-serif"}
    )

Run it:

creation run app.py

---

Key Features

1. Fine-Grained Reactivity (Signals)

Creation doesn't re-render entire components. When a signal changes, only the specific text node or attribute bound to it updates.

from creation.reactive.reactive import signal, computed

count = signal(0)
double = computed(lambda: count() * 2)

# Use lambda for reactive text that updates automatically
span(lambda: f"Double is: {double()}") 

2. Built-in Routing

A lightweight, history-mode router is included out of the box.

from creation.router.router import page, Link

@page("/about")
def About():
    return div(
        h1("About Us"),
        Link("Go Home", to="/")
    )

3. Tailwind-Style Styling

Creation includes a tw() utility for rapid styling without leaving Python.

from creation.src.html import div, tw

div("Hello", **tw("text-white bg-blue-500 p-4 rounded-lg flex justify-center"))

4. Component Lifecycle

Hook into mount and unmount events for side effects (API calls, subscriptions).

from creation.components.component import component
from creation.core.lifecycle import on_mount, on_cleanup

@component
def Timer():
    on_mount(lambda: print("Component mounted!"))
    on_cleanup(lambda: print("Cleaned up!"))
    return div("Timer Component")

---

Architecture

Creation bridges the gap between Python and the Browser DOM using a highly efficient architecture:

flowchart TD
    subgraph Browser ["Browser (WASM Context)"]
        direction TB
        App[Your App.py] --> Reactive[Reactive Engine]
        Reactive --> Diff[Diff Engine]
        Diff --> Patch[Patch List]
    end

    subgraph Kernel ["JS Micro-Kernel"]
        Bridge[Pyodide Bridge]
        RealDOM[Real DOM]
    end

    Patch -- "Serialized Ops" --> Bridge
    Bridge --> RealDOM
    RealDOM -- "Events" --> App

1. Python Layer: Calculates changes using Signals.
2. Diff Engine: Generates a minimal list of DOM operations (patches).
3. JS Kernel: A tiny JavaScript layer receives patches and applies them to the real DOM.

---

Project Structure

When you run creation init, the following structure is created:

my-app/
├── components/       # Reusable UI components
├── pages/            # Route handlers (@page)
├── public/           # Static assets (images, fonts)
├── creation.zip      # Packed engine (generated on build)
└── app.py            # Entry point (auto-generated)

---

Roadmap

• v0.1: Core Reactive Engine & JS Kernel
• v0.1: Component System & Routing
• v0.1: CLI (init, build, run)
• v0.2: Global State Management (Store)
• v0.3: Form Handling & Validation
• v0.4: Server-Side Rendering (SSR) capabilities
• v1.0: Full WASM Component Model Support

---

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to set up the development environment.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

License

Distributed under the MIT License. See LICENSE for more information.