Pulse Python

Core Python framework for building full-stack reactive web apps with React frontends.

Architecture

Server-driven UI model: Python components render to VDOM, synced to React via WebSocket. State changes trigger re-renders; diffs are sent to client.

┌─────────────────────────────────────────────────────────────────┐
│  Python Server                                                  │
│  ┌──────────┐  ┌───────────────┐  ┌──────────────────────────┐  │
│  │   App    │──│ RenderSession │──│ VDOM Renderer            │  │
│  │ (FastAPI)│  │ (per browser) │  │ (diff & serialize)       │  │
│  └──────────┘  └───────────────┘  └──────────────────────────┘  │
│       │                │                      │                 │
│       │         ┌──────┴───────┐              │                 │
│       │         │    Hooks     │              │                 │
│       │         │ (state/setup)│              │                 │
│       │         └──────────────┘              │                 │
└───────┼───────────────────────────────────────┼─────────────────┘
        │ Socket.IO                             │ VDOM updates
        ▼                                       ▼
┌─────────────────────────────────────────────────────────────────┐
│  Browser (React)                                                │
└─────────────────────────────────────────────────────────────────┘

Folder Structure

src/pulse/
├── app.py              # Main App class, FastAPI + Socket.IO setup
├── channel.py          # Bidirectional real-time channels
├── routing.py          # Route/Layout definitions, URL matching
├── vdom.py             # VDOM node types (Element, Component, Node)
├── renderer.py         # VDOM rendering and diffing
├── render_session.py   # Per-browser session, manages mounted routes
├── reactive.py         # Signal/Computed/Effect primitives
├── reactive_extensions.py  # ReactiveList, ReactiveDict, ReactiveSet
├── state.py            # State management
├── serializer.py       # Python<->JSON serialization
├── middleware.py       # Request middleware (prerender, connect, message)
├── plugin.py           # Plugin interface for extensions
├── form.py             # Form handling
├── context.py          # PulseContext (request/session context)
├── cookies.py          # Cookie management
├── request.py          # PulseRequest abstraction
├── user_session.py     # User session storage
├── helpers.py          # Utilities (CSSProperties, later, repeat)
├── decorators.py       # @computed, @effect decorators
├── messages.py         # Client<->server message types
├── react_component.py  # ReactComponent wrapper for JS libraries
│
├── hooks/              # Server-side hooks (like React hooks)
│   ├── core.py         # Hook registry, HooksAPI
│   ├── runtime.py      # session(), route(), navigate(), redirect()
│   ├── states.py       # Reactive state hook
│   ├── effects.py      # Side effects hook
│   ├── setup.py        # Initialization hook
│   ├── init.py         # One-time setup hook
│   └── stable.py       # Memoization hook
│
├── queries/            # Data fetching (like TanStack Query)
│   ├── query.py        # @query decorator
│   ├── mutation.py     # @mutation decorator
│   ├── infinite_query.py  # Pagination support
│   ├── client.py       # QueryClient for cache management
│   └── store.py        # Query state store
│
├── components/         # Built-in components
│   ├── for_.py         # <For> loop component
│   ├── if_.py          # <If> conditional component
│   └── react_router.py # Link, Outlet for routing
│
├── html/               # HTML element bindings
│   ├── tags.py         # div, span, button, etc.
│   ├── props.py        # Typed props for HTML elements
│   ├── events.py       # Event types (MouseEvent, etc.)
│   └── elements.py     # Element type definitions
│
├── transpiler/         # Python->JS transpilation
│   ├── function.py     # JsFunction, @javascript decorator
│   └── imports.py      # Import/CssImport for client-side JS
│
├── codegen/            # Code generation for React Router
│   ├── codegen.py      # Generates routes.ts, loaders
│   └── templates/      # Mako templates for generated code
│
├── cli/                # Command-line interface
│   ├── cmd.py          # pulse run, pulse build
│   ├── lock.py         # Web-root lock state and helpers
│   └── processes.py    # Dev server process management
│
└── js/                 # JS API stubs for transpilation
    ├── window.py, document.py, navigator.py
    ├── array.py, object.py, string.py
    └── ...

Key Concepts

App

Entry point defining routes, middleware, plugins.

import pulse as ps

app = ps.App(routes=[
    ps.Route("/", home),
    ps.Layout("/dashboard", layout, children=[
        ps.Route("/", dashboard),
    ]),
])

Components

Functions returning VDOM. Use @ps.component for stateful components.

def greeting(name: str):
    return ps.div(f"Hello, {name}!")

@ps.component
def counter():
    count = ps.states.use(0)
    return ps.button(f"Count: {count()}", onClick=lambda _: count.set(count() + 1))

Reactivity

Signal[T] - reactive value
Computed[T] - derived value
Effect - side effect on change

Hooks

Server-side hooks via ps.state, ps.effect, ps.setup:

ps.state(StateClass) - reactive state (auto-keyed by callsite; use key= for manual control)
@ps.effect - side effects decorator
ps.setup(fn) - one-time initialization

Queries

Data fetching with caching:

@ps.query
async def fetch_user(id: str):
    return await db.get_user(id)

Channels

Bidirectional real-time messaging:

ch = ps.channel("chat")

@ch.on("message")
def handle_message(data):
    ch.broadcast("new_message", data)

Main Exports

App, FastAPIConfig, Route, Layout - app/routing
component - server-side component decorator
states, effects, setup, init - hooks
query, mutation, infinite_query - data fetching
channel - real-time channels
State, @computed, @effect - reactivity
ReactiveList, ReactiveDict, ReactiveSet - reactive containers
div, span, button, ... - HTML elements
For, If, Link, Outlet - built-in components
@react_component - wrap JS components
@javascript - transpile Python to JS

Release files for pulse-framework 0.1.109

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pulse-framework 0.1.109
File	Size	Uploaded
pulse_framework-0.1.109.tar.gz	282.3 kB	Jul 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pulse-framework 0.1.109
File	Interpreter	ABI	Platform	Reset
pulse_framework-0.1.109-py3-none-any.whl 346.2 kB Jul 28, 2026	Python 3	none	any	Details

Total release size: 628.4 kB

Release files / pulse_framework-0.1.109.tar.gz

Download URL	pulse_framework-0.1.109.tar.gz
Size	282.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`af8fce311fc48ae2cfe3b30a2fc6df666f5f5fe85a656b5e97ccf43068669322`
BLAKE2b-256 checksum How to use checksums	`1c5370d2ff540e07880a68ac87d7a6b71b7aa43677a8cf56de8167c79ae52c4d`
Upload date	Jul 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.0 {"installer":{"name":"uv","version":"0.12.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / pulse_framework-0.1.109-py3-none-any.whl

Download URL	pulse_framework-0.1.109-py3-none-any.whl
Size	346.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`db63cc66e43cdc3189d992cceef04587ed455b992d06504f3a6a954596ae52b7`
BLAKE2b-256 checksum How to use checksums	`5d79a4f8bbb272b339bb77606b7128f7bffb2f8b86e2e267f19e8bb259340726`
Upload date	Jul 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.0 {"installer":{"name":"uv","version":"0.12.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`