pulse-framework 0.1.53__tar.gz → 0.1.55__tar.gz

pulse_framework-0.1.55/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.3
+Name: pulse-framework
+Version: 0.1.55
+Summary: Pulse - Full-stack framework for building real-time React applications in Python
+Requires-Dist: websockets>=12.0
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: mako>=1.3.10
+Requires-Dist: typer>=0.16.0
+Requires-Dist: python-socketio>=5.13.0
+Requires-Dist: rich>=13.7.1
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: watchfiles>=1.1.0
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# 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
+│   └── 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.
+
+```python
+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.
+
+```python
+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.states`, `ps.effects`, `ps.setup`:
+- `states.use(initial)` - reactive state
+- `effects.use(fn, deps)` - side effects
+- `setup.use(fn)` - one-time initialization
+
+### Queries
+
+Data fetching with caching:
+
+```python
+@ps.query
+async def fetch_user(id: str):
+    return await db.get_user(id)
+```
+
+### Channels
+
+Bidirectional real-time messaging:
+
+```python
+ch = ps.channel("chat")
+
+@ch.on("message")
+def handle_message(data):
+    ch.broadcast("new_message", data)
+```
+
+## Main Exports
+
+- `App`, `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

pulse_framework-0.1.55/README.md

@@ -0,0 +1,178 @@
+# 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
+│   └── 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.
+
+```python
+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.
+
+```python
+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.states`, `ps.effects`, `ps.setup`:
+- `states.use(initial)` - reactive state
+- `effects.use(fn, deps)` - side effects
+- `setup.use(fn)` - one-time initialization
+
+### Queries
+
+Data fetching with caching:
+
+```python
+@ps.query
+async def fetch_user(id: str):
+    return await db.get_user(id)
+```
+
+### Channels
+
+Bidirectional real-time messaging:
+
+```python
+ch = ps.channel("chat")
+
+@ch.on("message")
+def handle_message(data):
+    ch.broadcast("new_message", data)
+```
+
+## Main Exports
+
+- `App`, `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

{pulse_framework-0.1.53 → pulse_framework-0.1.55}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pulse-framework"
-version = "0.1.53"
+version = "0.1.55"
 description = "Pulse - Full-stack framework for building real-time React applications in Python"
 readme = "README.md"
 requires-python = ">=3.11"

{pulse_framework-0.1.53 → pulse_framework-0.1.55}/src/pulse/__init__.py

@@ -1286,9 +1286,9 @@ from pulse.hooks.stable import (
 	stable as stable,
 )
 
-# Hooks - States
-from pulse.hooks.states import StatesHookState as StatesHookState
-from pulse.hooks.states import states as states
+# Hooks - State
+from pulse.hooks.state import StateHookState as StateHookState
+from pulse.hooks.state import state as state
 from pulse.messages import ClientMessage as ClientMessage
 from pulse.messages import Directives as Directives
 from pulse.messages import Prerender as Prerender

{pulse_framework-0.1.53 → pulse_framework-0.1.55}/src/pulse/app.py

@@ -21,6 +21,7 @@ from fastapi import FastAPI, HTTPException, Request, Response
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 from starlette.types import ASGIApp
+from starlette.websockets import WebSocket
 
 from pulse.codegen.codegen import Codegen, CodegenConfig
 from pulse.context import PULSE_CONTEXT, PulseContext
@@ -28,6 +29,7 @@ from pulse.cookies import (
 	Cookie,
 	CORSOptions,
 	compute_cookie_domain,
+	compute_cookie_secure,
 	cors_options,
 	session_cookie,
 )
@@ -364,6 +366,8 @@ class App:
 		# Compute cookie domain from deployment/server address if not explicitly provided
 		if self.cookie.domain is None:
 			self.cookie.domain = compute_cookie_domain(self.mode, self.server_address)
+		if self.cookie.secure is None:
+			self.cookie.secure = compute_cookie_secure(self.env, self.server_address)
 
 		# Add CORS middleware (configurable/overridable)
 		if self.cors is not None:
@@ -450,7 +454,7 @@ class App:
 			self._schedule_render_cleanup(render_id)
 
 			async def _prerender_one(path: str):
-				captured = render.prerender_mount_capture(path, route_info)
+				captured = render.prerender(path, route_info)
 				if captured["type"] == "vdom_init":
 					return Ok(captured)
 				if captured["type"] == "navigate_to":
@@ -578,20 +582,20 @@ class App:
 				server_address=server_address,
 			)
 
+			# In dev mode, proxy WebSocket connections to React Router (e.g. Vite HMR)
+			# Socket.IO handles /socket.io/ at ASGI level before reaching FastAPI
+			if self.env == "dev":
+
+				@self.fastapi.websocket("/{path:path}")
+				async def websocket_proxy(websocket: WebSocket, path: str):  # pyright: ignore[reportUnusedFunction]
+					await proxy_handler.proxy_websocket(websocket)
+
 			@self.fastapi.api_route(
 				"/{path:path}",
 				methods=["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
 				include_in_schema=False,
 			)
 			async def proxy_catch_all(request: Request, path: str):  # pyright: ignore[reportUnusedFunction]
-				# Skip WebSocket upgrades outside the Vite dev server (handled by Socket.IO)
-				is_websocket_upgrade = (
-					request.headers.get("upgrade", "").lower() == "websocket"
-				)
-				is_vite_dev_server = self.env == "dev" and request.url.path == "/"
-				if is_websocket_upgrade and not is_vite_dev_server:
-					raise HTTPException(status_code=404, detail="Not found")
-
 				# Proxy all unmatched HTTP requests to React Router
 				return await proxy_handler(request)
 
@@ -605,12 +609,14 @@ class App:
 			# Parse cookies from environ and ensure a session exists
 			cookie = self.cookie.get_from_socketio(environ)
 			if cookie is None:
-				raise ConnectionRefusedError()
+				raise ConnectionRefusedError("Socket connect missing cookie")
 			session = await self.get_or_create_session(cookie)
 
 			if not rid:
 				# Still refuse connections without a renderId
-				raise ConnectionRefusedError()
+				raise ConnectionRefusedError(
+					f"Socket connect missing render_id session={session.sid}"
+				)
 
 			# Allow reconnects where the provided renderId no longer exists by creating a new RenderSession
 			render = self.render_sessions.get(rid)
@@ -621,7 +627,10 @@ class App:
 			else:
 				owner = self._render_to_user.get(render.id)
 				if owner != session.sid:
-					raise ConnectionRefusedError()
+					raise ConnectionRefusedError(
+						f"Socket connect session mismatch render={render.id} "
+						+ f"owner={owner} session={session.sid}"
+					)
 
 			def on_message(message: ServerMessage):
 				payload = serialize(message)
@@ -733,14 +742,14 @@ class App:
 		self, render: RenderSession, session: UserSession, msg: ClientPulseMessage
 	) -> None:
 		async def _next() -> Ok[None]:
-			if msg["type"] == "mount":
-				render.mount(msg["path"], msg["routeInfo"])
-			elif msg["type"] == "navigate":
-				render.navigate(msg["path"], msg["routeInfo"])
+			if msg["type"] == "attach":
+				render.attach(msg["path"], msg["routeInfo"])
+			elif msg["type"] == "update":
+				render.update_route(msg["path"], msg["routeInfo"])
 			elif msg["type"] == "callback":
 				render.execute_callback(msg["path"], msg["callback"], msg["args"])
-			elif msg["type"] == "unmount":
-				render.unmount(msg["path"])
+			elif msg["type"] == "detach":
+				render.detach(msg["path"])
 				render.channels.remove_route(msg["path"])
 			elif msg["type"] == "api_result":
 				render.handle_api_result(dict(msg))
@@ -845,6 +854,11 @@ class App:
 
 		# Server-backed store path
 		assert isinstance(self.session_store, SessionStore)
+		cookie_secure = self.cookie.secure
+		if cookie_secure is None:
+			raise RuntimeError(
+				"Cookie.secure is not resolved. Ensure App.setup() ran before sessions."
+			)
 		if raw_cookie is not None:
 			sid = raw_cookie
 			data = await self.session_store.get(sid) or await self.session_store.create(
@@ -855,7 +869,7 @@ class App:
 				name=self.cookie.name,
 				value=sid,
 				domain=self.cookie.domain,
-				secure=self.cookie.secure,
+				secure=cookie_secure,
 				samesite=self.cookie.samesite,
 				max_age_seconds=self.cookie.max_age_seconds,
 			)
@@ -871,7 +885,7 @@ class App:
 				name=self.cookie.name,
 				value=sid,
 				domain=self.cookie.domain,
-				secure=self.cookie.secure,
+				secure=cookie_secure,
 				samesite=self.cookie.samesite,
 				max_age_seconds=self.cookie.max_age_seconds,
 			)

pulse_framework-0.1.55/src/pulse/code_analysis.py

@@ -0,0 +1,38 @@
+"""Code analysis utilities for inspecting Python source."""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import textwrap
+from collections.abc import Callable
+from typing import Any
+
+
+def is_stub_function(fn: Callable[..., Any]) -> bool:
+	"""Check if function body is just ... or pass (no real implementation)."""
+	try:
+		source = inspect.getsource(fn)
+		tree = ast.parse(textwrap.dedent(source))
+		func_def = tree.body[0]
+		if not isinstance(func_def, ast.FunctionDef):
+			return False
+		body = func_def.body
+		# Skip docstring
+		if body and isinstance(body[0], ast.Expr):
+			if isinstance(body[0].value, ast.Constant) and isinstance(
+				body[0].value.value, str
+			):
+				body = body[1:]
+		if not body:
+			return True
+		if len(body) == 1:
+			stmt = body[0]
+			if isinstance(stmt, ast.Pass):
+				return True
+			if isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Constant):
+				if stmt.value.value is ...:
+					return True
+		return False
+	except (OSError, TypeError, SyntaxError):
+		return False