feat(event): accept any sequence of events where a list of them is accepted (#7402)

* feat(event): accept any sequence of events where a list of them is accepted

* fix(app): read a page's on_load and the form on_submit events as any sequence

* perf(event): check the single event kinds before the Sequence ABC in from_event_type

* fix(internal): read the forms' on_submit sequence without the new helper, so the declared reflex floor still type-checks

* fix(internal): reject a string as the forms' on_submit events instead of splitting it into characters

* fix(event): split any sequence an event lambda returns into its events

call_event_fn only split a list or tuple, so a lambda returning another
sequence such as a UserList was wrapped as one event and rejected.

* refactor(event): share one fast check for a single event or a sequence

is_non_string_sequence checks list and tuple before the Sequence ABC, and
excludes bytes as well as str. _check_valid_yield uses it instead of its own
copy of the check.

from_event_type, fix_events and call_event_fn wrap a single event through
one _event_sequence helper. EventChain.create keeps its own branches, so a
bad top-level value still reports "Invalid event chain".

The demo and intro forms drop the string guard: the type already excludes
a str, and the event chain rejects one anyway.

Tests cover a handler that returns or yields a tuple through the event
processor, and which values count as a sequence.

* build(reflex): require the reflex-base that has is_non_string_sequence

reflex/app.py imports is_non_string_sequence, which reflex-base 0.10.0 lacks.

* Revert "build(reflex): require the reflex-base that has is_non_string_sequence"

pin-exact rewrites the reflex-base requirement to == <version> at build time, so
a released reflex never installs with an older reflex-base.

* feat(event): make event_sequence public and use it in the internal forms

The demo and intro forms turn their on_submit into a list of events with
reflex_base.event.event_sequence instead of their own isinstance check.

* build(internal): require the reflex that has event_sequence

The demo and intro forms import event_sequence, which reflex 0.10.0 and older lack.

---------

Co-authored-by: Farhan <www.mfarvirus@gmail.com>
Co-authored-by: Farhan Ali Raza <62690310+FarhanAliRaza@users.noreply.github.com>
Co-authored-by: Masen Furer <m_github@0x26.net>

Author: 3 people

news/+event-sequences.feature.md

@@ -0,0 +1 @@
+A page's `on_load` accepts any sequence of events, e.g. a tuple, like a list of them.

packages/reflex-base/news/+event-sequences.feature.md

@@ -0,0 +1 @@
+Event props and the events an event handler returns accept any sequence of events, e.g. a tuple or a variable typed `list[EventSpec]`, not only a list literal. The new `reflex_base.event.event_sequence` helper returns such a value as a sequence of events, wrapping a single event in a list.

packages/reflex-base/src/reflex_base/event/__init__.py

@@ -50,6 +50,7 @@
     ArgsSpec,
     GenericType,
     Unset,
+    is_non_string_sequence,
     is_optional,
     safe_issubclass,
     typehint_issubclass,
@@ -108,7 +109,7 @@ def state_cls(self) -> "type[BaseState]":
     @classmethod
     def from_event_type(
         cls,
-        events: "IndividualEventType | list[IndividualEventType] | None",
+        events: "IndividualEventType | Sequence[IndividualEventType] | None",
         *,
         router_data: dict[str, Any] | None = None,
     ) -> "list[Event]":
@@ -125,13 +126,9 @@ def from_event_type(
         if events is None:
             return []
 
-        # If the handler returns a single event, wrap it in a list.
-        if not isinstance(events, list):
-            events = [events]
-
         # Fix the events created by the handler.
         out = []
-        for e in events:
+        for e in event_sequence(events):
             if callable(e) and getattr(e, "__name__", "") == "<lambda>":
                 # A lambda was returned, assume the user wants to call it with no args.
                 e = e()
@@ -1025,7 +1022,7 @@ def create(
         events: list[EventSpec | EventVar | FunctionVar] = []
 
         # If the input is a list of event handlers, create an event chain.
-        if isinstance(value, list):
+        if is_non_string_sequence(value):
             for v in value:
                 if isinstance(v, (EventHandler, EventSpec)):
                     # Call the event handler to get the event.
@@ -2398,6 +2395,28 @@ def check_fn_match_arg_spec(
         raise EventFnArgMismatchError(msg)
 
 
+def event_sequence(events: Any) -> Sequence[Any]:
+    """Get events as a sequence, wrapping a single event-like value in a list.
+
+    A str or bytes value counts as a single value. The single event kinds are
+    checked first: they are the common case, and cheaper to check than the
+    Sequence ABC.
+
+    Args:
+        events: A single event-like value or a sequence of them.
+
+    Returns:
+        The events as a sequence.
+    """
+    if (
+        isinstance(events, (Event, EventSpec))
+        or callable(events)
+        or not is_non_string_sequence(events)
+    ):
+        return [events]
+    return events
+
+
 def call_event_fn(
     fn: Callable,
     arg_spec: ArgsSpec | Sequence[ArgsSpec],
@@ -2435,10 +2454,6 @@ def call_event_fn(
     # Call the function with the parsed args.
     out = fn(*[*parsed_args][:number_of_fn_args])
 
-    # Normalize common heterogeneous event collections into individual events
-    # while keeping other scalar values for validation below.
-    out = list(out) if isinstance(out, (list, tuple)) else [out]
-
     def _dispatch_mixed_event_var(event_like_var: Var) -> FunctionVar:
         """Wrap a mixed event-like Var into a callable frontend dispatcher.
 
@@ -2494,7 +2509,7 @@ def _dispatch_mixed_event_var(event_like_var: Var) -> FunctionVar:
 
     # Convert any event specs to event specs.
     events = []
-    for e in out:
+    for e in event_sequence(out):
         if isinstance(e, EventHandler):
             # An un-called EventHandler gets all of the args of the event trigger.
             e = call_event_handler(e, arg_spec, key=key)
@@ -2549,7 +2564,7 @@ def get_handler_args(
 
 
 def fix_events(
-    events: list[EventSpec | EventHandler] | None,
+    events: Sequence[EventSpec | EventHandler] | None,
     token: str | None = None,
     router_data: dict[str, Any] | None = None,
 ) -> list[Event]:
@@ -2580,13 +2595,9 @@ def fix_events(
     if events is None:
         return []
 
-    # If the handler returns a single event, wrap it in a list.
-    if not isinstance(events, list):
-        events = [events]
-
     # Fix the events created by the handler.
     out = []
-    for e in events:
+    for e in event_sequence(events):
         if callable(e) and getattr(e, "__name__", "") == "<lambda>":
             # A lambda was returned, assume the user wants to call it with no args.
             e = e()
@@ -3082,7 +3093,10 @@ def __call__(self, *args: Var) -> Any:
     type_params=(ARGS,),
 )
 
-ItemOrList = V | list[V]
+
+# A Sequence rather than a list: lists are invariant, so a `list[EventSpec]`
+# variable would not count as a list of every kind of event.
+ItemOrList = V | Sequence[V]
 
 BASIC_EVENT_TYPES = TypeAliasType(
     "BASIC_EVENT_TYPES", EventSpec | EventHandler | Var[Any], type_params=()
@@ -3156,6 +3170,7 @@ class EventNamespace:
     upload_files_chunk = upload_files_chunk
     stop_propagation = stop_propagation
     prevent_default = prevent_default
+    event_sequence = staticmethod(event_sequence)
 
     # Private/Internal Functions
     resolve_upload_handler_param = staticmethod(resolve_upload_handler_param)

packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py

@@ -26,6 +26,7 @@
 from reflex_base.utils.form import form_data_as_dict, transform_form_data
 from reflex_base.utils.format import format_event_handler
 from reflex_base.utils.serializers import deserializers
+from reflex_base.utils.types import is_non_string_sequence
 
 logger = logging.getLogger(__name__)
 
@@ -85,7 +86,7 @@ def _is_valid_type(events: Any) -> bool:
     if events is None or _is_valid_type(events):
         return events
 
-    if not (isinstance(events, Sequence) and not isinstance(events, (str, bytes))):
+    if not is_non_string_sequence(events):
         events = [events]
 
     try:

packages/reflex-base/src/reflex_base/utils/format.py

@@ -14,6 +14,7 @@
 
 from reflex_base import constants
 from reflex_base.utils import exceptions
+from reflex_base.utils.types import is_non_string_sequence
 
 if TYPE_CHECKING:
     from reflex_base.components.component import ComponentStyle
@@ -570,7 +571,7 @@ def _default_args_spec():
         arg_def = "()"
 
     payloads = []
-    if not isinstance(events, list):
+    if not is_non_string_sequence(events):
         events = [events]
 
     # Process each event/spec/lambda (similar to Component._create_event_chain).

packages/reflex-base/src/reflex_base/utils/types.py

@@ -40,7 +40,7 @@
 from typing import get_type_hints as get_type_hints_og
 
 import typing_extensions
-from typing_extensions import TypeAliasType, TypeVarTuple
+from typing_extensions import TypeAliasType, TypeIs, TypeVarTuple
 from typing_extensions import override as override
 
 from reflex_base import constants
@@ -572,6 +572,25 @@ def is_none(cls: GenericType) -> bool:
     return cls is type(None) or cls is None
 
 
+def is_non_string_sequence(value: object) -> TypeIs[Sequence[Any]]:
+    """Check if a value is a sequence other than a str or bytes, e.g. a list of events.
+
+    Separate list and tuple checks come first: they are the common case, and
+    cheaper than the Sequence ABC check.
+
+    Args:
+        value: The value to check.
+
+    Returns:
+        Whether the value is a sequence and not a str or bytes.
+    """
+    return (
+        isinstance(value, list)  # noqa: SIM101 - a lone list check is the fastest
+        or isinstance(value, tuple)
+        or (isinstance(value, Sequence) and not isinstance(value, (str, bytes)))
+    )
+
+
 def is_union(cls: GenericType) -> bool:
     """Check if a class is a Union.
 

packages/reflex-components-internal/news/+event-sequences.feature.md

@@ -0,0 +1 @@
+The demo and intro forms take any sequence of `on_submit` events, e.g. a tuple, like a list of them.

packages/reflex-components-internal/pyproject.toml

@@ -16,7 +16,7 @@ classifiers = [
     "Programming Language :: Python :: 3.15",
 ]
 dependencies = [
-    "reflex >= 0.9.4",
+    "reflex >= 0.10.1.dev0",
 ]
 
 [tool.hatch.version]

packages/reflex-components-internal/src/reflex_components_internal/blocks/demo_form.py

@@ -8,7 +8,7 @@
 from typing import Any
 
 import reflex as rx
-from reflex.event import EventType
+from reflex.event import EventType, event_sequence
 from reflex.experimental.client_state import ClientStateVar
 from reflex.vars.base import get_unique_variable_name
 from reflex_components_internal.blocks.telemetry.posthog import (
@@ -315,9 +315,7 @@ def _demo_form(
     """
     prefix = id_prefix or get_unique_variable_name()
     email_id = f"{prefix}_user_email"
-    extra_on_submit = (
-        on_submit if isinstance(on_submit, list) else [on_submit] if on_submit else []
-    )
+    extra_on_submit = event_sequence(on_submit) if on_submit is not None else []
     fields = (
         rx.el.div(
             input_field("First name", "John", "first_name", "text", True),

packages/reflex-components-internal/src/reflex_components_internal/blocks/intro_form.py

@@ -6,7 +6,7 @@
 from typing import Any
 
 import reflex as rx
-from reflex.event import EventType, IndividualEventType
+from reflex.event import EventType, event_sequence
 from reflex.experimental.client_state import ClientStateVar
 from reflex.vars.base import get_unique_variable_name
 from reflex_components_internal.blocks.telemetry.posthog import (
@@ -292,9 +292,7 @@ def intro_form(
     prefix = id_prefix or get_unique_variable_name()
     email_id = f"{prefix}_user_email"
 
-    extra: list[IndividualEventType[dict[str, Any]]] = (
-        on_submit if isinstance(on_submit, list) else [on_submit] if on_submit else []
-    )
+    extra = event_sequence(on_submit) if on_submit is not None else []
 
     form = rx.el.form(
         rx.el.div(