pulse-framework 0.1.62__py3-none-any.whl

pulse/queries/store.py

@@ -0,0 +1,120 @@
+import datetime as dt
+from collections.abc import Callable
+from typing import Any, TypeVar, cast
+
+from pulse.helpers import MISSING
+from pulse.queries.common import QueryKey
+from pulse.queries.infinite_query import InfiniteQuery, Page
+from pulse.queries.query import RETRY_DELAY_DEFAULT, KeyedQuery
+
+T = TypeVar("T")
+
+
+class QueryStore:
+	"""
+	Store for query entries. Manages creation, retrieval, and disposal of queries.
+	"""
+
+	def __init__(self):
+		self._entries: dict[QueryKey, KeyedQuery[Any] | InfiniteQuery[Any, Any]] = {}
+
+	def items(self):
+		"""Iterate over all (key, query) pairs in the store."""
+		return self._entries.items()
+
+	def get_any(self, key: QueryKey):
+		"""Get any query (regular or infinite) by key, or None if not found."""
+		return self._entries.get(key)
+
+	def ensure(
+		self,
+		key: QueryKey,
+		initial_data: T | None = MISSING,
+		initial_data_updated_at: float | dt.datetime | None = None,
+		gc_time: float = 300.0,
+		retries: int = 3,
+		retry_delay: float = RETRY_DELAY_DEFAULT,
+	) -> KeyedQuery[T]:
+		# Return existing entry if present
+		existing = self._entries.get(key)
+		if existing:
+			if isinstance(existing, InfiniteQuery):
+				raise TypeError(
+					"Query key is already used for an infinite query; cannot reuse for regular query"
+				)
+			return cast(KeyedQuery[T], existing)
+
+		def _on_dispose(e: KeyedQuery[Any]) -> None:
+			if e.key in self._entries and self._entries[e.key] is e:
+				del self._entries[e.key]
+
+		entry = KeyedQuery(
+			key,
+			initial_data=initial_data,
+			initial_data_updated_at=initial_data_updated_at,
+			gc_time=gc_time,
+			retries=retries,
+			retry_delay=retry_delay,
+			on_dispose=_on_dispose,
+		)
+		self._entries[key] = entry
+		return entry
+
+	def get(self, key: QueryKey) -> KeyedQuery[Any] | None:
+		"""
+		Get an existing regular query by key, or None if not found.
+		"""
+		existing = self._entries.get(key)
+		if existing and isinstance(existing, InfiniteQuery):
+			return None
+		return existing
+
+	def get_infinite(self, key: QueryKey) -> InfiniteQuery[Any, Any] | None:
+		"""
+		Get an existing infinite query by key, or None if not found.
+		"""
+		existing = self._entries.get(key)
+		if existing and isinstance(existing, InfiniteQuery):
+			return existing
+		return None
+
+	def ensure_infinite(
+		self,
+		key: QueryKey,
+		*,
+		initial_page_param: Any,
+		get_next_page_param: Callable[[list[Page[Any, Any]]], Any | None],
+		get_previous_page_param: Callable[[list[Page[Any, Any]]], Any | None]
+		| None = None,
+		max_pages: int = 0,
+		initial_data_updated_at: float | dt.datetime | None = None,
+		gc_time: float = 300.0,
+		retries: int = 3,
+		retry_delay: float = RETRY_DELAY_DEFAULT,
+	) -> InfiniteQuery[Any, Any]:
+		existing = self._entries.get(key)
+		if existing:
+			if not isinstance(existing, InfiniteQuery):
+				raise TypeError(
+					"Query key is already used for a regular query; cannot reuse for infinite query"
+				)
+			return existing
+
+		def _on_dispose(e: InfiniteQuery[Any, Any]) -> None:
+			if e.key in self._entries and self._entries[e.key] is e:
+				del self._entries[e.key]
+
+		entry = InfiniteQuery(
+			key,
+			initial_page_param=initial_page_param,
+			get_next_page_param=get_next_page_param,
+			get_previous_page_param=get_previous_page_param,
+			max_pages=max_pages,
+			initial_data_updated_at=initial_data_updated_at,
+			gc_time=gc_time,
+			retries=retries,
+			retry_delay=retry_delay,
+			on_dispose=_on_dispose,
+		)
+		self._entries[key] = entry
+		return entry

pulse/react_component.py

@@ -0,0 +1,88 @@
+"""React component helpers for Python API."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, ParamSpec, overload
+
+from pulse.js.react import lazy as react_lazy
+from pulse.transpiler.imports import Import
+from pulse.transpiler.nodes import Element, Expr, Jsx, Node
+
+P = ParamSpec("P")
+
+
+def default_signature(
+	*children: Node, key: str | None = None, **props: Any
+) -> Element: ...
+
+
+class ReactComponent(Jsx):
+	"""JSX wrapper for React components with runtime call support."""
+
+	def __init__(self, expr_or_src: Expr | str, *, lazy: bool = False) -> None:
+		if isinstance(expr_or_src, str):
+			if lazy:
+				expr: Expr = react_lazy(Import(expr_or_src, lazy=True))
+			else:
+				expr = Import(expr_or_src)
+		else:
+			if lazy:
+				raise TypeError(
+					"ReactComponent lazy only supported with a source string"
+				)
+			expr = expr_or_src
+		if not isinstance(expr, Expr):
+			raise TypeError("ReactComponent expects an Expr or source string")
+		if isinstance(expr, Jsx):
+			expr = expr.expr
+		super().__init__(expr)
+
+
+@overload
+def react_component(
+	expr_or_name: Expr,
+) -> Callable[[Callable[P, Any]], Callable[P, Element]]: ...
+
+
+@overload
+def react_component(
+	expr_or_name: str,
+	src: str | None = None,
+	*,
+	lazy: bool = False,
+) -> Callable[[Callable[P, Any]], Callable[P, Element]]: ...
+
+
+def react_component(
+	expr_or_name: Expr | str,
+	src: str | None = None,
+	*,
+	lazy: bool = False,
+) -> Callable[[Callable[P, Any]], Callable[P, Element]]:
+	"""Decorator for typed React component bindings."""
+	if isinstance(expr_or_name, Expr):
+		if src is not None:
+			raise TypeError("react_component expects (expr) or (name, src)")
+		if lazy:
+			raise TypeError("react_component lazy only supported with string inputs")
+		component = ReactComponent(expr_or_name)
+	elif isinstance(expr_or_name, str):
+		if src is None:
+			component = ReactComponent(expr_or_name, lazy=lazy)
+		else:
+			imp = Import(expr_or_name, src, lazy=lazy)
+			if lazy:
+				component = ReactComponent(react_lazy(imp))
+			else:
+				component = ReactComponent(imp)
+	else:
+		raise TypeError("react_component expects an Expr or (name, src)")
+
+	def decorator(fn: Callable[P, Any]) -> Callable[P, Element]:
+		return component.as_(fn)
+
+	return decorator
+
+
+__all__ = ["ReactComponent", "react_component", "default_signature"]