pulse-framework 0.1.54__tar.gz → 0.1.56__tar.gz

{pulse_framework-0.1.54 → pulse_framework-0.1.56}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pulse-framework
-Version: 0.1.54
+Version: 0.1.56
 Summary: Pulse - Full-stack framework for building real-time React applications in Python
 Requires-Dist: websockets>=12.0
 Requires-Dist: fastapi>=0.104.0
@@ -154,10 +154,10 @@ def counter():
 
 ### 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
+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
 

{pulse_framework-0.1.54 → pulse_framework-0.1.56}/README.md

@@ -136,10 +136,10 @@ def counter():
 
 ### 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
+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
 

{pulse_framework-0.1.54 → pulse_framework-0.1.56}/pyproject.toml

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

{pulse_framework-0.1.54 → pulse_framework-0.1.56}/src/pulse/__init__.py

@@ -1205,9 +1205,8 @@ from pulse.hooks.core import (
 	hooks as hooks,
 )
 
-# Hooks - Effects
-from pulse.hooks.effects import EffectsHookState as EffectsHookState
-from pulse.hooks.effects import effects as effects
+# Hooks - Effects (import to register inline_effect_hook before registry locks)
+from pulse.hooks.effects import InlineEffectHookState as InlineEffectHookState
 
 # Hooks - Init
 from pulse.hooks.init import (
@@ -1323,9 +1322,6 @@ from pulse.middleware import (
 from pulse.middleware import (
 	Redirect as Redirect,
 )
-from pulse.middleware import (
-	RoutePrerenderResponse as RoutePrerenderResponse,
-)
 from pulse.middleware import (
 	stack as stack,
 )
@@ -1344,6 +1340,9 @@ from pulse.queries.infinite_query import infinite_query as infinite_query
 from pulse.queries.mutation import mutation as mutation
 from pulse.queries.protocol import QueryResult as QueryResult
 from pulse.queries.query import query as query
+from pulse.react_component import (
+	ReactComponent as ReactComponent,
+)
 
 # React components (v2)
 from pulse.react_component import (

{pulse_framework-0.1.54 → pulse_framework-0.1.56}/src/pulse/app.py

@@ -47,7 +47,6 @@ from pulse.helpers import (
 	later,
 )
 from pulse.hooks.core import hooks
-from pulse.hooks.runtime import NotFoundInterrupt, RedirectInterrupt
 from pulse.messages import (
 	ClientChannelMessage,
 	ClientChannelRequestMessage,
@@ -56,7 +55,9 @@ from pulse.messages import (
 	ClientPulseMessage,
 	Prerender,
 	PrerenderPayload,
+	ServerInitMessage,
 	ServerMessage,
+	ServerNavigateToMessage,
 )
 from pulse.middleware import (
 	ConnectResponse,
@@ -67,13 +68,12 @@ from pulse.middleware import (
 	PrerenderResponse,
 	PulseMiddleware,
 	Redirect,
-	RoutePrerenderResponse,
 )
 from pulse.plugin import Plugin
 from pulse.proxy import ReactProxy
 from pulse.render_session import RenderSession
 from pulse.request import PulseRequest
-from pulse.routing import Layout, Route, RouteTree
+from pulse.routing import Layout, Route, RouteTree, ensure_absolute_path
 from pulse.serializer import Serialized, deserialize, serialize
 from pulse.user_session import (
 	CookieSessionStore,
@@ -88,6 +88,16 @@ T = TypeVar("T")
 
 
 class AppStatus(IntEnum):
+	"""Application lifecycle status.
+
+	Attributes:
+		created: App instance created but not yet initialized.
+		initialized: App.setup() has been called, routes configured.
+		running: App is actively serving requests.
+		draining: App is shutting down, draining connections.
+		stopped: App has been fully stopped.
+	"""
+
 	created = 0
 	initialized = 1
 	running = 2
@@ -96,6 +106,12 @@ class AppStatus(IntEnum):
 
 
 PulseMode = Literal["subdomains", "single-server"]
+"""Deployment mode for the application.
+
+Values:
+    "single-server": Python and React served from the same origin (default).
+    "subdomains": Python API on a subdomain (e.g., api.example.com).
+"""
 
 
 @dataclass
@@ -118,21 +134,55 @@ class ConnectionStatusConfig:
 
 
 class App:
-	"""
-	Pulse UI Application - the main entry point for defining your app.
+	"""Main Pulse application class.
 
+	Creates a server that handles routing, sessions, and WebSocket connections.
 	Similar to FastAPI, users create an App instance and define their routes.
 
-	Example:
-	    ```python
-	    import pulse as ps
+	Args:
+		routes: Route definitions for the application.
+		codegen: Code generation settings for React Router output.
+		middleware: Request middleware, either a single middleware or sequence.
+		plugins: Application plugins that can contribute routes, middleware,
+			and lifecycle hooks.
+		cookie: Session cookie configuration.
+		session_store: Session storage backend. Defaults to CookieSessionStore.
+		server_address: Public server URL. Required in production.
+		dev_server_address: Development server URL. Defaults to
+			"http://localhost:8000".
+		internal_server_address: Internal URL for server-side loader fetches.
+			Falls back to server_address if not provided.
+		not_found: Path for 404 page. Defaults to "/not-found".
+		mode: Deployment mode - "single-server" (default) or "subdomains".
+		api_prefix: API route prefix. Defaults to "/_pulse".
+		cors: CORS configuration. Auto-configured based on mode if not provided.
+		fastapi: Additional FastAPI constructor options.
+		session_timeout: Session cleanup timeout in seconds. Defaults to 60.0.
+		connection_status: Connection status UI timing configuration.
 
-	    app = ps.App()
+	Attributes:
+		env: Current environment ("dev", "ci", or "prod").
+		mode: Deployment mode ("single-server" or "subdomains").
+		status: Current application lifecycle status.
+		routes: Parsed route tree containing all registered routes.
+		fastapi: Underlying FastAPI instance.
+		asgi: ASGI application (includes Socket.IO).
 
-	    @app.route("/")
-	    def home():
-	        return ps.div("Hello World!")
-	    ```
+	Example:
+		```python
+		import pulse as ps
+
+		app = ps.App(
+		    routes=[
+		        ps.Route("/", render=home),
+		        ps.Route("/users/:id", render=user_detail),
+		    ],
+		    session_timeout=120.0,
+		)
+
+		if __name__ == "__main__":
+		    app.run(port=8000)
+		```
 	"""
 
 	env: PulseEnv
@@ -162,6 +212,9 @@ class App:
 	_render_cleanups: dict[str, asyncio.TimerHandle]
 	session_timeout: float
 	connection_status: ConnectionStatusConfig
+	render_loop_limit: int
+	detach_queue_timeout: float
+	disconnect_queue_timeout: float
 
 	def __init__(
 		self,
@@ -181,7 +234,10 @@ class App:
 		cors: CORSOptions | None = None,
 		fastapi: dict[str, Any] | None = None,
 		session_timeout: float = 60.0,
+		detach_queue_timeout: float = 15.0,
+		disconnect_queue_timeout: float = 300.0,
 		connection_status: ConnectionStatusConfig | None = None,
+		render_loop_limit: int = 50,
 	):
 		# Resolve mode from environment and expose on the app instance
 		self.env = envvars.pulse_env
@@ -228,7 +284,10 @@ class App:
 		# Map render_id -> cleanup timer handle for timeout-based expiry
 		self._render_cleanups = {}
 		self.session_timeout = session_timeout
+		self.detach_queue_timeout = detach_queue_timeout
+		self.disconnect_queue_timeout = disconnect_queue_timeout
 		self.connection_status = connection_status or ConnectionStatusConfig()
+		self.render_loop_limit = render_loop_limit
 
 		self.codegen = Codegen(
 			self.routes,
@@ -290,7 +349,21 @@ class App:
 
 	def run_codegen(
 		self, address: str | None = None, internal_address: str | None = None
-	):
+	) -> None:
+		"""Generate React Router code for all routes.
+
+		Generates TypeScript/JSX files for React Router integration based on
+		the application's route definitions.
+
+		Args:
+			address: Public server address. Updates server_address if provided.
+			internal_address: Internal server address for SSR fetches. Updates
+				internal_server_address if provided.
+
+		Raises:
+			RuntimeError: If no server address is available (neither passed
+				as argument nor set on the App instance).
+		"""
 		# Allow the CLI to disable codegen in specific scenarios (e.g., prod server-only)
 		if envvars.codegen_disabled:
 			return
@@ -309,11 +382,18 @@ class App:
 			connection_status=self.connection_status,
 		)
 
-	def asgi_factory(self):
-		"""
-		ASGI factory for uvicorn. This is called on every reload.
-		"""
+	def asgi_factory(self) -> ASGIApp:
+		"""ASGI factory for production deployment.
+
+		Called on each uvicorn reload. Initializes code generation and sets up
+		the application with the appropriate server address.
 
+		Returns:
+			The ASGI application instance (includes Socket.IO).
+
+		Raises:
+			RuntimeError: If in prod/ci mode without an explicit server_address.
+		"""
 		# In prod/ci, use the server_address provided to App(...).
 		if self.env in ("prod", "ci"):
 			if not self.server_address:
@@ -347,13 +427,34 @@ class App:
 		port: int = 8000,
 		find_port: bool = True,
 		reload: bool = True,
-	):
+	) -> None:
+		"""Start the development server with uvicorn.
+
+		Args:
+			address: Host address to bind to. Defaults to "localhost".
+			port: Port number to listen on. Defaults to 8000.
+			find_port: If True, automatically find an available port if the
+				specified port is in use. Defaults to True.
+			reload: If True, enable auto-reload on file changes. Defaults to True.
+		"""
 		if find_port:
 			port = find_available_port(port)
 
 		uvicorn.run(self.asgi_factory, reload=reload)
 
-	def setup(self, server_address: str):
+	def setup(self, server_address: str) -> None:
+		"""Initialize the app with a server address.
+
+		Configures FastAPI routes, middleware, CORS, and Socket.IO handlers.
+		Called automatically by asgi_factory().
+
+		Args:
+			server_address: The public URL where the server is accessible.
+
+		Note:
+			This method is idempotent - calling it multiple times on an already
+			initialized app will log a warning and return early.
+		"""
 		if self.status >= AppStatus.initialized:
 			logger.warning("Called App.setup() on an already initialized application")
 			return
@@ -436,6 +537,8 @@ class App:
 				raise HTTPException(
 					status_code=400, detail="'paths' must be a non-empty list"
 				)
+			paths = [ensure_absolute_path(path) for path in paths]
+			payload["paths"] = paths
 			route_info = payload.get("routeInfo")
 
 			client_addr: str | None = get_client_address(request)
@@ -453,8 +556,9 @@ class App:
 			# Schedule cleanup timeout (will cancel/reschedule on activity)
 			self._schedule_render_cleanup(render_id)
 
-			async def _prerender_one(path: str):
-				captured = render.prerender(path, route_info)
+			def _normalize_prerender_result(
+				captured: ServerInitMessage | ServerNavigateToMessage,
+			) -> Ok[ServerInitMessage] | Redirect | NotFound:
 				if captured["type"] == "vdom_init":
 					return Ok(captured)
 				if captured["type"] == "navigate_to":
@@ -467,12 +571,6 @@ class App:
 				# Fallback: shouldn't happen, return not found to be safe
 				return NotFound()
 
-			def _normalize_prerender_response(res: Any) -> RoutePrerenderResponse:
-				if isinstance(res, (Ok, Redirect, NotFound)):
-					return res
-				# Treat any other value as a VDOM payload
-				return Ok(res)
-
 			with PulseContext.update(render=render):
 				# Call top-level prerender middleware, which wraps the route processing
 				async def _process_routes() -> PrerenderResponse:
@@ -487,37 +585,21 @@ class App:
 						},
 					}
 
-					# Fan out on routes
+					captured = render.prerender(paths, route_info)
+
 					for p in paths:
-						try:
-							# Capture p in closure to avoid loop variable binding issue
-							async def _next(path: str = p) -> RoutePrerenderResponse:
-								return await _prerender_one(path)
-
-							# Call prerender_route middleware (in) -> prerender route -> (out)
-							res = await self.middleware.prerender_route(
-								path=p,
-								route_info=route_info,
-								request=PulseRequest.from_fastapi(request),
-								session=session.data,
-								next=_next,
-							)
-							res = _normalize_prerender_response(res)
-							if isinstance(res, Ok):
-								# Aggregate results
-								result_data["views"][p] = res.payload
-							elif isinstance(res, Redirect):
-								# Return redirect immediately
-								return Redirect(path=res.path or "/")
-							elif isinstance(res, NotFound):
-								# Return not found immediately
-								return NotFound()
-							else:
-								raise ValueError("Unexpected prerender response:", res)
-						except RedirectInterrupt as r:
-							return Redirect(path=r.path)
-						except NotFoundInterrupt:
+						res = _normalize_prerender_result(captured[p])
+						if isinstance(res, Ok):
+							# Aggregate results
+							result_data["views"][p] = res.payload
+						elif isinstance(res, Redirect):
+							# Return redirect immediately
+							return Redirect(path=res.path or "/")
+						elif isinstance(res, NotFound):
+							# Return not found immediately
 							return NotFound()
+						else:
+							raise ValueError("Unexpected prerender response:", res)
 
 					return Ok(result_data)
 
@@ -741,6 +823,8 @@ class App:
 	async def _handle_pulse_message(
 		self, render: RenderSession, session: UserSession, msg: ClientPulseMessage
 	) -> None:
+		print(f"[MSG] {msg}")
+
 		async def _next() -> Ok[None]:
 			if msg["type"] == "attach":
 				render.attach(msg["path"], msg["routeInfo"])
@@ -919,6 +1003,9 @@ class App:
 			self.routes,
 			server_address=self.server_address,
 			client_address=client_address,
+			detach_queue_timeout=self.detach_queue_timeout,
+			disconnect_queue_timeout=self.disconnect_queue_timeout,
+			render_loop_limit=self.render_loop_limit,
 		)
 		self.render_sessions[rid] = render
 		self._render_to_user[rid] = session.sid

{pulse_framework-0.1.54 → pulse_framework-0.1.56}/src/pulse/channel.py

@@ -24,14 +24,40 @@ logger = logging.getLogger(__name__)
 
 
 ChannelHandler = Callable[[Any], Any | Awaitable[Any]]
+"""Handler function for channel events. Can be sync or async.
+
+Type alias for ``Callable[[Any], Any | Awaitable[Any]]``.
+"""
 
 
 class ChannelClosed(RuntimeError):
-	"""Raised when interacting with a channel that has been closed."""
+	"""Raised when interacting with a channel that has been closed.
+
+	This exception is raised when attempting to call ``on()``, ``emit()``,
+	or ``request()`` on a channel that has already been closed.
+
+	Example:
+
+	```python
+	ch = ps.channel("my-channel")
+	ch.close()
+	ch.emit("event")  # Raises ChannelClosed
+	```
+	"""
 
 
 class ChannelTimeout(asyncio.TimeoutError):
-	"""Raised when a channel request times out waiting for a response."""
+	"""Raised when a channel request times out waiting for a response.
+
+	This exception is raised by ``Channel.request()`` when the specified
+	timeout elapses before receiving a response from the client.
+
+	Example:
+
+	```python
+	result = await ch.request("get_value", timeout=5.0)  # Raises if no response in 5s
+	```
+	"""
 
 
 @dataclass(slots=True)
@@ -311,7 +337,32 @@ class ChannelsManager:
 
 
 class Channel:
-	"""Bidirectional communication channel bound to a render session."""
+	"""Bidirectional communication channel bound to a render session.
+
+	Channels enable real-time messaging between server and client. Use
+	``ps.channel()`` to create a channel within a component.
+
+	Attributes:
+		id: Channel identifier (auto-generated UUID or user-provided).
+		render_id: Associated render session ID.
+		session_id: Associated user session ID.
+		route_path: Route path this channel is bound to, or None.
+		closed: Whether the channel has been closed.
+
+	Example:
+
+	```python
+	@ps.component
+	def ChatRoom():
+	    ch = ps.channel("chat")
+
+	    @ch.on("message")
+	    def handle_message(payload):
+	        ch.emit("broadcast", payload)
+
+	    return ps.div("Chat room")
+	```
+	"""
 
 	_manager: ChannelsManager
 	id: str
@@ -344,7 +395,24 @@ class Channel:
 	def on(self, event: str, handler: ChannelHandler) -> Callable[[], None]:
 		"""Register a handler for an incoming event.
 
-		Returns a callable that removes the handler when invoked.
+		Args:
+			event: Event name to listen for.
+			handler: Callback function ``(payload: Any) -> Any | Awaitable[Any]``.
+
+		Returns:
+			Callable that removes the handler when invoked.
+
+		Raises:
+			ChannelClosed: If the channel is closed.
+
+		Example:
+
+		```python
+		ch = ps.channel()
+		remove_handler = ch.on("data", lambda payload: print(payload))
+		# Later, to unregister:
+		remove_handler()
+		```
 		"""
 
 		self._ensure_open()
@@ -368,7 +436,21 @@ class Channel:
 	# Outgoing messages
 	# ---------------------------------------------------------------------
 	def emit(self, event: str, payload: Any = None) -> None:
-		"""Send a fire-and-forget event to the client."""
+		"""Send a fire-and-forget event to the client.
+
+		Args:
+			event: Event name.
+			payload: Data to send (optional).
+
+		Raises:
+			ChannelClosed: If the channel is closed.
+
+		Example:
+
+		```python
+		ch.emit("notification", {"message": "Hello"})
+		```
+		"""
 
 		self._ensure_open()
 		msg = ServerChannelRequestMessage(
@@ -389,7 +471,26 @@ class Channel:
 		*,
 		timeout: float | None = None,
 	) -> Any:
-		"""Send a request to the client and await the response."""
+		"""Send a request to the client and await the response.
+
+		Args:
+			event: Event name.
+			payload: Data to send (optional).
+			timeout: Timeout in seconds (optional).
+
+		Returns:
+			Response payload from client.
+
+		Raises:
+			ChannelClosed: If the channel is closed.
+			ChannelTimeout: If the request times out.
+
+		Example:
+
+		```python
+		result = await ch.request("get_value", timeout=5.0)
+		```
+		"""
 
 		self._ensure_open()
 		request_id = uuid.uuid4().hex
@@ -421,6 +522,11 @@ class Channel:
 
 	# ---------------------------------------------------------------------
 	def close(self) -> None:
+		"""Close the channel and clean up resources.
+
+		After closing, any further operations on the channel will raise
+		``ChannelClosed``. Pending requests will be cancelled.
+		"""
 		if self.closed:
 			return
 		self.closed = True
@@ -458,7 +564,33 @@ class Channel:
 
 
 def channel(identifier: str | None = None) -> Channel:
-	"""Convenience helper to create a channel using the active PulseContext."""
+	"""Create a channel bound to the current render session.
+
+	Args:
+		identifier: Optional channel ID. Auto-generated UUID if not provided.
+
+	Returns:
+		Channel instance.
+
+	Raises:
+		RuntimeError: If called outside an active render session.
+
+	Example:
+
+	```python
+	import pulse as ps
+
+	@ps.component
+	def ChatRoom():
+	    ch = ps.channel("chat")
+
+	    @ch.on("message")
+	    def handle_message(payload):
+	        ch.emit("broadcast", payload)
+
+	    return ps.div("Chat room")
+	```
+	"""
 
 	ctx = PulseContext.get()
 	if ctx.render is None:

{pulse_framework-0.1.54 → pulse_framework-0.1.56}/src/pulse/cli/cmd.py

@@ -210,6 +210,7 @@ def run(
 			mode=app_instance.env,
 			ready_pattern=r"localhost:\d+",
 			on_ready=mark_web_ready,
+			plain=plain,
 		)
 		commands.append(web_cmd)
 		# Set env var so app can read the React server address (only used in single-server mode)
@@ -228,6 +229,7 @@ def run(
 			verbose=verbose,
 			ready_pattern=r"Application startup complete",
 			on_ready=mark_server_ready,
+			plain=plain,
 		)
 		commands.append(server_cmd)
 
@@ -394,6 +396,7 @@ def build_uvicorn_command(
 	verbose: bool = False,
 	ready_pattern: str | None = None,
 	on_ready: Callable[[], None] | None = None,
+	plain: bool = False,
 ) -> CommandSpec:
 	app_import = f"{app_ctx.module_name}:{app_ctx.app_var}.asgi_factory"
 	args: list[str] = [
@@ -421,16 +424,22 @@ def build_uvicorn_command(
 
 	if extra_args:
 		args.extend(extra_args)
+	if plain:
+		args.append("--no-use-colors")
 
 	command_env = os.environ.copy()
 	command_env.update(
 		{
-			"FORCE_COLOR": "1",
 			"PYTHONUNBUFFERED": "1",
 			ENV_PULSE_HOST: address,
 			ENV_PULSE_PORT: str(port),
 		}
 	)
+	if plain:
+		command_env["NO_COLOR"] = "1"
+		command_env["FORCE_COLOR"] = "0"
+	else:
+		command_env["FORCE_COLOR"] = "1"
 	# Pass React server address to uvicorn process if set
 	if ENV_PULSE_REACT_SERVER_ADDRESS in os.environ:
 		command_env[ENV_PULSE_REACT_SERVER_ADDRESS] = os.environ[
@@ -471,6 +480,7 @@ def build_web_command(
 	mode: PulseEnv = "dev",
 	ready_pattern: str | None = None,
 	on_ready: Callable[[], None] | None = None,
+	plain: bool = False,
 ) -> CommandSpec:
 	command_env = os.environ.copy()
 	if mode == "prod":
@@ -493,10 +503,14 @@ def build_web_command(
 
 	command_env.update(
 		{
-			"FORCE_COLOR": "1",
 			"PYTHONUNBUFFERED": "1",
 		}
 	)
+	if plain:
+		command_env["NO_COLOR"] = "1"
+		command_env["FORCE_COLOR"] = "0"
+	else:
+		command_env["FORCE_COLOR"] = "1"
 
 	return CommandSpec(
 		name="web",