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

pulse/env.py

@@ -18,6 +18,13 @@ from typing import Literal
 
 # Types
 PulseEnv = Literal["dev", "ci", "prod"]
+"""Environment type for the Pulse application.
+
+Values:
+    "dev": Development environment with hot reload and debugging.
+    "ci": Continuous integration environment for testing.
+    "prod": Production environment with optimizations enabled.
+"""
 
 # Keys
 ENV_PULSE_ENV = "PULSE_ENV"
@@ -31,6 +38,28 @@ ENV_PULSE_DISABLE_CODEGEN = "PULSE_DISABLE_CODEGEN"
 
 
 class EnvVars:
+	"""Singleton accessor for Pulse environment variables.
+
+	Provides typed getters and setters for all Pulse-related environment
+	variables. Access via the `env` singleton instance.
+
+	Example:
+		```python
+		from pulse.env import env
+
+		env.pulse_env = "prod"
+		if env.pulse_env == "dev":
+		    print(f"Running on {env.pulse_host}:{env.pulse_port}")
+		```
+
+	Attributes:
+		pulse_env: Current environment ("dev", "ci", "prod").
+		pulse_host: Server hostname. Defaults to "localhost".
+		pulse_port: Server port number. Defaults to 8000.
+		pulse_secret: Secret key for JWT session signing.
+		codegen_disabled: If True, skip code generation.
+	"""
+
 	def _get(self, key: str) -> str | None:
 		return os.environ.get(key)
 
@@ -117,8 +146,33 @@ class EnvVars:
 
 # Singleton
 env = EnvVars()
+"""Singleton instance for accessing Pulse environment variables.
+
+Example:
+    ```python
+    from pulse.env import env
+
+    env.pulse_env = "prod"
+    print(env.pulse_host)  # "localhost"
+    print(env.pulse_port)  # 8000
+    ```
+"""
+
+
+def mode() -> PulseEnv:
+	"""Returns the current pulse_env value.
+
+	Shorthand for `env.pulse_env`.
+
+	Returns:
+		The current environment: "dev", "ci", or "prod".
 
+	Example:
+		```python
+		from pulse.env import mode
 
-# Commonly used helpesr
-def mode():
+		if mode() == "dev":
+		    enable_debug_toolbar()
+		```
+	"""
 	return env.pulse_env

pulse/form.py

@@ -42,8 +42,16 @@ __all__ = [
 	"FormStorage",
 	"internal_forms_hook",
 ]
+
 FormValue = str | UploadFile
+"""Individual form field value: ``str | UploadFile``."""
+
 FormData = dict[str, FormValue | list[FormValue]]
+"""Parsed form submission data.
+
+Values are either single or multiple (for repeated field names).
+Type alias for ``dict[str, FormValue | list[FormValue]]``.
+"""
 
 
 @react_component(Import("PulseForm", "pulse-ui-client"))
@@ -56,6 +64,16 @@ def client_form_component(
 
 @dataclass
 class FormRegistration:
+	"""Internal registration info for a form.
+
+	Attributes:
+		id: Unique form identifier.
+		render_id: Associated render session ID.
+		route_path: Route path this form is bound to.
+		session_id: Associated user session ID.
+		on_submit: Async callback for form submission.
+	"""
+
 	id: str
 	render_id: str
 	route_path: str
@@ -64,6 +82,12 @@ class FormRegistration:
 
 
 class FormRegistry(Disposable):
+	"""Internal class managing form registrations.
+
+	Not typically used directly. Forms are registered automatically via
+	``ps.Form`` or ``ManualForm``.
+	"""
+
 	def __init__(self, render: "RenderSession") -> None:
 		self._render: "RenderSession" = render
 		self._handlers: dict[str, FormRegistration] = {}
@@ -75,6 +99,17 @@ class FormRegistry(Disposable):
 		session_id: str,
 		on_submit: Callable[[FormData], Awaitable[None]],
 	) -> FormRegistration:
+		"""Register a form handler.
+
+		Args:
+			render_id: Render session ID.
+			route_id: Route path.
+			session_id: User session ID.
+			on_submit: Async callback for form submission.
+
+		Returns:
+			FormRegistration with generated form ID.
+		"""
 		registration = FormRegistration(
 			uuid.uuid4().hex,
 			render_id=render_id,
@@ -86,10 +121,16 @@ class FormRegistry(Disposable):
 		return registration
 
 	def unregister(self, form_id: str) -> None:
+		"""Unregister a form handler.
+
+		Args:
+			form_id: The form ID to unregister.
+		"""
 		self._handlers.pop(form_id, None)
 
 	@override
 	def dispose(self) -> None:
+		"""Clean up all registered forms."""
 		self._handlers.clear()
 
 	async def handle_submit(
@@ -98,6 +139,20 @@ class FormRegistry(Disposable):
 		request: Request,
 		session: "UserSession",
 	) -> Response:
+		"""Handle incoming form submission.
+
+		Args:
+			form_id: The form ID being submitted.
+			request: The HTTP request.
+			session: The user session.
+
+		Returns:
+			HTTP response (204 on success).
+
+		Raises:
+			HTTPException: If form not found (404), session mismatch (403),
+				or route unmounted (410).
+		"""
 		registration = self._handlers.get(form_id)
 		if registration is None:
 			raise HTTPException(status_code=404, detail="Unknown form submission")
@@ -139,6 +194,16 @@ class FormRegistry(Disposable):
 
 
 def normalize_form_data(raw: StarletteFormData) -> FormData:
+	"""Convert Starlette FormData to normalized FormData dict.
+
+	Handles multiple values for the same key and filters out empty file uploads.
+
+	Args:
+		raw: Starlette FormData from request.form().
+
+	Returns:
+		Normalized FormData dictionary.
+	"""
 	normalized: FormData = {}
 	for key, value in raw.multi_items():
 		item: FormValue
@@ -163,6 +228,11 @@ def normalize_form_data(raw: StarletteFormData) -> FormData:
 
 
 class PulseFormProps(HTMLFormProps, total=False):
+	"""Form props that exclude action, method, encType, and onSubmit.
+
+	These props are auto-generated by Pulse for form handling.
+	"""
+
 	action: Never  # pyright: ignore[reportIncompatibleVariableOverride]
 	method: Never  # pyright: ignore[reportIncompatibleVariableOverride]
 	encType: Never  # pyright: ignore[reportIncompatibleVariableOverride]
@@ -174,7 +244,48 @@ def Form(
 	key: str,
 	onSubmit: EventHandler1[FormData] | None = None,
 	**props: Unpack[PulseFormProps],  # pyright: ignore[reportGeneralTypeIssues]
-):
+) -> Node:
+	"""Server-registered HTML form component.
+
+	Automatically wires up form submission to a Python handler. Uses
+	``multipart/form-data`` encoding to support file uploads.
+
+	Args:
+		*children: Form content (inputs, buttons, etc.).
+		key: Unique form identifier (required, non-empty string).
+		onSubmit: Submit handler receiving parsed FormData.
+		**props: Standard HTML form props (except action, method, encType, onSubmit).
+
+	Returns:
+		Form node.
+
+	Raises:
+		ValueError: If key is empty or onSubmit is not callable.
+		RuntimeError: If called outside a component render.
+
+	Example:
+
+	```python
+	async def handle_submit(data: ps.FormData):
+	    name = data.get("name")  # str
+	    file = data.get("avatar")  # UploadFile
+	    await save_user(name, file)
+
+	def my_form():
+	    return ps.Form(
+	        m.TextInput(name="name", label="Name"),
+	        m.FileInput(name="avatar", label="Avatar"),
+	        m.Button("Submit", type="submit"),
+	        key="user-form",
+	        onSubmit=handle_submit,
+	    )
+	```
+
+	Note:
+		- ``key`` must be unique within the render.
+		- Cannot override ``action``, ``method``, ``encType``, or ``onSubmit`` via props.
+		- Handler receives parsed form data as a ``FormData`` dict.
+	"""
 	if not isinstance(key, str) or not key:
 		raise ValueError("ps.Form requires a non-empty string key")
 	if not callable(onSubmit):
@@ -197,6 +308,15 @@ def Form(
 
 
 class GeneratedFormProps(TypedDict):
+	"""Form props generated by ``ManualForm.props()``.
+
+	Attributes:
+		action: Form submission URL.
+		method: HTTP method ("POST").
+		encType: Encoding type ("multipart/form-data").
+		onSubmit: Submission trigger callback.
+	"""
+
 	action: str
 	method: str
 	encType: str
@@ -204,11 +324,51 @@ class GeneratedFormProps(TypedDict):
 
 
 class ManualForm(Disposable):
+	"""Low-level form handler for custom form implementations.
+
+	Use when you need more control over form rendering than ``ps.Form`` provides.
+
+	Attributes:
+		is_submitting: Whether the form is currently submitting.
+		registration: Form registration info (raises if disposed).
+
+	Example:
+
+	```python
+	def custom_form():
+	    manual = ManualForm(on_submit=handle_data)
+
+	    # Option 1: Render directly
+	    return manual(
+	        m.TextInput(name="field"),
+	        m.Button("Submit", type="submit"),
+	        key="my-form",
+	    )
+
+	    # Option 2: Use props manually
+	    form_props = manual.props()
+	    return m.form(
+	        m.TextInput(name="field"),
+	        m.Button("Submit", type="submit"),
+	        **form_props,
+	    )
+	```
+	"""
+
 	_submit_signal: Signal[bool]
 	_render: "RenderSession"
 	_registration: FormRegistration | None
 
 	def __init__(self, on_submit: EventHandler1[FormData] | None = None) -> None:
+		"""Initialize a manual form handler.
+
+		Args:
+			on_submit: Optional submit handler receiving parsed FormData.
+
+		Raises:
+			RuntimeError: If called outside a render pass, route context,
+				or user session.
+		"""
 		ctx = PulseContext.get()
 		render = ctx.render
 		route = ctx.route
@@ -238,19 +398,30 @@ class ManualForm(Disposable):
 		return on_submit_handler
 
 	@property
-	def is_submitting(self):
+	def is_submitting(self) -> bool:
+		"""Whether the form is currently submitting."""
 		return self._submit_signal.read()
 
 	@property
-	def registration(self):
+	def registration(self) -> FormRegistration:
+		"""Form registration info.
+
+		Raises:
+			ValueError: If the form has been disposed.
+		"""
 		if self._registration is None:
 			raise ValueError("This form has been disposed")
 		return self._registration
 
-	def _start_submit(self):
+	def _start_submit(self) -> None:
 		self._submit_signal.write(True)
 
 	def props(self) -> GeneratedFormProps:
+		"""Get form props for manual binding to a form element.
+
+		Returns:
+			Dict with action, method, encType, and onSubmit props.
+		"""
 		return {
 			"action": f"{server_address()}/pulse/forms/{self._render.id}/{self.registration.id}",
 			"method": "POST",
@@ -263,22 +434,44 @@ class ManualForm(Disposable):
 		*children: Node,
 		key: str | None = None,
 		**props: Unpack[PulseFormProps],
-	):
+	) -> Node:
+		"""Render as a form element with children.
+
+		Args:
+			*children: Form content.
+			key: Optional element key.
+			**props: Additional form props.
+
+		Returns:
+			Form node with auto-generated submission props.
+		"""
 		props.update(self.props())  # pyright: ignore[reportCallIssue, reportArgumentType]
 		return client_form_component(*children, key=key, **props)
 
 	@override
 	def dispose(self) -> None:
+		"""Unregister the form and clean up."""
 		if self._registration is None:
 			return
 		self._render.forms.unregister(self._registration.id)
 		self._registration = None
 
 	def update(self, on_submit: EventHandler1[FormData] | None) -> None:
+		"""Update the submit handler.
+
+		Args:
+			on_submit: New submit handler.
+		"""
 		self.registration.on_submit = self.wrap_on_submit(on_submit)
 
 
 class FormStorage(HookState):
+	"""Internal hook state for managing form lifecycle within renders.
+
+	Not typically used directly. Manages form persistence and cleanup across
+	render cycles.
+	"""
+
 	__slots__ = ("forms", "prev_forms", "render_mark")  # pyright: ignore[reportUnannotatedClassAttribute]
 	render_mark: int
 

pulse/helpers.py

@@ -252,7 +252,13 @@ def later(
 
 	from pulse.reactive import Untrack
 
-	loop = asyncio.get_running_loop()
+	try:
+		loop = asyncio.get_running_loop()
+	except RuntimeError:
+		try:
+			loop = asyncio.get_event_loop()
+		except RuntimeError as exc:
+			raise RuntimeError("later() requires an event loop") from exc
 
 	def _run():
 		try:

pulse/hooks/core.py

@@ -31,6 +31,18 @@ MISSING: Any = object()
 
 @dataclass(slots=True)
 class HookMetadata:
+	"""Metadata for a registered hook.
+
+	Contains optional descriptive information about a hook, useful for
+	debugging and documentation.
+
+	Attributes:
+		description: Human-readable description of the hook's purpose.
+		owner: Module or package that owns this hook (e.g., "pulse.core").
+		version: Version string for the hook implementation.
+		extra: Additional metadata as a mapping.
+	"""
+
 	description: str | None = None
 	owner: str | None = None
 	version: str | None = None
@@ -38,20 +50,58 @@ class HookMetadata:
 
 
 class HookState(Disposable):
-	"""Base class returned by hook factories."""
+	"""Base class for hook state returned by hook factories.
+
+	Subclass this to create custom hook state that persists across renders.
+	Override lifecycle methods to respond to render events.
+
+	Attributes:
+		render_cycle: The current render cycle number.
+
+	Example:
+
+	```python
+	class TimerHookState(ps.hooks.State):
+	    def __init__(self):
+	        self.start_time = time.time()
+
+	    def elapsed(self) -> float:
+	        return time.time() - self.start_time
+
+	    def dispose(self) -> None:
+	        pass
+
+	_timer_hook = ps.hooks.create("my_app:timer", lambda: TimerHookState())
+
+	def use_timer() -> TimerHookState:
+	    return _timer_hook()
+	```
+	"""
 
 	render_cycle: int = 0
 
 	def on_render_start(self, render_cycle: int) -> None:
+		"""Called before each component render.
+
+		Args:
+			render_cycle: The current render cycle number.
+		"""
 		self.render_cycle = render_cycle
 
 	def on_render_end(self, render_cycle: int) -> None:
-		"""Called after the component render has completed."""
+		"""Called after the component render has completed.
+
+		Args:
+			render_cycle: The current render cycle number.
+		"""
 		...
 
 	@override
 	def dispose(self) -> None:
-		"""Called when the hook instance is discarded."""
+		"""Called when the hook instance is discarded.
+
+		Override to clean up resources (close connections, cancel tasks, etc.).
+		"""
 		...
 
 
@@ -66,11 +116,33 @@ def _default_factory() -> HookState:
 
 @dataclass(slots=True)
 class Hook(Generic[T]):
+	"""A registered hook definition.
+
+	Hooks are created via ``ps.hooks.create()`` and can be called during
+	component render to access their associated state.
+
+	Attributes:
+		name: Unique name identifying this hook.
+		factory: Function that creates new HookState instances.
+		metadata: Optional metadata about the hook.
+	"""
+
 	name: str
 	factory: HookFactory[T]
 	metadata: HookMetadata
 
 	def __call__(self, key: str | None = None) -> T:
+		"""Get or create hook state for the current component.
+
+		Args:
+			key: Optional key for multiple instances of the same hook.
+
+		Returns:
+			The hook state instance.
+
+		Raises:
+			HookError: If called outside of a render context.
+		"""
 		ctx = HookContext.require(self.name)
 		namespace = ctx.namespace_for(self)
 		state = namespace.ensure(ctx, key)
@@ -79,6 +151,17 @@ class Hook(Generic[T]):
 
 @dataclass(slots=True)
 class HookInit(Generic[T]):
+	"""Initialization context passed to hook factories.
+
+	When a hook factory accepts a single argument, it receives this object
+	containing context about the initialization.
+
+	Attributes:
+		key: Optional key if the hook was called with a specific key.
+		render_cycle: The current render cycle number.
+		definition: Reference to the Hook definition being initialized.
+	"""
+
 	key: str | None
 	render_cycle: int
 	definition: Hook[T]
@@ -178,7 +261,6 @@ class HookContext:
 		if self._token is not None:
 			HOOK_CONTEXT.reset(self._token)
 			self._token = None
-
 			for namespace in self.namespaces.values():
 				namespace.on_render_end(self.render_cycle)
 		return False
@@ -265,6 +347,19 @@ HOOK_REGISTRY: HookRegistry = HookRegistry()
 
 
 class HooksAPI:
+	"""Low-level API for creating custom hooks.
+
+	Access via ``ps.hooks``. Provides methods for registering, listing,
+	and managing hooks.
+
+	Attributes:
+		State: Alias for HookState base class.
+		Metadata: Alias for HookMetadata dataclass.
+		AlreadyRegisteredError: Exception for duplicate hook registration.
+		NotFoundError: Exception for missing hook lookup.
+		RenameCollisionError: Exception for hook rename conflicts.
+	"""
+
 	__slots__ = ()  # pyright: ignore[reportUnannotatedClassAttribute]
 
 	State: type[HookState] = HookState
@@ -281,7 +376,42 @@ class HooksAPI:
 		factory: HookFactory[T] = _default_factory,
 		*,
 		metadata: HookMetadata | None = None,
-	):
+	) -> "Hook[T]":
+		"""Register a new hook.
+
+		Args:
+			name: Unique name for the hook (e.g., "my_app:timer").
+			factory: Function that creates HookState instances. Can be a
+				zero-argument callable or accept a HookInit object.
+			metadata: Optional metadata describing the hook.
+
+		Returns:
+			Hook[T]: The registered hook, callable during component render.
+
+		Raises:
+			ValueError: If name is empty.
+			HookAlreadyRegisteredError: If a hook with this name already exists.
+			HookError: If the registry is locked.
+
+		Example:
+
+		```python
+		class TimerHookState(ps.hooks.State):
+		    def __init__(self):
+		        self.start_time = time.time()
+
+		    def elapsed(self) -> float:
+		        return time.time() - self.start_time
+
+		    def dispose(self) -> None:
+		        pass
+
+		_timer_hook = ps.hooks.create("my_app:timer", lambda: TimerHookState())
+
+		def use_timer() -> TimerHookState:
+		    return _timer_hook()
+		```
+		"""
 		return HOOK_REGISTRY.create(name, factory, metadata)
 
 	def rename(self, current: str, new: str) -> None: