How codelv/enaml-web works
Project Type and Purpose
• Type: An open-source Python web component toolkit / framework for building websites declaratively with Enaml.
• Purpose: Provides a component API (Html, Markdown, Code, etc.), a core application engine to render and manage a server-side DOM, and an LXML-based implementation with optional C speedups. Enables both static site generation and interactive, stateful pages via WebSockets or polling.
High-Level Architecture & Main Components
A. Developer Layer
• .enaml view definitions (e.g., index.enaml, examples/**/*.enaml)
• Python glue code (examples/*.py, user handlers)
B. Framework Layer (enaml-web core)
1. Component API (web/components/)
– High-level Enaml component classes: Html, Raw, Markdown, Code, AutoForm, Block, Looper, etc.
2. Core Engine (web/core/)
– WebApplication (app startup, request routing, DOM lifecycle)
– Block, View abstractions (template inheritance and composition)
– Event handling and data binding API
C. Implementation Layer (DOM & Rendering)
1. LXML Back-end (web/impl/)
– Parsers & renderers for each component using lxml etree
2. C Speedups (src/speedups.c)
– Performance-critical routines for diffing or attribute updates
D. Integration & Delivery
1. Web Framework Adapter (e.g., Tornado, Flask)
– Uses WebApplication to handle HTTP GET/POST and WebSocket endpoints
2. Client-Side Script (examples/*/app.js)
– Listens on WebSocket for diff messages, applies patches to browser DOM
– Captures user events and sends “modified” messages back to server
E. Supporting Infrastructure
• Examples (examples/) and Tests (tests/)
• CI/CD (GitHub Actions ci.yml)
• Documentation (docs/, README.md)
Relationships & Data Flows
• Startup: User’s Python application creates a WebApplication → loads Enaml views → registers routes/events.
• Static Render: view.render() → Core Engine invokes Component API → LXML Implementation builds DOM → HTML output written to disk.
• Interactive Flow:
1. Initial Request: Browser GET → WebFramework Adapter → WebApplication → view.render() → HTML+JS → Browser.
2. Client Events: User clicks/types → Client-Side Script captures → sends JSON “modified” event via WebSocket.
3. Server Update: Adapter receives event → WebApplication applies change to server-side LXML tree → triggers handlers.
4. Diff Generation: Core Engine diffs old vs. new DOM → produces patch messages.
5. Client Patch: Patch sent back via WebSocket → Client-Side Script applies to live DOM.
Architectural Patterns & Principles
• Component-Based: Each UI element is an Enaml component class.
• Server-Side DOM: Maintains authoritative view state, enables two-way data binding.
• Template Inheritance: Block nodes allow extension and override of base templates.
• Layered Design: API → Core Engine → Implementation → Integration.
• Extension Points:
• New components under web/components/
• Provide custom LXML renderers under web/impl/
• Swap out WebFramework adapter