pulse-framework 0.1.54__py3-none-any.whl → 0.1.56__py3-none-any.whl

pulse/request.py

@@ -17,15 +17,32 @@ def _bytes_kv_to_str(headers: list[tuple[bytes, bytes]]) -> dict[str, str]:
 
 
 class PulseRequest:
-	"""Normalized request for both HTTP prerender and Socket.IO connect.
-
-	Provides a minimal, consistent surface:
-	  - headers: dict[str, str] (lowercased)
-	  - cookies: dict[str, str]
-	  - scheme, method, path, query_string, url
-	  - client: tuple[str, int] | None
-	  - auth: Any | None (only set for Socket.IO connect when provided)
-	  - raw: underlying request/scope/environ for advanced users
+	"""Normalized request object for both HTTP prerender and WebSocket connect.
+
+	Provides a consistent interface for accessing request data regardless of
+	the underlying transport (FastAPI/Starlette HTTP or Socket.IO WebSocket).
+
+	Attributes:
+		headers: Request headers with lowercased keys.
+		cookies: Request cookies as name-value pairs.
+		scheme: URL scheme (http/https).
+		method: HTTP method (GET, POST, etc.).
+		path: URL path.
+		query_string: Query string (without leading ?).
+		client: Client address as (host, port) tuple, or None.
+		auth: Auth data (Socket.IO only).
+		raw: Underlying request object for advanced use.
+
+	Args:
+		headers: Request headers (keys will be lowercased).
+		cookies: Request cookies.
+		scheme: URL scheme (http/https).
+		method: HTTP method.
+		path: URL path.
+		query_string: Query string (without ?).
+		client: Client address as (host, port) tuple.
+		auth: Auth data (for Socket.IO).
+		raw: Underlying request object.
 	"""
 
 	headers: dict[str, str]
@@ -63,6 +80,7 @@ class PulseRequest:
 
 	@property
 	def url(self) -> str:
+		"""Full URL including scheme, host, path, and query string."""
 		qs = f"?{self.query_string}" if self.query_string else ""
 		host = self.headers.get("host", "")
 		if host:
@@ -70,7 +88,15 @@ class PulseRequest:
 		return f"{self.path}{qs}"
 
 	@staticmethod
-	def from_fastapi(request: Any) -> PulseRequest:
+	def from_fastapi(request: Any) -> "PulseRequest":
+		"""Create from a FastAPI/Starlette request.
+
+		Args:
+			request: FastAPI/Starlette Request object.
+
+		Returns:
+			PulseRequest instance with normalized request data.
+		"""
 		# FastAPI/Starlette Request
 		headers = {k.lower(): v for k, v in request.headers.items()}
 		cookies = dict(request.cookies or {})
@@ -93,7 +119,16 @@ class PulseRequest:
 	@staticmethod
 	def from_socketio_environ(
 		environ: MutableMapping[str, Any], auth: Any | None
-	) -> PulseRequest:
+	) -> "PulseRequest":
+		"""Create from a Socket.IO environ dictionary.
+
+		Args:
+			environ: Socket.IO environ dictionary (WSGI or ASGI-like).
+			auth: Auth data passed during Socket.IO connect.
+
+		Returns:
+			PulseRequest instance with normalized request data.
+		"""
 		# python-socketio passes a WSGI/ASGI-like environ. Try to detect ASGI scope first.
 		scope: MutableMapping[str, Any] = environ.get("asgi.scope") or environ
 

pulse/routing.py

@@ -149,8 +149,45 @@ def route_or_ancestors_have_dynamic(node: "Route | Layout") -> bool:
 
 
 class Route:
-	"""
-	Represents a route definition with its component dependencies.
+	"""Defines a route in the application.
+
+	Routes map URL paths to components that render the page content.
+
+	Args:
+		path: URL path pattern (e.g., "/users/:id"). Supports static segments,
+			dynamic parameters (`:id`), optional parameters (`:id?`), and
+			catch-all segments (`*`).
+		render: Component function to render for this route. Must be a
+			zero-argument component.
+		children: Nested child routes. Child paths are relative to parent.
+		dev: If True, route is only included in dev mode. Defaults to False.
+
+	Attributes:
+		path: Normalized relative path (no leading/trailing slashes).
+		segments: Parsed path segments.
+		render: Component to render.
+		children: Nested routes.
+		is_index: True if this is an index route (empty path).
+		is_dynamic: True if path contains dynamic or optional segments.
+		dev: Whether route is dev-only.
+
+	Path Syntax:
+		- Static: `/users` - Exact match
+		- Dynamic: `:id` - Named parameter (available in pathParams)
+		- Optional: `:id?` - Optional parameter
+		- Catch-all: `*` - Match remaining path (must be last segment)
+
+	Example:
+		```python
+		ps.Route(
+		    "/users",
+		    render=users_page,
+		    children=[
+		        ps.Route(":id", render=user_detail),
+		        ps.Route(":id/edit", render=user_edit),
+		    ],
+		)
+		```
 	"""
 
 	path: str
@@ -243,6 +280,43 @@ def replace_layout_indicator(path_list: list[str], value: str):
 
 
 class Layout:
+	"""Wraps child routes with a shared layout component.
+
+	Layouts provide persistent UI elements (headers, sidebars, etc.) that
+	wrap child routes. The layout component must render an `Outlet` to
+	display the matched child route.
+
+	Args:
+		render: Layout component function. Must render `ps.Outlet()` to
+			display child content.
+		children: Nested routes that will be wrapped by this layout.
+		dev: If True, layout is only included in dev mode. Defaults to False.
+
+	Attributes:
+		render: Layout component to render.
+		children: Nested routes.
+		dev: Whether layout is dev-only.
+
+	Example:
+		```python
+		@ps.component
+		def AppLayout():
+		    return ps.div(
+		        Header(),
+		        ps.main(ps.Outlet()),
+		        Footer(),
+		    )
+
+		ps.Layout(
+		    render=AppLayout,
+		    children=[
+		        ps.Route("/", render=home),
+		        ps.Route("/about", render=about),
+		    ],
+		)
+		```
+	"""
+
 	render: Component[...]
 	children: Sequence["Route | Layout"]
 	dev: bool
@@ -359,7 +433,17 @@ def filter_dev_routes(routes: Sequence[Route | Layout]) -> list[Route | Layout]:
 	return filtered
 
 
-class InvalidRouteError(Exception): ...
+class InvalidRouteError(Exception):
+	"""Raised for invalid route configurations.
+
+	Examples of invalid configurations:
+		- Empty path segments
+		- Invalid characters in path
+		- Catch-all (*) not at end of path
+		- Attempting to get default RouteInfo for dynamic routes
+	"""
+
+	...
 
 
 class RouteTree:
@@ -406,6 +490,20 @@ class RouteTree:
 
 
 class RouteInfo(TypedDict):
+	"""TypedDict containing current route information.
+
+	Provides access to URL components and parsed parameters for the
+	current route. Available via `use_route()` hook in components.
+
+	Attributes:
+		pathname: Current URL path (e.g., "/users/123").
+		hash: URL hash fragment after # (e.g., "section1").
+		query: Raw query string after ? (e.g., "page=2&sort=name").
+		queryParams: Parsed query parameters as dict (e.g., {"page": "2"}).
+		pathParams: Dynamic path parameters (e.g., {"id": "123"} for ":id").
+		catchall: Catch-all segments as list (e.g., ["a", "b"] for "a/b").
+	"""
+
 	pathname: str
 	hash: str
 	query: str
@@ -415,6 +513,33 @@ class RouteInfo(TypedDict):
 
 
 class RouteContext:
+	"""Runtime context for the current route.
+
+	Provides reactive access to the current route's URL components and
+	parameters. Accessible via `ps.route()` in components.
+
+	Attributes:
+		info: Current route info (reactive, auto-updates on navigation).
+		pulse_route: Route or Layout definition for this context.
+
+	Properties:
+		pathname: Current URL path (e.g., "/users/123").
+		hash: URL hash fragment (without #).
+		query: Raw query string (without ?).
+		queryParams: Parsed query parameters as dict.
+		pathParams: Dynamic path parameters (e.g., {"id": "123"}).
+		catchall: Catch-all segments as list.
+
+	Example:
+		```python
+		@ps.component
+		def UserProfile():
+			ctx = ps.route()
+			user_id = ctx.pathParams.get("id")
+			return ps.div(f"User: {user_id}")
+		```
+	"""
+
 	info: RouteInfo
 	pulse_route: Route | Layout
 
@@ -422,31 +547,42 @@ class RouteContext:
 		self.info = cast(RouteInfo, cast(object, ReactiveDict(info)))
 		self.pulse_route = pulse_route
 
-	def update(self, info: RouteInfo):
+	def update(self, info: RouteInfo) -> None:
+		"""Update the route info with new values.
+
+		Args:
+			info: New route info to apply.
+		"""
 		self.info.update(info)
 
 	@property
 	def pathname(self) -> str:
+		"""Current URL path (e.g., "/users/123")."""
 		return self.info["pathname"]
 
 	@property
 	def hash(self) -> str:
+		"""URL hash fragment (without #)."""
 		return self.info["hash"]
 
 	@property
 	def query(self) -> str:
+		"""Raw query string (without ?)."""
 		return self.info["query"]
 
 	@property
 	def queryParams(self) -> dict[str, str]:
+		"""Parsed query parameters as dict."""
 		return self.info["queryParams"]
 
 	@property
 	def pathParams(self) -> dict[str, str]:
+		"""Dynamic path parameters (e.g., {"id": "123"} for ":id")."""
 		return self.info["pathParams"]
 
 	@property
 	def catchall(self) -> list[str]:
+		"""Catch-all segments as list."""
 		return self.info["catchall"]
 
 	@override

pulse/serializer.py

@@ -46,6 +46,48 @@ __all__ = [
 
 
 def serialize(data: Any) -> Serialized:
+	"""Serialize a Python value to wire format.
+
+	Converts Python values to a JSON-compatible format with metadata for
+	preserving types like datetime, set, and shared references.
+
+	Args:
+		data: Value to serialize.
+
+	Returns:
+		Serialized tuple containing metadata and JSON payload.
+
+	Raises:
+		TypeError: For unsupported types (functions, modules, classes).
+		ValueError: For Infinity float values.
+
+	Supported types:
+		- Primitives: None, bool, int, float, str
+		- Collections: list, tuple, dict, set
+		- datetime.datetime (converted to milliseconds since Unix epoch)
+		- Dataclasses (serialized as dict of fields)
+		- Objects with __dict__ (public attributes only)
+
+	Notes:
+		- NaN floats serialize as None
+		- Infinity raises ValueError
+		- Dict keys must be strings
+		- Private attributes (starting with _) are excluded
+		- Shared references and cycles are preserved
+
+	Example:
+		```python
+		from datetime import datetime
+		import pulse as ps
+
+		data = {
+			"name": "Alice",
+			"created": datetime.now(),
+			"tags": {"admin", "user"},
+		}
+		serialized = ps.serialize(data)
+		```
+	"""
 	# Map object id -> assigned global index
 	seen: dict[int, int] = {}
 	refs: list[int] = []
@@ -133,6 +175,35 @@ def serialize(data: Any) -> Serialized:
 def deserialize(
 	payload: Serialized,
 ) -> Any:
+	"""Deserialize wire format back to Python values.
+
+	Reconstructs Python values from the serialized format, restoring
+	datetime objects, sets, and shared references.
+
+	Args:
+		payload: Serialized tuple from serialize().
+
+	Returns:
+		Reconstructed Python value.
+
+	Raises:
+		TypeError: For malformed payloads.
+
+	Notes:
+		- datetime values are reconstructed as UTC-aware
+		- set values are reconstructed as Python sets
+		- Shared references and cycles are restored
+
+	Example:
+		```python
+		from datetime import datetime
+		import pulse as ps
+
+		original = {"items": [1, 2, 3], "timestamp": datetime.now()}
+		serialized = ps.serialize(original)
+		restored = ps.deserialize(serialized)
+		```
+	"""
 	(refs, dates, sets, _maps), data = payload
 	refs = set(refs)
 	dates = set(dates)

pulse/state.py

@@ -25,6 +25,30 @@ T = TypeVar("T")
 
 
 class StateProperty(ReactiveProperty[Any]):
+	"""
+	Descriptor for reactive properties on State classes.
+
+	StateProperty wraps a Signal and provides automatic reactivity for
+	class attributes. When a property is read, it subscribes to the underlying
+	Signal. When written, it updates the Signal and triggers re-renders.
+
+	This class is typically not used directly. Instead, declare typed attributes
+	on a State subclass, and the StateMeta metaclass will automatically convert
+	them into StateProperty instances.
+
+	Example:
+
+	```python
+	class MyState(ps.State):
+	    count: int = 0  # Automatically becomes a StateProperty
+	    name: str = "default"
+
+	state = MyState()
+	state.count = 5  # Updates the underlying Signal
+	print(state.count)  # Reads from the Signal, subscribes to changes
+	```
+	"""
+
 	pass
 
 
@@ -35,7 +59,33 @@ class InitializableProperty(ABC):
 
 class ComputedProperty(Generic[T]):
 	"""
-	Descriptor for computed properties on State classes.
+	Descriptor for computed (derived) properties on State classes.
+
+	ComputedProperty wraps a method that derives its value from other reactive
+	properties. The computed value is cached and only recalculated when its
+	dependencies change. Reading a computed property subscribes to it.
+
+	Created automatically when using the @ps.computed decorator on a State method.
+
+	Args:
+		name: The property name (used for debugging and the private storage key).
+		fn: The method that computes the value. Must take only `self` as argument.
+
+	Example:
+
+	```python
+	class MyState(ps.State):
+	    count: int = 0
+
+	    @ps.computed
+	    def doubled(self):
+	        return self.count * 2
+
+	state = MyState()
+	print(state.doubled)  # 0
+	state.count = 5
+	print(state.doubled)  # 10 (automatically recomputed)
+	```
 	"""
 
 	name: str
@@ -74,12 +124,56 @@ class ComputedProperty(Generic[T]):
 
 
 class StateEffect(Generic[T], InitializableProperty):
+	"""
+	Descriptor for side effects on State classes.
+
+	StateEffect wraps a method that performs side effects when its dependencies
+	change. The effect is initialized when the State instance is created and
+	disposed when the State is disposed.
+
+	Created automatically when using the @ps.effect decorator on a State method.
+	Supports both sync and async methods.
+
+		Args:
+			fn: The effect function. Must take only `self` as argument.
+			        Can return a cleanup function that runs before the next execution
+			        or when the effect is disposed.
+		name: Debug name for the effect. Defaults to "ClassName.method_name".
+		immediate: If True, run synchronously when scheduled (sync effects only).
+		lazy: If True, don't run on creation; wait for first dependency change.
+		on_error: Callback for handling errors during effect execution.
+		deps: Explicit dependencies. If provided, auto-tracking is disabled.
+		interval: Re-run interval in seconds for polling effects.
+
+	Example:
+
+	```python
+	class MyState(ps.State):
+	    count: int = 0
+
+	    @ps.effect
+	    def log_count(self):
+	        print(f"Count changed to: {self.count}")
+
+	    @ps.effect
+	    async def fetch_data(self):
+	        data = await api.fetch(self.query)
+	        self.data = data
+
+	    @ps.effect
+	    def subscribe(self):
+	        unsub = event_bus.subscribe(self.handle_event)
+	        return unsub  # Cleanup function
+	```
+	"""
+
 	fn: "Callable[[State], T]"
 	name: str | None
 	immediate: bool
 	on_error: "Callable[[Exception], None] | None"
 	lazy: bool
 	deps: "list[Signal[Any] | Computed[Any]] | None"
+	update_deps: bool | None
 	interval: float | None
 
 	def __init__(
@@ -90,6 +184,7 @@ class StateEffect(Generic[T], InitializableProperty):
 		lazy: bool = False,
 		on_error: "Callable[[Exception], None] | None" = None,
 		deps: "list[Signal[Any] | Computed[Any]] | None" = None,
+		update_deps: bool | None = None,
 		interval: float | None = None,
 	):
 		self.fn = fn
@@ -98,6 +193,7 @@ class StateEffect(Generic[T], InitializableProperty):
 		self.on_error = on_error
 		self.lazy = lazy
 		self.deps = deps
+		self.update_deps = update_deps
 		self.interval = interval
 
 	@override
@@ -111,6 +207,7 @@ class StateEffect(Generic[T], InitializableProperty):
 				lazy=self.lazy,
 				on_error=self.on_error,
 				deps=self.deps,
+				update_deps=self.update_deps,
 				interval=self.interval,
 			)
 		else:
@@ -121,6 +218,7 @@ class StateEffect(Generic[T], InitializableProperty):
 				lazy=self.lazy,
 				on_error=self.on_error,
 				deps=self.deps,
+				update_deps=self.update_deps,
 				interval=self.interval,
 			)
 		setattr(state, name, effect)
@@ -129,6 +227,28 @@ class StateEffect(Generic[T], InitializableProperty):
 class StateMeta(ABCMeta):
 	"""
 	Metaclass that automatically converts annotated attributes into reactive properties.
+
+	When a class uses StateMeta (via inheriting from State), the metaclass:
+
+	1. Converts all public type-annotated attributes into StateProperty descriptors
+	2. Converts all public non-callable values into StateProperty descriptors
+	3. Skips private attributes (starting with '_')
+	4. Preserves existing descriptors (StateProperty, ComputedProperty, StateEffect)
+
+	This enables the declarative state definition pattern:
+
+	Example:
+
+	```python
+	class MyState(ps.State):
+	    count: int = 0        # Becomes StateProperty
+	    name: str = "test"    # Becomes StateProperty
+	    _private: int = 0     # Stays as regular attribute (not reactive)
+
+	    @ps.computed
+	    def doubled(self):    # Becomes ComputedProperty
+	        return self.count * 2
+	```
 	"""
 
 	def __new__(
@@ -292,7 +412,19 @@ class State(Disposable, metaclass=StateMeta):
 		setattr(self, STATE_STATUS_FIELD, StateStatus.INITIALIZED)
 
 	def properties(self) -> Iterator[Signal[Any]]:
-		"""Iterate over the state's `Signal` instances, including base classes."""
+		"""
+		Iterate over the state's reactive Signal instances.
+
+		Traverses the class hierarchy (MRO) to include properties from base classes.
+		Each Signal is yielded only once, even if shadowed in subclasses.
+
+		Yields:
+			Signal[Any]: Each reactive property's underlying Signal instance.
+
+		Example:
+			for signal in state.properties():
+			    print(signal.name, signal.value)
+		"""
 		seen: set[str] = set()
 		for cls in self.__class__.__mro__:
 			if cls in (State, ABC):
@@ -305,7 +437,19 @@ class State(Disposable, metaclass=StateMeta):
 					yield prop.get_signal(self)
 
 	def computeds(self) -> Iterator[Computed[Any]]:
-		"""Iterate over the state's `Computed` instances, including base classes."""
+		"""
+		Iterate over the state's Computed instances.
+
+		Traverses the class hierarchy (MRO) to include computed properties from
+		base classes. Each Computed is yielded only once.
+
+		Yields:
+			Computed[Any]: Each computed property's underlying Computed instance.
+
+		Example:
+			for computed in state.computeds():
+			    print(computed.name, computed.read())
+		"""
 		seen: set[str] = set()
 		for cls in self.__class__.__mro__:
 			if cls in (State, ABC):
@@ -317,13 +461,24 @@ class State(Disposable, metaclass=StateMeta):
 					seen.add(name)
 					yield comp_prop.get_computed(self)
 
-	def effects(self):
-		"""Iterate over the state's `Effect` instances."""
+	def effects(self) -> Iterator[Effect]:
+		"""
+		Iterate over the state's Effect instances.
+
+		Returns effects that have been initialized on this state instance.
+		Effects are created from @ps.effect decorated methods when the
+		state is instantiated.
+
+		Yields:
+			Effect: Each effect instance attached to this state.
+
+		Example:
+			for effect in state.effects():
+			    print(effect.name)
+		"""
 		for value in self.__dict__.values():
 			if isinstance(value, Effect):
 				yield value
-			# if isinstance(value,QueryProperty):
-			#     value.
 
 	def on_dispose(self) -> None:
 		"""
@@ -335,9 +490,22 @@ class State(Disposable, metaclass=StateMeta):
 		pass
 
 	@override
-	def dispose(self):
-		# Call user-defined cleanup hook first
+	def dispose(self) -> None:
+		"""
+		Clean up the state, disposing all effects and resources.
 
+		Calls on_dispose() first for user-defined cleanup, then disposes all
+		Disposable instances attached to this state (including effects).
+
+		This method is called automatically when the state goes out of scope
+		or when explicitly cleaning up. After disposal, the state should not
+		be used.
+
+		Raises:
+			RuntimeError: If any effects defined on the state's scope were not
+			        properly disposed.
+		"""
+		# Call user-defined cleanup hook first
 		self.on_dispose()
 		for value in self.__dict__.values():
 			if isinstance(value, Disposable):

pulse/test_helpers.py

@@ -0,0 +1,15 @@
+import asyncio
+from collections.abc import Callable
+
+
+async def wait_for(
+	condition: Callable[[], bool], *, timeout: float = 1.0, poll_interval: float = 0.005
+) -> bool:
+	"""Poll until condition() is truthy or timeout. Returns True if condition met."""
+	loop = asyncio.get_event_loop()
+	deadline = loop.time() + timeout
+	while loop.time() < deadline:
+		if condition():
+			return True
+		await asyncio.sleep(poll_interval)
+	return False

pulse/transpiler/__init__.py

@@ -3,10 +3,23 @@
 # Ensure built-in Python modules (e.g., math) are registered on import.
 from pulse.transpiler import modules as _modules  # noqa: F401
 
+# Asset registry (unified for Import and DynamicImport)
+from pulse.transpiler.assets import LocalAsset as LocalAsset
+from pulse.transpiler.assets import clear_asset_registry as clear_asset_registry
+from pulse.transpiler.assets import get_registered_assets as get_registered_assets
+from pulse.transpiler.assets import register_local_asset as register_local_asset
+
 # Builtins
 from pulse.transpiler.builtins import BUILTINS as BUILTINS
 from pulse.transpiler.builtins import emit_method as emit_method
 
+# Dynamic import primitive
+from pulse.transpiler.dynamic_import import DynamicImport as DynamicImport
+from pulse.transpiler.dynamic_import import import_ as import_
+
+# Emit context
+from pulse.transpiler.emit_context import EmitContext as EmitContext
+
 # Errors
 from pulse.transpiler.errors import TranspileError as TranspileError
 
@@ -93,9 +106,6 @@ from pulse.transpiler.nodes import While as While
 # Emit
 from pulse.transpiler.nodes import emit as emit
 
-# React components (JSX imports with typed call signature)
-from pulse.transpiler.react_component import react_component as react_component
-
 # Transpiler
 from pulse.transpiler.transpiler import Transpiler as Transpiler
 from pulse.transpiler.transpiler import transpile as transpile