🧪 v0.7.0 — 全栈反应式 Web 框架🧪 v0.7.0 — Full-Stack Reactive Web Framework

融合 Clojure 声明式基因Clojure's Declarative Gene
与 Pythonic 全栈反应式Meets Pythonic Full-Stack Reactivity

纯 Python 编写全栈应用。零构建、零 API 胶水、天生离线就绪。用嵌套列表表达 UI,框架自动完成 WebSocket 双向同步与最小化 DOM 补丁推送。

Build full-stack apps in pure Python. Zero build, zero API glue, air-gapped ready. Express UI with nested lists — the framework handles WebSocket bidirectional sync and minimal DOM patch pushes automatically.

最新版本 v0.7.0 · MIT 开源 · Python ≥ 3.11

Latest v0.7.0 · MIT Open Source · Python ≥ 3.11

⚡️ 核心特性

⚡️ Key Features

Hiccl 继承了 Clojure 的优雅哲学,在 Python 生态中打造现代化全栈开发体验。

Hiccl inherits Clojure's elegant philosophy, crafting a modern full-stack development experience within the Python ecosystem.

🧩

Hiccup 声明式 UI

Hiccup Declarative UI

纯 Python 嵌套列表表达整个 DOM 结构,告别模板语言和 JSX。自动绑定事件到服务端方法。

Express entire DOM structures with pure Python nested lists. Say goodbye to template languages and JSX. Events auto-bind to server-side methods.

🔌

Signal 反应式状态

Signal Reactive State

signal / computed / effect 三大原语,搭配 batch() 批量事务。状态变更自动触发最小化虚拟 DOM Diff。

Three primitives — signal / computed / effect — plus batch() transactions. State changes auto-trigger minimal virtual-DOM diffs.

🛡️

Spec 运行时契约

Spec Runtime Contracts

Clojure-like 声明式数据契约守卫 @server 方法边界。结构化 explain_data 报错,赋能 AI Agent 自愈闭环。

Clojure-like declarative data contracts guarding @server method boundaries. Structured explain_data errors empower AI agent self-healing loops.

🔀

MQTT 通配符 EventBus

MQTT Wildcard EventBus

原生层级通配符订阅(* 单层 / # 多层),高性能正则缓存路由,轻松构建多人实时协作应用。

Native hierarchical wildcard subscriptions (* single / # multi level) with high-performance regex cache routing for real-time collaboration.

🧩

Reagent 纯函数组件

Reagent Functional Components

use_signal() / subscribe() / dispatch() 单向数据流。展示层纯函数 + 状态层 OOP,UI 与副作用深度解耦。

use_signal() / subscribe() / dispatch() unidirectional data flow. Pure-function presentation layer + OOP state layer, deeply decoupled.

📡

CSP 并发管道

CSP Concurrency Channels

Pythonic Channel(背压/缓冲/安全关闭)、alts_ 公平多路选择、@go 后台协程调度器。

Pythonic Channel (backpressure/buffered/safe-close), alts_ fair multiplexing, @go background coroutine scheduler.

🔀

Transducers 渲染中间件

Transducers Middleware

DFS 不可变树变换管线。内置 LoadingTransducer(自动加载态)与 SanitizingTransducer(敏感数据脱敏)。

DFS immutable tree transformation pipeline. Built-in LoadingTransducer (auto-spinner) and SanitizingTransducer (data masking).

时间旅行调试器

Time-Travel Debugger

Signal.with_history() 状态快照,可视化撤销/重做面板,多会话安全隔离。

Signal.with_history() state snapshots. Visual undo/redo panel with multi-session isolation, out of the box.

🧬

Datalog 声明式查询

Datalog Declarative Query

Datomic 风格 EAVT/AVE/VAE 索引,Logic Unification 求解器,GraphQL-like Pull API,as_of 历史回溯。

Datomic-style EAVT/AVE/VAE indices, Logic Unification solver, GraphQL-like Pull API, as_of historical snapshot querying.

🎨

内置 DaisyUI + TailwindCSS

Built-in DaisyUI + TailwindCSS

开箱即用暗色毛玻璃组件库与原子化样式。零构建步骤,纯 Play CDN 运行时。

Dark-mode glassmorphic component library + utility-first styling out of the box. Zero build steps, pure Play CDN runtime.

🌿

Alpine.js 客户端加速

Alpine.js Client Acceleration

高频本地交互(60fps 计时器、滑块、手风琴)无需网络往返,标准 HTML 属性声明式激活。

High-frequency local interactions (60fps timers, sliders, accordions) without network round-trips. Declarative HTML attribute activation.

📦

100% 离线与内网就绪

100% Offline & Air-Gapped

所有静态依赖完全本地托管。物理隔离网络内高速运行,零外部 CDN 依赖。

All static dependencies hosted locally. Run at full speed in physically isolated networks with zero external CDN dependencies.

🛠 技术栈

🛠 Tech Stack

Hiccl 的全栈架构由五个精心编排的层次构成,每一层都聚焦于特定的职责。

Hiccl's full-stack architecture is composed of five carefully orchestrated layers, each focused on a specific responsibility.

🎯 Hiccl 内核

🎯 Hiccl Core

Signal 反应式引擎 · Hiccup DSL 渲染器 · 虚拟 DOM Diff · 会话管理 · 组件生命周期

Signal Reactive Engine · Hiccup DSL Renderer · Virtual DOM Diff · Session Management · Component Lifecycle

⚡ FastAPI / Starlette

⚡ FastAPI / Starlette

高性能异步 HTTP 服务 · WebSocket/SSE 双通道传输 · CORS 中间件 · 静态文件服务

High-Performance Async HTTP · WebSocket/SSE Dual Transport · CORS Middleware · Static File Serving

🌐 通信胶水层

🌐 Communication Glue

HTMX — 声明式请求拦截与降级 · hiccl.js — WebSocket 长连接管理 · DOM 补丁精准替换

HTMX — Declarative Request Interception & Fallback · hiccl.js — WebSocket Keep-Alive · DOM Patch Precision Replacement

🎨 样式 & 组件库

🎨 Styling & Components

TailwindCSS Play CDN 运行时 · DaisyUI 毛玻璃暗色组件 · 完全本地托管,零构建步骤

TailwindCSS Play CDN Runtime · DaisyUI Glassmorphic Dark Components · Fully Local Hosting, Zero Build Steps

🌿 客户端响应式

🌿 Client-Side Reactivity

Alpine.js — 轻量级客户端 MVVM · 高频本地交互无网络延迟 · 与 Hiccl 服务端状态无缝桥接

Alpine.js — Lightweight Client MVVM · High-Frequency Local Interactions · Seamless Bridge with Hiccl Server State

🚀 快速上手

🚀 Quick Start

30 行代码,从零到运行一个全栈响应式计数器。

30 lines of code, from zero to a running full-stack reactive counter.

1

安装 Hiccl

Install Hiccl

使用 pip 或 uv 安装框架本体。

Install the framework via pip or uv.

2

编写组件

Write Component

用 Hiccup DSL 声明 UI,用 @server 声明事件。

Declare UI with Hiccup DSL, declare events with @server.

3

启动服务

Launch Server

一行命令启动,浏览器即刻看到响应式界面。

One command to start the dev server. See your reactive UI instantly.

counter_app.py
from hiccl import (
    Component, ComponentRegistry,
    HicclConfig, create_hiccl_app,
    menu, server, signal,
)
from hiccl.hiccup import button, div, h2

registry = ComponentRegistry()

class Counter(Component):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.count = signal(0)

    @server
    def increment(self, step: int = 1):
        if isinstance(step, str):
            step = int(step)
        self.count.set(self.count.get() + step)

    @server
    def decrement(self, step: int = 1):
        if isinstance(step, str):
            step = int(step)
        self.count.set(self.count.get() - step)

    def render(self):
        count = self.count.get()
        return div(
            {"class": "card w-96 bg-base-200 shadow-xl mx-auto mt-10"},
            div({"class": "card-body items-center text-center"},
                h2({"class": "card-title text-3xl font-extrabold"},
                   f"Count: {count}"),
                div({"class": "card-actions justify-center gap-2"},
                    button({"class": "btn btn-error",
                            "on_click": self.decrement(1)}, "-1"),
                    button({"class": "btn btn-success",
                            "on_click": self.increment(1)}, "+1"),
                ),
            ),
        )

app = create_hiccl_app(HicclConfig(
    component_registry=registry,
    pages=menu(Counter),
    brand_name="Hiccl Quickstart"
))

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

📦 安装 Hiccl

📦 Install Hiccl

一行命令即可将 Hiccl 添加到你的 Python 项目中。

Add Hiccl to your Python project with a single command.

📦使用 pipUsing pip
$ pip install hiccl
使用 uv(推荐)Using uv (recommended)推荐
$ uv add hiccl

GitHub 开源仓库

GitHub Repository

欢迎 ⭐ Star、🐛 Issue、🤝 PR!完整源码、210+ 单元测试、路线图尽在 GitHub。

Welcome ⭐ Star, 🐛 Issue, 🤝 PR! Full source code, 210+ unit tests, and roadmap all on GitHub.

Star