pulse-framework 0.1.0__py3-none-any.whl

pulse/decorators.py

@@ -0,0 +1,187 @@
+# Separate file from reactive.py due to needing to import from state too
+
+from typing import Any, Callable, Coroutine, Optional, TypeVar, overload
+
+from pulse.state import State, ComputedProperty, StateEffect
+from pulse.reactive import Computed, Effect, EffectCleanup, EffectFn
+import inspect
+from pulse.query import QueryProperty, QueryPropertyWithInitial
+
+
+T = TypeVar("T")
+TState = TypeVar("TState", bound=State)
+
+
+# -> @ps.computed The chalenge is:
+# - We want to turn regular functions with no arguments into a Computed object
+# - We want to turn state methods into a ComputedProperty (which wraps a
+#   Computed, but gives it access to the State object).
+@overload
+def computed(fn: Callable[[], T], *, name: Optional[str] = None) -> Computed[T]: ...
+@overload
+def computed(
+    fn: Callable[[TState], T], *, name: Optional[str] = None
+) -> ComputedProperty[T]: ...
+@overload
+def computed(
+    fn: None = None, *, name: Optional[str] = None
+) -> Callable[[Callable[[], T]], Computed[T]]: ...
+
+
+def computed(fn: Optional[Callable] = None, *, name: Optional[str] = None):
+    # The type checker is not happy if I don't specify the `/` here.
+    def decorator(fn: Callable, /):
+        sig = inspect.signature(fn)
+        params = list(sig.parameters.values())
+        # Check if it's a method with exactly one argument called 'self'
+        if len(params) == 1 and params[0].name == "self":
+            return ComputedProperty(fn.__name__, fn)
+        # If it has any arguments at all, it's not allowed (except for 'self')
+        if len(params) > 0:
+            raise TypeError(
+                f"@computed: Function '{fn.__name__}' must take no arguments or a single 'self' argument"
+            )
+        return Computed(fn, name=name or fn.__name__)
+
+    if fn is not None:
+        return decorator(fn)
+    else:
+        return decorator
+
+
+@overload
+def effect(
+    fn: EffectFn,
+    *,
+    name: Optional[str] = None,
+    immediate: bool = False,
+    lazy: bool = False,
+    on_error: Optional[Callable[[Exception], None]] = None,
+) -> Effect: ...
+# In practice this overload returns a StateEffect, but it gets converted into an
+# Effect at state instantiation.
+@overload
+def effect(
+    fn: Callable[[TState], None] | Callable[[TState], EffectCleanup],
+) -> Effect: ...
+@overload
+def effect(
+    fn: None = None,
+    *,
+    name: Optional[str] = None,
+    immediate: bool = False,
+    lazy: bool = False,
+    on_error: Optional[Callable[[Exception], None]] = None,
+) -> Callable[[EffectFn], Effect]: ...
+
+
+def effect(
+    fn: Optional[Callable] = None,
+    *,
+    name: Optional[str] = None,
+    immediate: bool = False,
+    lazy: bool = False,
+    on_error: Optional[Callable[[Exception], None]] = None,
+):
+    # The type checker is not happy if I don't specify the `/` here.
+    def decorator(func: Callable, /):
+        sig = inspect.signature(func)
+        params = list(sig.parameters.values())
+
+        if len(params) == 1 and params[0].name == "self":
+            return StateEffect(func, on_error=on_error)
+
+        if len(params) > 0:
+            raise TypeError(
+                f"@effect: Function '{func.__name__}' must take no arguments or a single 'self' argument"
+            )
+
+        # This is a standalone effect function. Create the Effect object.
+        return Effect(
+            func,
+            name=name or func.__name__,
+            immediate=immediate,
+            lazy=lazy,
+            on_error=on_error,
+        )
+
+    if fn:
+        return decorator(fn)
+    return decorator
+
+
+# -----------------
+# Query decorator
+# -----------------
+@overload
+def query(
+    fn: Callable[[TState], Coroutine[Any, Any, T]],
+    *,
+    keep_alive: bool = False,  # noqa: F821
+    keep_previous_data: bool = True,
+) -> QueryProperty[T]: ...
+@overload
+def query(
+    fn: None = None, *, keep_alive: bool = False, keep_previous_data: bool = True
+) -> Callable[[Callable[[TState], Coroutine[Any, Any, T]]], QueryProperty[T]]: ...
+
+
+# When an initial value is provided, the resulting property narrows data to non-None
+@overload
+def query(
+    fn: Callable[[TState], Coroutine[Any, Any, T]],
+    *,
+    keep_alive: bool = False,
+    keep_previous_data: bool = True,
+    initial: T,
+) -> QueryPropertyWithInitial[T]: ...
+@overload
+def query(
+    fn: None = None,
+    *,
+    keep_alive: bool = False,
+    keep_previous_data: bool = True,
+    initial: T,
+) -> Callable[
+    [Callable[[TState], Coroutine[Any, Any, T]]], QueryPropertyWithInitial[T]
+]: ...
+
+
+def query(
+    fn: Optional[Callable] = None,
+    *,
+    keep_alive: bool = False,
+    keep_previous_data: bool = True,
+    initial: Any = None,
+) -> (
+    QueryProperty[T]
+    | QueryPropertyWithInitial[T]
+    | Callable[
+        [Callable[[TState], Coroutine[Any, Any, T]]],
+        QueryProperty[T] | QueryPropertyWithInitial[T],
+    ]
+):
+    def decorator(func: Callable[[TState], Coroutine[Any, Any, T]], /):
+        sig = inspect.signature(func)
+        params = list(sig.parameters.values())
+        # Only state-method form supported for now (single 'self')
+        if not (len(params) == 1 and params[0].name == "self"):
+            raise TypeError("@query currently only supports state methods (self)")
+        if initial is not None:
+            return QueryPropertyWithInitial(
+                func.__name__,
+                func,
+                keep_alive=keep_alive,
+                keep_previous_data=keep_previous_data,
+                initial=initial,
+            )
+        return QueryProperty(
+            func.__name__,
+            func,
+            keep_alive=keep_alive,
+            keep_previous_data=keep_previous_data,
+        )
+
+    if fn:
+        return decorator(fn)
+    return decorator

pulse/diff.py

@@ -0,0 +1,252 @@
+from typing import (
+    TypedDict,
+    Union,
+    Optional,
+    Literal,
+    Sequence,
+    Any,
+)
+from .vdom import VDOM, Props, Node, Primitive, Element
+
+
+class InsertOperation(TypedDict):
+    type: Literal["insert"]
+    path: str
+    data: VDOM
+
+
+class RemoveOperation(TypedDict):
+    type: Literal["remove"]
+    path: str
+
+
+class ReplaceOperation(TypedDict):
+    type: Literal["replace"]
+    path: str
+    data: VDOM
+
+
+class UpdatePropsOperation(TypedDict):
+    type: Literal["update_props"]
+    path: str
+    data: Props
+
+
+class MoveOperationData(TypedDict):
+    from_index: int
+    to_index: int
+    key: str
+
+
+class MoveOperation(TypedDict):
+    type: Literal["move"]
+    path: str
+    data: MoveOperationData
+
+
+VDOMOperation = Union[
+    InsertOperation,
+    RemoveOperation,
+    ReplaceOperation,
+    UpdatePropsOperation,
+    MoveOperation,
+]
+
+
+def _render_to_vdom(node: Union[Node, Primitive], path: str) -> VDOM:
+    if isinstance(node, Node):
+        return node._render_node(path, {})
+    return node
+
+
+def _effective_props(node: Node, path: str) -> dict[str, Any]:
+    props = dict(node.props or {})
+    if node.callbacks:
+        path_prefix = (path + ".") if path else ""
+        for cb_name in node.callbacks.keys():
+            props[cb_name] = f"$$fn:{path_prefix}{cb_name}"
+    return props
+
+
+def diff_node(
+    old_node: Optional[Union[Node, Primitive]],
+    new_node: Optional[Union[Node, Primitive]],
+    path: str = "",
+) -> list[VDOMOperation]:
+    operations: list[VDOMOperation] = []
+
+    # Handle null cases
+    if old_node is None and new_node is None:
+        return operations
+    elif old_node is None:
+        assert new_node is not None
+        operations.append(
+            {"type": "insert", "path": path, "data": _render_to_vdom(new_node, path)}
+        )
+        return operations
+    elif new_node is None:
+        operations.append({"type": "remove", "path": path, "data": None})
+        return operations
+
+    # Primitives equality
+    if not isinstance(old_node, Node) and not isinstance(new_node, Node):
+        if old_node == new_node:
+            return operations
+        else:
+            operations.append({"type": "replace", "path": path, "data": new_node})
+            return operations
+
+    # Type mismatch or tag difference => replace
+    if not isinstance(old_node, Node) or not isinstance(new_node, Node):
+        operations.append(
+            {"type": "replace", "path": path, "data": _render_to_vdom(new_node, path)}
+        )
+        return operations
+
+    if old_node.tag != new_node.tag:
+        operations.append(
+            {"type": "replace", "path": path, "data": _render_to_vdom(new_node, path)}
+        )
+        return operations
+
+    # Same tag - diff props (including callback placeholders)
+    old_props = _effective_props(old_node, path)
+    new_props = _effective_props(new_node, path)
+    if old_props != new_props:
+        operations.append({"type": "update_props", "path": path, "data": new_props})
+
+    # Diff children
+    old_children: list[Element] = list(old_node.children or [])
+    new_children: list[Element] = list(new_node.children or [])
+
+    # Determine strategy based on keys
+    has_keyed_old = any(isinstance(c, Node) and c.key is not None for c in old_children)
+    has_keyed_new = any(isinstance(c, Node) and c.key is not None for c in new_children)
+
+    if has_keyed_old or has_keyed_new:
+        operations.extend(_diff_keyed_children(old_children, new_children, path))
+    else:
+        operations.extend(_diff_positional_children(old_children, new_children, path))
+
+    return operations
+
+
+def _diff_keyed_children(
+    old_children: Sequence[Element], new_children: Sequence[Element], path: str
+) -> list[VDOMOperation]:
+    operations: list[VDOMOperation] = []
+
+    old_keyed: dict[str, Node] = {}
+    old_positions: dict[str, int] = {}
+    new_keyed: dict[str, Node] = {}
+
+    for i, child in enumerate(old_children):
+        if isinstance(child, Node) and child.key is not None:
+            old_keyed[child.key] = child
+            old_positions[child.key] = i
+
+    for i, child in enumerate(new_children):
+        if isinstance(child, Node) and child.key is not None:
+            new_keyed[child.key] = child
+
+    used_old_positions: set[int] = set()
+
+    for new_index, new_child in enumerate(new_children):
+        child_path = f"{path}.{new_index}" if path else str(new_index)
+
+        if isinstance(new_child, Node) and new_child.key is not None:
+            key = new_child.key
+            if key in old_keyed:
+                old_child = old_keyed[key]
+                old_index = old_positions[key]
+                if old_index != new_index:
+                    operations.append(
+                        {
+                            "type": "move",
+                            "path": child_path,
+                            "data": {
+                                "from_index": old_index,
+                                "to_index": new_index,
+                                "key": key,
+                            },
+                        }
+                    )
+                used_old_positions.add(old_index)
+                operations.extend(diff_node(old_child, new_child, child_path))
+            else:
+                operations.append(
+                    {
+                        "type": "insert",
+                        "path": child_path,
+                        "data": _render_to_vdom(new_child, child_path),
+                    }
+                )
+        else:
+            # Unkeyed new element - try positional match
+            old_child_at_pos = (
+                old_children[new_index] if new_index < len(old_children) else None
+            )
+            if (
+                new_index < len(old_children)
+                and new_index not in used_old_positions
+                and not (
+                    isinstance(old_child_at_pos, Node)
+                    and old_child_at_pos.key is not None
+                )
+            ):
+                used_old_positions.add(new_index)
+                operations.extend(
+                    diff_node(old_children[new_index], new_child, child_path)
+                )
+            else:
+                operations.append(
+                    {
+                        "type": "insert",
+                        "path": child_path,
+                        "data": _render_to_vdom(new_child, child_path),
+                    }
+                )
+
+    # Remove old keyed elements that disappeared
+    for key, old_child in old_keyed.items():
+        if key not in new_keyed:
+            old_index = old_positions[key]
+            old_child_path = f"{path}.{old_index}" if path else str(old_index)
+            operations.append({"type": "remove", "path": old_child_path, "data": key})
+
+    # Remove leftover unkeyed olds
+    for old_index, old_child in enumerate(old_children):
+        if old_index not in used_old_positions and not (
+            isinstance(old_child, Node) and old_child.key is not None
+        ):
+            old_child_path = f"{path}.{old_index}" if path else str(old_index)
+            operations.append({"type": "remove", "path": old_child_path, "data": None})
+
+    return operations
+
+
+def _diff_positional_children(
+    old_children: Sequence[Element], new_children: Sequence[Element], path: str
+) -> list[VDOMOperation]:
+    operations: list[VDOMOperation] = []
+    max_len = max(len(old_children), len(new_children))
+
+    for i in range(max_len):
+        child_path = f"{path}.{i}" if path else str(i)
+        old_child = old_children[i] if i < len(old_children) else None
+        new_child = new_children[i] if i < len(new_children) else None
+
+        if old_child is not None and new_child is not None:
+            operations.extend(diff_node(old_child, new_child, child_path))
+        elif new_child is not None:
+            operations.append(
+                {
+                    "type": "insert",
+                    "path": child_path,
+                    "data": _render_to_vdom(new_child, child_path),
+                }
+            )
+        else:
+            operations.append({"type": "remove", "path": child_path, "data": None})
+
+    return operations

pulse/flags.py

@@ -0,0 +1,5 @@
+
+from contextvars import ContextVar
+
+
+IS_PRERENDERING: ContextVar[bool] = ContextVar("pulse_is_prerendering", default=False)

pulse/flatted.py

@@ -0,0 +1,159 @@
+"""
+Simple object transformation for socket.io transport
+Handles Dates, circular references, and basic Python objects
+"""
+
+from datetime import datetime
+from typing import Any, Dict
+
+
+def stringify(input_value: Any) -> Any:
+    """
+    Convert Python objects into a serializable format that handles circular references.
+
+    Args:
+        input_value: The object to serialize
+
+    Returns:
+        A JSON-serializable object with special markers for complex types
+    """
+    seen: Dict[int, int] = {}  # Map object id to assigned ID
+    next_id = 1
+
+    def transform(value: Any) -> Any:
+        nonlocal next_id
+
+        # Handle primitives
+        if value is None or isinstance(value, (int, float, str, bool)):
+            return value
+
+        # Handle objects that can have circular references
+        if isinstance(value, (dict, list, datetime)) or hasattr(value, "__dict__"):
+            obj_id = id(value)
+            if obj_id in seen:
+                return {"__ref": seen[obj_id]}
+
+        # Special type transformations
+        if isinstance(value, datetime):
+            current_id = next_id
+            next_id += 1
+            seen[id(value)] = current_id
+            # Type checker safety: we know value is datetime.datetime here
+            dt_value: datetime.datetime = value  # type: ignore
+            return {
+                "__pulse": "date",
+                "__id": current_id,
+                "timestamp": int(
+                    dt_value.timestamp() * 1000
+                ),  # Convert to milliseconds
+            }
+
+        # Handle lists
+        if isinstance(value, list):
+            current_id = next_id
+            next_id += 1
+            seen[id(value)] = current_id
+            return {
+                "__pulse": "array",
+                "__id": current_id,
+                "items": [transform(item) for item in value],
+            }
+
+        # Handle dictionaries
+        if isinstance(value, dict):
+            current_id = next_id
+            next_id += 1
+            seen[id(value)] = current_id
+
+            user_data = {}
+            for key, val in value.items():
+                if callable(val):
+                    continue  # Skip functions/methods
+                user_data[str(key)] = transform(val)
+
+            return {"__pulse": "object", "__id": current_id, "__data": user_data}
+
+        # Handle custom objects with __dict__
+        if hasattr(value, "__dict__"):
+            current_id = next_id
+            next_id += 1
+            seen[id(value)] = current_id
+
+            user_data = {}
+            for key, val in value.__dict__.items():
+                if callable(val) or key.startswith("_"):
+                    continue  # Skip private attributes and methods
+                user_data[str(key)] = transform(val)
+
+            return {"__pulse": "object", "__id": current_id, "__data": user_data}
+
+        # Fallback for unknown types - convert to string
+        return str(value)
+
+    return transform(input_value)
+
+
+def parse(input_value: Any) -> Any:
+    """
+    Parse serialized objects back into Python objects, resolving circular references.
+
+    Args:
+        input_value: The serialized object to parse
+
+    Returns:
+        The reconstructed Python object
+    """
+    objects: Dict[int, Any] = {}
+
+    def resolve(value: Any) -> Any:
+        if value is None or isinstance(value, (int, float, str, bool)):
+            return value
+
+        if isinstance(value, list):
+            return [resolve(item) for item in value]
+
+        if not isinstance(value, dict):
+            return value
+
+        obj = value
+
+        # Handle references
+        if "__ref" in obj:
+            ref_id = obj["__ref"]
+            return objects.get(ref_id)
+
+        # Handle special types (only if they have __pulse marker)
+        if obj.get("__pulse") == "date":
+            obj_id = obj["__id"]
+            timestamp_ms = obj["timestamp"]
+            resolved = datetime.fromtimestamp(timestamp_ms / 1000.0)
+            objects[obj_id] = resolved
+            return resolved
+
+        if obj.get("__pulse") == "array":
+            obj_id = obj["__id"]
+            resolved = []
+            objects[obj_id] = resolved
+
+            items = obj["items"]
+            for item in items:
+                resolved.append(resolve(item))
+            return resolved
+
+        if obj.get("__pulse") == "object":
+            obj_id = obj["__id"]
+            resolved = {}
+            objects[obj_id] = resolved
+
+            user_data = obj["__data"]
+            for key, val in user_data.items():
+                resolved[key] = resolve(val)
+            return resolved
+
+        # Unknown object type - process properties
+        result = {}
+        for key, val in obj.items():
+            result[key] = resolve(val)
+        return result
+
+    return resolve(input_value)

pulse/helpers.py

@@ -0,0 +1,27 @@
+from typing import Any, Callable, Coroutine, Iterable, TypeVar, TypeVarTuple, Unpack
+
+from pulse.vdom import Element
+
+
+Args = TypeVarTuple("Args")
+EventHandler = (
+    Callable[[], None]
+    | Callable[[], Coroutine[Any, Any, None]]
+    | Callable[[Unpack[Args]], None]
+    | Callable[[Unpack[Args]], Coroutine[Any, Any, None]]
+)
+
+
+class Sentinel:
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def __repr__(self) -> str:
+        return self.name
+
+
+T = TypeVar("T")
+
+
+def For(items: Iterable[T], fn: Callable[[T], Element]):
+    return [fn(item) for item in items]