Evolve

<div align="center"> <h1>🧬 Evolve</h1> <p><strong>The Python-Native Frontend Framework</strong></p> <p><em> v1 coming soon! Evolve is actively evolving - polishing the reactive engine & browser kernel before final release.</em></p> <p> <a href="https://pypi.org/project/evolve/"> <img src="https://img.shields.io/badge/pypi-v0.1.0-blue?style=flat-square&logo=pypi&logoColor=white" alt="PyPI Version" /> </a> <a href="#"> <img src="https://img.shields.io/badge/python-3.11+-yellow?style=flat-square&logo=python&logoColor=white" alt="Python Version" /> </a> <a href="LICENSE"> <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" /> </a> </p> <p> Build high-performance, reactive web applications entirely in Python.<br/> Powered by <strong>Pyodide (WASM)</strong> and a fine-grained <strong>Solid.js-style</strong> reactive engine. </p> </div>

---

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.

---

Evolve is a paradigm shift for Python web development. Unlike traditional frameworks that render HTML on the server (Django, Flask) or wrap heavy JS runtimes, Evolve 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.

Installation

Requires Python 3.11+.

pip install evolve-web

---

Quick Start

Get a reactive app running in seconds.

1. Initialize a Project

evolve init my-app
cd my-app

This creates a simple app.py with example routes.

2. Run the Dev Server

evolve run

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

3. Build for Production

evolve build

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

---

The "Hello World" Component

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

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

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

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

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

Run it:

evolve run app.py

---

Key Features

1. Fine-Grained Reactivity (Signals)

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

from evolve.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 evolve.router.router import page, Link

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

3. Tailwind-Style Styling

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

from evolve.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 evolve.components.component import component
from evolve.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

Evolve 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 evolve init, the following structure is created:

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

---

Roadmap

• [x] v0.1: Core Reactive Engine & JS Kernel
• [x] v0.1: Component System & Routing
• [x] 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.