reflex 0.6.4a3__py3-none-any.whl → 0.6.5__py3-none-any.whl

reflex/event.py

@@ -10,6 +10,7 @@ import urllib.parse
 from base64 import b64encode
 from functools import partial
 from typing import (
+    TYPE_CHECKING,
     Any,
     Callable,
     Dict,
@@ -19,25 +20,32 @@ from typing import (
     Sequence,
     Tuple,
     Type,
-    TypeVar,
     Union,
     get_type_hints,
     overload,
 )
 
-from typing_extensions import ParamSpec, Protocol, get_args, get_origin
+from typing_extensions import (
+    Concatenate,
+    ParamSpec,
+    Protocol,
+    TypeAliasType,
+    TypedDict,
+    TypeVar,
+    get_args,
+    get_origin,
+)
 
 from reflex import constants
+from reflex.constants.state import FRONTEND_EVENT_STATE
 from reflex.utils import console, format
-from reflex.utils.exceptions import EventFnArgMismatch, EventHandlerArgMismatch
-from reflex.utils.types import ArgsSpec, GenericType
+from reflex.utils.exceptions import EventFnArgMismatch, EventHandlerArgTypeMismatch
+from reflex.utils.types import ArgsSpec, GenericType, typehint_issubclass
 from reflex.vars import VarData
-from reflex.vars.base import (
-    LiteralVar,
-    Var,
-)
+from reflex.vars.base import LiteralVar, Var
 from reflex.vars.function import (
     ArgsFunctionOperation,
+    FunctionArgs,
     FunctionStringVar,
     FunctionVar,
     VarOperationCall,
@@ -83,7 +91,7 @@ class Event:
 BACKGROUND_TASK_MARKER = "_reflex_background_task"
 
 
-def background(fn):
+def background(fn, *, __internal_reflex_call: bool = False):
     """Decorator to mark event handler as running in the background.
 
     Args:
@@ -96,6 +104,13 @@ def background(fn):
     Raises:
         TypeError: If the function is not a coroutine function or async generator.
     """
+    if not __internal_reflex_call:
+        console.deprecate(
+            "background-decorator",
+            "Use `rx.event(background=True)` instead.",
+            "0.6.5",
+            "0.7.0",
+        )
     if not inspect.iscoroutinefunction(fn) and not inspect.isasyncgenfunction(fn):
         raise TypeError("Background task must be async function or generator.")
     setattr(fn, BACKGROUND_TASK_MARKER, True)
@@ -394,7 +409,9 @@ class EventChain(EventActionsMixin):
         default_factory=list
     )
 
-    args_spec: Optional[Callable] = dataclasses.field(default=None)
+    args_spec: Optional[Union[Callable, Sequence[Callable]]] = dataclasses.field(
+        default=None
+    )
 
     invocation: Optional[Var] = dataclasses.field(default=None)
 
@@ -427,6 +444,10 @@ class JavasciptKeyboardEvent:
     """Interface for a Javascript KeyboardEvent https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent."""
 
     key: str = ""
+    altKey: bool = False
+    ctrlKey: bool = False
+    metaKey: bool = False
+    shiftKey: bool = False
 
 
 def input_event(e: Var[JavascriptInputEvent]) -> Tuple[Var[str]]:
@@ -441,7 +462,16 @@ def input_event(e: Var[JavascriptInputEvent]) -> Tuple[Var[str]]:
     return (e.target.value,)
 
 
-def key_event(e: Var[JavasciptKeyboardEvent]) -> Tuple[Var[str]]:
+class KeyInputInfo(TypedDict):
+    """Information about a key input event."""
+
+    alt_key: bool
+    ctrl_key: bool
+    meta_key: bool
+    shift_key: bool
+
+
+def key_event(e: Var[JavasciptKeyboardEvent]) -> Tuple[Var[str], Var[KeyInputInfo]]:
     """Get the key from a keyboard event.
 
     Args:
@@ -450,10 +480,20 @@ def key_event(e: Var[JavasciptKeyboardEvent]) -> Tuple[Var[str]]:
     Returns:
         The key from the keyboard event.
     """
-    return (e.key,)
+    return (
+        e.key,
+        Var.create(
+            {
+                "alt_key": e.altKey,
+                "ctrl_key": e.ctrlKey,
+                "meta_key": e.metaKey,
+                "shift_key": e.shiftKey,
+            },
+        ),
+    )
 
 
-def empty_event() -> Tuple[()]:
+def no_args_event_spec() -> Tuple[()]:
     """Empty event handler.
 
     Returns:
@@ -463,43 +503,14 @@ def empty_event() -> Tuple[()]:
 
 
 # These chains can be used for their side effects when no other events are desired.
-stop_propagation = EventChain(events=[], args_spec=empty_event).stop_propagation
-prevent_default = EventChain(events=[], args_spec=empty_event).prevent_default
+stop_propagation = EventChain(events=[], args_spec=no_args_event_spec).stop_propagation
+prevent_default = EventChain(events=[], args_spec=no_args_event_spec).prevent_default
 
 
 T = TypeVar("T")
 U = TypeVar("U")
 
 
-# def identity_event(event_type: Type[T]) -> Callable[[Var[T]], Tuple[Var[T]]]:
-#     """A helper function that returns the input event as output.
-
-#     Args:
-#         event_type: The type of the event.
-
-#     Returns:
-#         A function that returns the input event as output.
-#     """
-
-#     def inner(ev: Var[T]) -> Tuple[Var[T]]:
-#         return (ev,)
-
-#     inner.__signature__ = inspect.signature(inner).replace(  # type: ignore
-#         parameters=[
-#             inspect.Parameter(
-#                 "ev",
-#                 kind=inspect.Parameter.POSITIONAL_OR_KEYWORD,
-#                 annotation=Var[event_type],
-#             )
-#         ],
-#         return_annotation=Tuple[Var[event_type]],
-#     )
-#     inner.__annotations__["ev"] = Var[event_type]
-#     inner.__annotations__["return"] = Tuple[Var[event_type]]
-
-#     return inner
-
-
 class IdentityEventReturn(Generic[T], Protocol):
     """Protocol for an identity event return."""
 
@@ -516,20 +527,22 @@ class IdentityEventReturn(Generic[T], Protocol):
 
 
 @overload
-def identity_event(event_type: Type[T], /) -> Callable[[Var[T]], Tuple[Var[T]]]: ...  # type: ignore
+def passthrough_event_spec(
+    event_type: Type[T], /
+) -> Callable[[Var[T]], Tuple[Var[T]]]: ...  # type: ignore
 
 
 @overload
-def identity_event(
+def passthrough_event_spec(
     event_type_1: Type[T], event_type2: Type[U], /
 ) -> Callable[[Var[T], Var[U]], Tuple[Var[T], Var[U]]]: ...
 
 
 @overload
-def identity_event(*event_types: Type[T]) -> IdentityEventReturn[T]: ...
+def passthrough_event_spec(*event_types: Type[T]) -> IdentityEventReturn[T]: ...
 
 
-def identity_event(*event_types: Type[T]) -> IdentityEventReturn[T]:  # type: ignore
+def passthrough_event_spec(*event_types: Type[T]) -> IdentityEventReturn[T]:  # type: ignore
     """A helper function that returns the input event as output.
 
     Args:
@@ -676,7 +689,7 @@ def server_side(name: str, sig: inspect.Signature, **kwargs) -> EventSpec:
     fn.__qualname__ = name
     fn.__signature__ = sig
     return EventSpec(
-        handler=EventHandler(fn=fn),
+        handler=EventHandler(fn=fn, state_full_name=FRONTEND_EVENT_STATE),
         args=tuple(
             (
                 Var(_js_expr=k),
@@ -720,7 +733,16 @@ def console_log(message: str | Var[str]) -> EventSpec:
     Returns:
         An event to log the message.
     """
-    return server_side("_console", get_fn_signature(console_log), message=message)
+    return run_script(Var("console").to(dict).log.to(FunctionVar).call(message))
+
+
+def noop() -> EventSpec:
+    """Do nothing.
+
+    Returns:
+        An event to do nothing.
+    """
+    return run_script(Var.create(None))
 
 
 def back() -> EventSpec:
@@ -729,7 +751,9 @@ def back() -> EventSpec:
     Returns:
         An event to go back one page.
     """
-    return call_script("window.history.back()")
+    return run_script(
+        Var("window").to(dict).history.to(dict).back.to(FunctionVar).call()
+    )
 
 
 def window_alert(message: str | Var[str]) -> EventSpec:
@@ -741,7 +765,7 @@ def window_alert(message: str | Var[str]) -> EventSpec:
     Returns:
         An event to alert the message.
     """
-    return server_side("_alert", get_fn_signature(window_alert), message=message)
+    return run_script(Var("window").to(dict).alert.to(FunctionVar).call(message))
 
 
 def set_focus(ref: str) -> EventSpec:
@@ -760,18 +784,25 @@ def set_focus(ref: str) -> EventSpec:
     )
 
 
-def scroll_to(elem_id: str) -> EventSpec:
+def scroll_to(elem_id: str, align_to_top: bool | Var[bool] = True) -> EventSpec:
     """Select the id of a html element for scrolling into view.
 
     Args:
-        elem_id: the id of the element
+        elem_id: The id of the element to scroll to.
+        align_to_top: Whether to scroll to the top (True) or bottom (False) of the element.
 
     Returns:
         An EventSpec to scroll the page to the selected element.
     """
-    js_code = f"document.getElementById('{elem_id}').scrollIntoView();"
-
-    return call_script(js_code)
+    get_element_by_id = FunctionStringVar.create("document.getElementById")
+
+    return run_script(
+        get_element_by_id(elem_id)
+        .call(elem_id)
+        .to(ObjectVar)
+        .scrollIntoView.to(FunctionVar)
+        .call(align_to_top),
+    )
 
 
 def set_value(ref: str, value: Any) -> EventSpec:
@@ -877,10 +908,12 @@ def set_clipboard(content: str) -> EventSpec:
     Returns:
         EventSpec: An event to set some content in the clipboard.
     """
-    return server_side(
-        "_set_clipboard",
-        get_fn_signature(set_clipboard),
-        content=content,
+    return run_script(
+        Var("navigator")
+        .to(dict)
+        .clipboard.to(dict)
+        .writeText.to(FunctionVar)
+        .call(content)
     )
 
 
@@ -967,13 +1000,7 @@ def _callback_arg_spec(eval_result):
 
 def call_script(
     javascript_code: str | Var[str],
-    callback: (
-        EventSpec
-        | EventHandler
-        | Callable
-        | List[EventSpec | EventHandler | Callable]
-        | None
-    ) = None,
+    callback: EventType | None = None,
 ) -> EventSpec:
     """Create an event handler that executes arbitrary javascript code.
 
@@ -987,12 +1014,10 @@ def call_script(
     callback_kwargs = {}
     if callback is not None:
         callback_kwargs = {
-            "callback": str(
-                format.format_queue_events(
-                    callback,
-                    args_spec=lambda result: [result],
-                ),
-            ),
+            "callback": format.format_queue_events(
+                callback,
+                args_spec=lambda result: [result],
+            )._js_expr,
         }
     if isinstance(javascript_code, str):
         # When there is VarData, include it and eval the JS code inline on the client.
@@ -1012,6 +1037,62 @@ def call_script(
     )
 
 
+def call_function(
+    javascript_code: str | Var,
+    callback: EventType | None = None,
+) -> EventSpec:
+    """Create an event handler that executes arbitrary javascript code.
+
+    Args:
+        javascript_code: The code to execute.
+        callback: EventHandler that will receive the result of evaluating the javascript code.
+
+    Returns:
+        EventSpec: An event that will execute the client side javascript.
+    """
+    callback_kwargs = {}
+    if callback is not None:
+        callback_kwargs = {
+            "callback": format.format_queue_events(
+                callback,
+                args_spec=lambda result: [result],
+            ),
+        }
+
+    javascript_code = (
+        Var(javascript_code) if isinstance(javascript_code, str) else javascript_code
+    )
+
+    return server_side(
+        "_call_function",
+        get_fn_signature(call_function),
+        function=javascript_code,
+        **callback_kwargs,
+    )
+
+
+def run_script(
+    javascript_code: str | Var,
+    callback: EventType | None = None,
+) -> EventSpec:
+    """Create an event handler that executes arbitrary javascript code.
+
+    Args:
+        javascript_code: The code to execute.
+        callback: EventHandler that will receive the result of evaluating the javascript code.
+
+    Returns:
+        EventSpec: An event that will execute the client side javascript.
+    """
+    javascript_code = (
+        Var(javascript_code) if isinstance(javascript_code, str) else javascript_code
+    )
+
+    return call_function(
+        ArgsFunctionOperation.create(tuple(), javascript_code), callback
+    )
+
+
 def get_event(state, event):
     """Get the event from the given state.
 
@@ -1038,8 +1119,9 @@ def get_hydrate_event(state) -> str:
 
 
 def call_event_handler(
-    event_handler: EventHandler | EventSpec,
-    arg_spec: ArgsSpec,
+    event_callback: EventHandler | EventSpec,
+    event_spec: ArgsSpec | Sequence[ArgsSpec],
+    key: Optional[str] = None,
 ) -> EventSpec:
     """Call an event handler to get the event spec.
 
@@ -1048,33 +1130,135 @@ def call_event_handler(
     Otherwise, the event handler will be called with no args.
 
     Args:
-        event_handler: The event handler.
-        arg_spec: The lambda that define the argument(s) to pass to the event handler.
-
-    Raises:
-        EventHandlerArgMismatch: if number of arguments expected by event_handler doesn't match the spec.
+        event_callback: The event handler.
+        event_spec: The lambda that define the argument(s) to pass to the event handler.
+        key: The key to pass to the event handler.
 
     Returns:
         The event spec from calling the event handler.
-    """
-    parsed_args = parse_args_spec(arg_spec)  # type: ignore
 
-    if isinstance(event_handler, EventSpec):
+    # noqa: DAR401 failure
+
+    """
+    event_spec_args = parse_args_spec(event_spec)  # type: ignore
+
+    if isinstance(event_callback, EventSpec):
+        check_fn_match_arg_spec(
+            event_callback.handler.fn,
+            event_spec,
+            key,
+            bool(event_callback.handler.state_full_name) + len(event_callback.args),
+            event_callback.handler.fn.__qualname__,
+        )
         # Handle partial application of EventSpec args
-        return event_handler.add_args(*parsed_args)
-
-    args = inspect.getfullargspec(event_handler.fn).args
-    n_args = len(args) - 1  # subtract 1 for bound self arg
-    if n_args == len(parsed_args):
-        return event_handler(*parsed_args)  # type: ignore
-    else:
-        raise EventHandlerArgMismatch(
-            "The number of arguments accepted by "
-            f"{event_handler.fn.__qualname__} ({n_args}) "
-            "does not match the arguments passed by the event trigger: "
-            f"{[str(v) for v in parsed_args]}\n"
-            "See https://reflex.dev/docs/events/event-arguments/"
+        return event_callback.add_args(*event_spec_args)
+
+    check_fn_match_arg_spec(
+        event_callback.fn,
+        event_spec,
+        key,
+        bool(event_callback.state_full_name),
+        event_callback.fn.__qualname__,
+    )
+
+    all_acceptable_specs = (
+        [event_spec] if not isinstance(event_spec, Sequence) else event_spec
+    )
+
+    event_spec_return_types = list(
+        filter(
+            lambda event_spec_return_type: event_spec_return_type is not None
+            and get_origin(event_spec_return_type) is tuple,
+            (
+                get_type_hints(arg_spec).get("return", None)
+                for arg_spec in all_acceptable_specs
+            ),
         )
+    )
+
+    if event_spec_return_types:
+        failures = []
+
+        event_callback_spec = inspect.getfullargspec(event_callback.fn)
+
+        for event_spec_index, event_spec_return_type in enumerate(
+            event_spec_return_types
+        ):
+            args = get_args(event_spec_return_type)
+
+            args_types_without_vars = [
+                arg if get_origin(arg) is not Var else get_args(arg)[0] for arg in args
+            ]
+
+            try:
+                type_hints_of_provided_callback = get_type_hints(event_callback.fn)
+            except NameError:
+                type_hints_of_provided_callback = {}
+
+            failed_type_check = False
+
+            # check that args of event handler are matching the spec if type hints are provided
+            for i, arg in enumerate(event_callback_spec.args[1:]):
+                if arg not in type_hints_of_provided_callback:
+                    continue
+
+                try:
+                    compare_result = typehint_issubclass(
+                        args_types_without_vars[i], type_hints_of_provided_callback[arg]
+                    )
+                except TypeError:
+                    # TODO: In 0.7.0, remove this block and raise the exception
+                    # raise TypeError(
+                    #     f"Could not compare types {args_types_without_vars[i]} and {type_hints_of_provided_callback[arg]} for argument {arg} of {event_handler.fn.__qualname__} provided for {key}."
+                    # ) from e
+                    console.warn(
+                        f"Could not compare types {args_types_without_vars[i]} and {type_hints_of_provided_callback[arg]} for argument {arg} of {event_callback.fn.__qualname__} provided for {key}."
+                    )
+                    compare_result = False
+
+                if compare_result:
+                    continue
+                else:
+                    failure = EventHandlerArgTypeMismatch(
+                        f"Event handler {key} expects {args_types_without_vars[i]} for argument {arg} but got {type_hints_of_provided_callback[arg]} as annotated in {event_callback.fn.__qualname__} instead."
+                    )
+                    failures.append(failure)
+                    failed_type_check = True
+                    break
+
+            if not failed_type_check:
+                if event_spec_index:
+                    args = get_args(event_spec_return_types[0])
+
+                    args_types_without_vars = [
+                        arg if get_origin(arg) is not Var else get_args(arg)[0]
+                        for arg in args
+                    ]
+
+                    expect_string = ", ".join(
+                        repr(arg) for arg in args_types_without_vars
+                    ).replace("[", "\\[")
+
+                    given_string = ", ".join(
+                        repr(type_hints_of_provided_callback.get(arg, Any))
+                        for arg in event_callback_spec.args[1:]
+                    ).replace("[", "\\[")
+
+                    console.warn(
+                        f"Event handler {key} expects ({expect_string}) -> () but got ({given_string}) -> () as annotated in {event_callback.fn.__qualname__} instead. "
+                        f"This may lead to unexpected behavior but is intentionally ignored for {key}."
+                    )
+                return event_callback(*event_spec_args)
+
+        if failures:
+            console.deprecate(
+                "Mismatched event handler argument types",
+                "\n".join([str(f) for f in failures]),
+                "0.6.5",
+                "0.7.0",
+            )
+
+    return event_callback(*event_spec_args)  # type: ignore
 
 
 def unwrap_var_annotation(annotation: GenericType):
@@ -1114,7 +1298,7 @@ def resolve_annotation(annotations: dict[str, Any], arg_name: str):
     return annotation
 
 
-def parse_args_spec(arg_spec: ArgsSpec):
+def parse_args_spec(arg_spec: ArgsSpec | Sequence[ArgsSpec]):
     """Parse the args provided in the ArgsSpec of an event trigger.
 
     Args:
@@ -1123,6 +1307,8 @@ def parse_args_spec(arg_spec: ArgsSpec):
     Returns:
         The parsed args.
     """
+    # if there's multiple, the first is the default
+    arg_spec = arg_spec[0] if isinstance(arg_spec, Sequence) else arg_spec
     spec = inspect.getfullargspec(arg_spec)
     annotations = get_type_hints(arg_spec)
 
@@ -1138,39 +1324,49 @@ def parse_args_spec(arg_spec: ArgsSpec):
     )
 
 
-def check_fn_match_arg_spec(fn: Callable, arg_spec: ArgsSpec) -> List[Var]:
+def check_fn_match_arg_spec(
+    user_func: Callable,
+    arg_spec: ArgsSpec | Sequence[ArgsSpec],
+    key: str | None = None,
+    number_of_bound_args: int = 0,
+    func_name: str | None = None,
+):
     """Ensures that the function signature matches the passed argument specification
     or raises an EventFnArgMismatch if they do not.
 
     Args:
-        fn: The function to be validated.
+        user_func: The function to be validated.
         arg_spec: The argument specification for the event trigger.
-
-    Returns:
-        The parsed arguments from the argument specification.
+        key: The key of the event trigger.
+        number_of_bound_args: The number of bound arguments to the function.
+        func_name: The name of the function to be validated.
 
     Raises:
         EventFnArgMismatch: Raised if the number of mandatory arguments do not match
     """
-    fn_args = inspect.getfullargspec(fn).args
-    fn_defaults_args = inspect.getfullargspec(fn).defaults
-    n_fn_args = len(fn_args)
-    n_fn_defaults_args = len(fn_defaults_args) if fn_defaults_args else 0
-    if isinstance(fn, types.MethodType):
-        n_fn_args -= 1  # subtract 1 for bound self arg
-    parsed_args = parse_args_spec(arg_spec)
-    if not (n_fn_args - n_fn_defaults_args <= len(parsed_args) <= n_fn_args):
+    user_args = inspect.getfullargspec(user_func).args
+    user_default_args = inspect.getfullargspec(user_func).defaults
+    number_of_user_args = len(user_args) - number_of_bound_args
+    number_of_user_default_args = len(user_default_args) if user_default_args else 0
+
+    parsed_event_args = parse_args_spec(arg_spec)
+
+    number_of_event_args = len(parsed_event_args)
+
+    if number_of_user_args - number_of_user_default_args > number_of_event_args:
         raise EventFnArgMismatch(
-            "The number of mandatory arguments accepted by "
-            f"{fn} ({n_fn_args - n_fn_defaults_args}) "
-            "does not match the arguments passed by the event trigger: "
-            f"{[str(v) for v in parsed_args]}\n"
+            f"Event {key} only provides {number_of_event_args} arguments, but "
+            f"{func_name or user_func} requires at least {number_of_user_args - number_of_user_default_args} "
+            "arguments to be passed to the event handler.\n"
             "See https://reflex.dev/docs/events/event-arguments/"
         )
-    return parsed_args
 
 
-def call_event_fn(fn: Callable, arg_spec: ArgsSpec) -> list[EventSpec] | Var:
+def call_event_fn(
+    fn: Callable,
+    arg_spec: ArgsSpec | Sequence[ArgsSpec],
+    key: Optional[str] = None,
+) -> list[EventSpec] | Var:
     """Call a function to a list of event specs.
 
     The function should return a single EventSpec, a list of EventSpecs, or a
@@ -1179,6 +1375,7 @@ def call_event_fn(fn: Callable, arg_spec: ArgsSpec) -> list[EventSpec] | Var:
     Args:
         fn: The function to call.
         arg_spec: The argument spec for the event trigger.
+        key: The key to pass to the event handler.
 
     Returns:
         The event specs from calling the function or a Var.
@@ -1191,10 +1388,14 @@ def call_event_fn(fn: Callable, arg_spec: ArgsSpec) -> list[EventSpec] | Var:
     from reflex.utils.exceptions import EventHandlerValueError
 
     # Check that fn signature matches arg_spec
-    parsed_args = check_fn_match_arg_spec(fn, arg_spec)
+    check_fn_match_arg_spec(fn, arg_spec, key=key)
+
+    parsed_args = parse_args_spec(arg_spec)
+
+    number_of_fn_args = len(inspect.getfullargspec(fn).args)
 
     # Call the function with the parsed args.
-    out = fn(*parsed_args)
+    out = fn(*[*parsed_args][:number_of_fn_args])
 
     # If the function returns a Var, assume it's an EventChain and render it directly.
     if isinstance(out, Var):
@@ -1209,7 +1410,7 @@ def call_event_fn(fn: Callable, arg_spec: ArgsSpec) -> list[EventSpec] | Var:
     for e in 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)
+            e = call_event_handler(e, arg_spec, key=key)
 
         # Make sure the event spec is valid.
         if not isinstance(e, EventSpec):
@@ -1313,7 +1514,7 @@ def get_fn_signature(fn: Callable) -> inspect.Signature:
     """
     signature = inspect.signature(fn)
     new_param = inspect.Parameter(
-        "state", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=Any
+        FRONTEND_EVENT_STATE, inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=Any
     )
     return signature.replace(parameters=(new_param, *signature.parameters.values()))
 
@@ -1419,7 +1620,12 @@ class LiteralEventChainVar(ArgsFunctionOperation, LiteralVar, EventChainVar):
         Returns:
             The created LiteralEventChainVar instance.
         """
-        sig = inspect.signature(value.args_spec)  # type: ignore
+        arg_spec = (
+            value.args_spec[0]
+            if isinstance(value.args_spec, Sequence)
+            else value.args_spec
+        )
+        sig = inspect.signature(arg_spec)  # type: ignore
         if sig.parameters:
             arg_def = tuple((f"_{p}" for p in sig.parameters))
             arg_def_expr = LiteralVar.create([Var(_js_expr=arg) for arg in arg_def])
@@ -1438,7 +1644,7 @@ class LiteralEventChainVar(ArgsFunctionOperation, LiteralVar, EventChainVar):
             _js_expr="",
             _var_type=EventChain,
             _var_data=_var_data,
-            _args_names=arg_def,
+            _args=FunctionArgs(arg_def),
             _return_expr=invocation.call(
                 LiteralVar.create([LiteralVar.create(event) for event in value.events]),
                 arg_def_expr,
@@ -1457,142 +1663,134 @@ V3 = TypeVar("V3")
 V4 = TypeVar("V4")
 V5 = TypeVar("V5")
 
-if sys.version_info >= (3, 10):
-    from typing import Concatenate
-
-    class EventCallback(Generic[P, T]):
-        """A descriptor that wraps a function to be used as an event."""
-
-        def __init__(self, func: Callable[Concatenate[Any, P], T]):
-            """Initialize the descriptor with the function to be wrapped.
-
-            Args:
-                func: The function to be wrapped.
-            """
-            self.func = func
-
-        @property
-        def prevent_default(self):
-            """Prevent default behavior.
-
-            Returns:
-                The event callback with prevent default behavior.
-            """
-            return self
-
-        @property
-        def stop_propagation(self):
-            """Stop event propagation.
-
-            Returns:
-                The event callback with stop propagation behavior.
-            """
-            return self
-
-        @overload
-        def __call__(
-            self: EventCallback[Q, T],
-        ) -> EventCallback[Q, T]: ...
-
-        @overload
-        def __call__(
-            self: EventCallback[Concatenate[V, Q], T], value: V | Var[V]
-        ) -> EventCallback[Q, T]: ...
-
-        @overload
-        def __call__(
-            self: EventCallback[Concatenate[V, V2, Q], T],
-            value: V | Var[V],
-            value2: V2 | Var[V2],
-        ) -> EventCallback[Q, T]: ...
-
-        @overload
-        def __call__(
-            self: EventCallback[Concatenate[V, V2, V3, Q], T],
-            value: V | Var[V],
-            value2: V2 | Var[V2],
-            value3: V3 | Var[V3],
-        ) -> EventCallback[Q, T]: ...
-
-        @overload
-        def __call__(
-            self: EventCallback[Concatenate[V, V2, V3, V4, Q], T],
-            value: V | Var[V],
-            value2: V2 | Var[V2],
-            value3: V3 | Var[V3],
-            value4: V4 | Var[V4],
-        ) -> EventCallback[Q, T]: ...
-
-        def __call__(self, *values) -> EventCallback:  # type: ignore
-            """Call the function with the values.
-
-            Args:
-                *values: The values to call the function with.
-
-            Returns:
-                The function with the values.
-            """
-            return self.func(*values)  # type: ignore
-
-        @overload
-        def __get__(
-            self: EventCallback[P, T], instance: None, owner
-        ) -> EventCallback[P, T]: ...
-
-        @overload
-        def __get__(self, instance, owner) -> Callable[P, T]: ...
-
-        def __get__(self, instance, owner) -> Callable:  # type: ignore
-            """Get the function with the instance bound to it.
-
-            Args:
-                instance: The instance to bind to the function.
-                owner: The owner of the function.
-
-            Returns:
-                The function with the instance bound to it
-            """
-            if instance is None:
-                return self.func  # type: ignore
-
-            return partial(self.func, instance)  # type: ignore
-
-    def event_handler(func: Callable[Concatenate[Any, P], T]) -> EventCallback[P, T]:
-        """Wrap a function to be used as an event.
+background_event_decorator = background
+
+
+class EventCallback(Generic[P, T]):
+    """A descriptor that wraps a function to be used as an event."""
+
+    def __init__(self, func: Callable[Concatenate[Any, P], T]):
+        """Initialize the descriptor with the function to be wrapped.
 
         Args:
-            func: The function to wrap.
+            func: The function to be wrapped.
+        """
+        self.func = func
+
+    @property
+    def prevent_default(self):
+        """Prevent default behavior.
 
         Returns:
-            The wrapped function.
+            The event callback with prevent default behavior.
         """
-        return func  # type: ignore
-else:
+        return self
 
-    class EventCallback(Generic[P, T]):
-        """A descriptor that wraps a function to be used as an event."""
+    @property
+    def stop_propagation(self):
+        """Stop event propagation.
 
-    def event_handler(func: Callable[P, T]) -> Callable[P, T]:
-        """Wrap a function to be used as an event.
+        Returns:
+            The event callback with stop propagation behavior.
+        """
+        return self
+
+    @overload
+    def __call__(
+        self: EventCallback[Q, T],
+    ) -> EventCallback[Q, T]: ...
+
+    @overload
+    def __call__(
+        self: EventCallback[Concatenate[V, Q], T], value: V | Var[V]
+    ) -> EventCallback[Q, T]: ...
+
+    @overload
+    def __call__(
+        self: EventCallback[Concatenate[V, V2, Q], T],
+        value: V | Var[V],
+        value2: V2 | Var[V2],
+    ) -> EventCallback[Q, T]: ...
+
+    @overload
+    def __call__(
+        self: EventCallback[Concatenate[V, V2, V3, Q], T],
+        value: V | Var[V],
+        value2: V2 | Var[V2],
+        value3: V3 | Var[V3],
+    ) -> EventCallback[Q, T]: ...
+
+    @overload
+    def __call__(
+        self: EventCallback[Concatenate[V, V2, V3, V4, Q], T],
+        value: V | Var[V],
+        value2: V2 | Var[V2],
+        value3: V3 | Var[V3],
+        value4: V4 | Var[V4],
+    ) -> EventCallback[Q, T]: ...
+
+    def __call__(self, *values) -> EventCallback:  # type: ignore
+        """Call the function with the values.
 
         Args:
-            func: The function to wrap.
+            *values: The values to call the function with.
 
         Returns:
-            The wrapped function.
+            The function with the values.
+        """
+        return self.func(*values)  # type: ignore
+
+    @overload
+    def __get__(
+        self: EventCallback[P, T], instance: None, owner
+    ) -> EventCallback[P, T]: ...
+
+    @overload
+    def __get__(self, instance, owner) -> Callable[P, T]: ...
+
+    def __get__(self, instance, owner) -> Callable:  # type: ignore
+        """Get the function with the instance bound to it.
+
+        Args:
+            instance: The instance to bind to the function.
+            owner: The owner of the function.
+
+        Returns:
+            The function with the instance bound to it
         """
-        return func
+        if instance is None:
+            return self.func  # type: ignore
+
+        return partial(self.func, instance)  # type: ignore
 
 
 G = ParamSpec("G")
 
+if TYPE_CHECKING:
+    from reflex.state import BaseState
+
+    BASE_STATE = TypeVar("BASE_STATE", bound=BaseState)
+else:
+    BASE_STATE = TypeVar("BASE_STATE")
+
+StateCallable = TypeAliasType(
+    "StateCallable",
+    Callable[Concatenate[BASE_STATE, G], Any],
+    type_params=(G, BASE_STATE),
+)
+
 IndividualEventType = Union[
-    EventSpec, EventHandler, Callable[G, Any], EventCallback[G, Any], Var[Any]
+    EventSpec,
+    EventHandler,
+    Callable[G, Any],
+    StateCallable[G, BASE_STATE],
+    EventCallback[G, Any],
+    Var[Any],
 ]
 
 ItemOrList = Union[V, List[V]]
 
-EventType = ItemOrList[IndividualEventType[G]]
+EventType = ItemOrList[IndividualEventType[G, BASE_STATE]]
 
 
 class EventNamespace(types.SimpleNamespace):
@@ -1608,8 +1806,52 @@ class EventNamespace(types.SimpleNamespace):
     EventChainVar = EventChainVar
     LiteralEventChainVar = LiteralEventChainVar
     EventType = EventType
+    EventCallback = EventCallback
+
+    @overload
+    @staticmethod
+    def __call__(
+        func: None = None, *, background: bool | None = None
+    ) -> Callable[[Callable[Concatenate[BASE_STATE, P], T]], EventCallback[P, T]]: ...
+
+    @overload
+    @staticmethod
+    def __call__(
+        func: Callable[Concatenate[BASE_STATE, P], T],
+        *,
+        background: bool | None = None,
+    ) -> EventCallback[P, T]: ...
+
+    @staticmethod
+    def __call__(
+        func: Callable[Concatenate[BASE_STATE, P], T] | None = None,
+        *,
+        background: bool | None = None,
+    ) -> Union[
+        EventCallback[P, T],
+        Callable[[Callable[Concatenate[BASE_STATE, P], T]], EventCallback[P, T]],
+    ]:
+        """Wrap a function to be used as an event.
+
+        Args:
+            func: The function to wrap.
+            background: Whether the event should be run in the background. Defaults to False.
+
+        Returns:
+            The wrapped function.
+        """
+
+        def wrapper(
+            func: Callable[Concatenate[BASE_STATE, P], T],
+        ) -> EventCallback[P, T]:
+            if background is True:
+                return background_event_decorator(func, __internal_reflex_call=True)  # type: ignore
+            return func  # type: ignore
+
+        if func is not None:
+            return wrapper(func)
+        return wrapper
 
-    __call__ = staticmethod(event_handler)
     get_event = staticmethod(get_event)
     get_hydrate_event = staticmethod(get_hydrate_event)
     fix_events = staticmethod(fix_events)
@@ -1619,13 +1861,14 @@ class EventNamespace(types.SimpleNamespace):
     check_fn_match_arg_spec = staticmethod(check_fn_match_arg_spec)
     resolve_annotation = staticmethod(resolve_annotation)
     parse_args_spec = staticmethod(parse_args_spec)
-    identity_event = staticmethod(identity_event)
+    passthrough_event_spec = staticmethod(passthrough_event_spec)
     input_event = staticmethod(input_event)
     key_event = staticmethod(key_event)
-    empty_event = staticmethod(empty_event)
+    no_args_event_spec = staticmethod(no_args_event_spec)
     server_side = staticmethod(server_side)
     redirect = staticmethod(redirect)
     console_log = staticmethod(console_log)
+    noop = staticmethod(noop)
     back = staticmethod(back)
     window_alert = staticmethod(window_alert)
     set_focus = staticmethod(set_focus)
@@ -1639,6 +1882,8 @@ class EventNamespace(types.SimpleNamespace):
     set_clipboard = staticmethod(set_clipboard)
     download = staticmethod(download)
     call_script = staticmethod(call_script)
+    call_function = staticmethod(call_function)
+    run_script = staticmethod(run_script)
 
 
 event = EventNamespace()