reflex 0.5.0.post1__py3-none-any.whl → 0.5.1a1__py3-none-any.whl

reflex/config.py

@@ -251,8 +251,10 @@ class Config(Base):
             The updated config values.
 
         Raises:
-            ValueError: If an environment variable is set to an invalid type.
+            EnvVarValueError: If an environment variable is set to an invalid type.
         """
+        from reflex.utils.exceptions import EnvVarValueError
+
         updated_values = {}
         # Iterate over the fields.
         for key, field in self.__fields__.items():
@@ -273,11 +275,11 @@ class Config(Base):
                         env_var = env_var.lower() in ["true", "1", "yes"]
                     else:
                         env_var = field.type_(env_var)
-                except ValueError:
+                except ValueError as ve:
                     console.error(
                         f"Could not convert {key.upper()}={env_var} to type {field.type_}"
                     )
-                    raise
+                    raise EnvVarValueError from ve
 
                 # Set the value.
                 updated_values[key] = env_var

reflex/constants/compiler.py

@@ -103,9 +103,9 @@ class Imports(SimpleNamespace):
     """Common sets of import vars."""
 
     EVENTS = {
-        "react": {ImportVar(tag="useContext")},
-        f"/{Dirs.CONTEXTS_PATH}": {ImportVar(tag="EventLoopContext")},
-        f"/{Dirs.STATE_PATH}": {ImportVar(tag=CompileVars.TO_EVENT)},
+        "react": [ImportVar(tag="useContext")],
+        f"/{Dirs.CONTEXTS_PATH}": [ImportVar(tag="EventLoopContext")],
+        f"/{Dirs.STATE_PATH}": [ImportVar(tag=CompileVars.TO_EVENT)],
     }
 
 

reflex/constants/installer.py

@@ -35,7 +35,7 @@ class Bun(SimpleNamespace):
     """Bun constants."""
 
     # The Bun version.
-    VERSION = "1.1.6"
+    VERSION = "1.1.8"
     # Min Bun Version
     MIN_VERSION = "0.7.0"
     # The directory to store the bun.

reflex/event.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import inspect
 from base64 import b64encode
-from types import FunctionType
 from typing import (
     Any,
     Callable,
@@ -180,8 +179,10 @@ class EventHandler(EventActionsMixin):
             The event spec, containing both the function and args.
 
         Raises:
-            TypeError: If the arguments are invalid.
+            EventHandlerTypeError: If the arguments are invalid.
         """
+        from reflex.utils.exceptions import EventHandlerTypeError
+
         # Get the function args.
         fn_args = inspect.getfullargspec(self.fn).args[1:]
         fn_args = (Var.create_safe(arg) for arg in fn_args)
@@ -197,7 +198,7 @@ class EventHandler(EventActionsMixin):
             try:
                 values.append(Var.create(arg, _var_is_string=isinstance(arg, str)))
             except TypeError as e:
-                raise TypeError(
+                raise EventHandlerTypeError(
                     f"Arguments to event handlers must be Vars or JSON-serializable. Got {arg} of type {type(arg)}."
                 ) from e
         payload = tuple(zip(fn_args, values))
@@ -256,8 +257,10 @@ class EventSpec(EventActionsMixin):
             The event spec with the new arguments.
 
         Raises:
-            TypeError: If the arguments are invalid.
+            EventHandlerTypeError: If the arguments are invalid.
         """
+        from reflex.utils.exceptions import EventHandlerTypeError
+
         # Get the remaining unfilled function args.
         fn_args = inspect.getfullargspec(self.handler.fn).args[1 + len(self.args) :]
         fn_args = (Var.create_safe(arg) for arg in fn_args)
@@ -268,7 +271,7 @@ class EventSpec(EventActionsMixin):
             try:
                 values.append(Var.create(arg, _var_is_string=isinstance(arg, str)))
             except TypeError as e:
-                raise TypeError(
+                raise EventHandlerTypeError(
                     f"Arguments to event handlers must be Vars or JSON-serializable. Got {arg} of type {type(arg)}."
                 ) from e
         new_payload = tuple(zip(fn_args, values))
@@ -312,10 +315,12 @@ class CallableEventSpec(EventSpec):
             The EventSpec returned from calling the function.
 
         Raises:
-            TypeError: If the CallableEventSpec has no associated function.
+            EventHandlerTypeError: If the CallableEventSpec has no associated function.
         """
+        from reflex.utils.exceptions import EventHandlerTypeError
+
         if self.fn is None:
-            raise TypeError("CallableEventSpec has no associated function.")
+            raise EventHandlerTypeError("CallableEventSpec has no associated function.")
         return self.fn(*args, **kwargs)
 
 
@@ -462,18 +467,27 @@ def server_side(name: str, sig: inspect.Signature, **kwargs) -> EventSpec:
     )
 
 
-def redirect(path: str | Var[str], external: Optional[bool] = False) -> EventSpec:
+def redirect(
+    path: str | Var[str],
+    external: Optional[bool] = False,
+    replace: Optional[bool] = False,
+) -> EventSpec:
     """Redirect to a new path.
 
     Args:
         path: The path to redirect to.
         external: Whether to open in new tab or not.
+        replace: If True, the current page will not create a new history entry.
 
     Returns:
         An event to redirect to the path.
     """
     return server_side(
-        "_redirect", get_fn_signature(redirect), path=path, external=external
+        "_redirect",
+        get_fn_signature(redirect),
+        path=path,
+        external=external,
+        replace=replace,
     )
 
 
@@ -700,7 +714,11 @@ def _callback_arg_spec(eval_result):
 
 def call_script(
     javascript_code: str,
-    callback: EventHandler | Callable | None = None,
+    callback: EventSpec
+    | EventHandler
+    | Callable
+    | List[EventSpec | EventHandler | Callable]
+    | None = None,
 ) -> EventSpec:
     """Create an event handler that executes arbitrary javascript code.
 
@@ -710,21 +728,14 @@ def call_script(
 
     Returns:
         EventSpec: An event that will execute the client side javascript.
-
-    Raises:
-        ValueError: If the callback is not a valid event handler.
     """
     callback_kwargs = {}
     if callback is not None:
-        arg_name = parse_args_spec(_callback_arg_spec)[0]._var_name
-        if isinstance(callback, EventHandler):
-            event_spec = call_event_handler(callback, _callback_arg_spec)
-        elif isinstance(callback, FunctionType):
-            event_spec = call_event_fn(callback, _callback_arg_spec)[0]
-        else:
-            raise ValueError("Cannot use {callback!r} as a call_script callback.")
         callback_kwargs = {
-            "callback": f"({arg_name}) => queueEvents([{format.format_event(event_spec)}], {constants.CompileVars.SOCKET})"
+            "callback": format.format_queue_events(
+                callback,
+                args_spec=lambda result: [result],
+            )
         }
     return server_side(
         "_call_script",
@@ -834,10 +845,11 @@ def call_event_fn(fn: Callable, arg: Union[Var, ArgsSpec]) -> list[EventSpec]:
         The event specs from calling the function.
 
     Raises:
-        ValueError: If the lambda has an invalid signature.
+        EventHandlerValueError: If the lambda has an invalid signature.
     """
     # Import here to avoid circular imports.
     from reflex.event import EventHandler, EventSpec
+    from reflex.utils.exceptions import EventHandlerValueError
 
     # Get the args of the lambda.
     args = inspect.getfullargspec(fn).args
@@ -851,7 +863,7 @@ def call_event_fn(fn: Callable, arg: Union[Var, ArgsSpec]) -> list[EventSpec]:
         elif len(args) == 1:
             out = fn(arg)
         else:
-            raise ValueError(f"Lambda {fn} must have 0 or 1 arguments.")
+            raise EventHandlerValueError(f"Lambda {fn} must have 0 or 1 arguments.")
 
     # Convert the output to a list.
     if not isinstance(out, List):
@@ -869,7 +881,9 @@ def call_event_fn(fn: Callable, arg: Union[Var, ArgsSpec]) -> list[EventSpec]:
 
         # Make sure the event spec is valid.
         if not isinstance(e, EventSpec):
-            raise ValueError(f"Lambda {fn} returned an invalid event spec: {e}.")
+            raise EventHandlerValueError(
+                f"Lambda {fn} returned an invalid event spec: {e}."
+            )
 
         # Add the event spec to the chain.
         events.append(e)

reflex/experimental/__init__.py

@@ -2,11 +2,13 @@
 
 from types import SimpleNamespace
 
+from reflex.components.props import PropsBase
 from reflex.components.radix.themes.components.progress import progress as progress
 from reflex.components.sonner.toast import toast as toast
 
 from ..utils.console import warn
 from . import hooks as hooks
+from .client_state import ClientStateVar as ClientStateVar
 from .layout import layout as layout
 from .misc import run_in_thread as run_in_thread
 
@@ -15,9 +17,11 @@ warn(
 )
 
 _x = SimpleNamespace(
+    client_state=ClientStateVar.create,
     hooks=hooks,
     layout=layout,
     progress=progress,
+    PropsBase=PropsBase,
     run_in_thread=run_in_thread,
     toast=toast,
 )

reflex/experimental/client_state.py

@@ -0,0 +1,198 @@
+"""Handle client side state with `useState`."""
+
+import dataclasses
+import sys
+from typing import Any, Callable, Optional, Type
+
+from reflex import constants
+from reflex.event import EventChain, EventHandler, EventSpec, call_script
+from reflex.utils.imports import ImportVar
+from reflex.vars import Var, VarData
+
+
+def _client_state_ref(var_name: str) -> str:
+    """Get the ref path for a ClientStateVar.
+
+    Args:
+        var_name: The name of the variable.
+
+    Returns:
+        An accessor for ClientStateVar ref as a string.
+    """
+    return f"refs['_client_state_{var_name}']"
+
+
+@dataclasses.dataclass(
+    eq=False,
+    **{"slots": True} if sys.version_info >= (3, 10) else {},
+)
+class ClientStateVar(Var):
+    """A Var that exists on the client via useState."""
+
+    # The name of the var.
+    _var_name: str = dataclasses.field()
+
+    # Track the names of the getters and setters
+    _setter_name: str = dataclasses.field()
+    _getter_name: str = dataclasses.field()
+
+    # The type of the var.
+    _var_type: Type = dataclasses.field(default=Any)
+
+    # Whether this is a local javascript variable.
+    _var_is_local: bool = dataclasses.field(default=False)
+
+    # Whether the var is a string literal.
+    _var_is_string: bool = dataclasses.field(default=False)
+
+    # _var_full_name should be prefixed with _var_state
+    _var_full_name_needs_state_prefix: bool = dataclasses.field(default=False)
+
+    # Extra metadata associated with the Var
+    _var_data: Optional[VarData] = dataclasses.field(default=None)
+
+    def __hash__(self) -> int:
+        """Define a hash function for a var.
+
+        Returns:
+            The hash of the var.
+        """
+        return hash(
+            (self._var_name, str(self._var_type), self._getter_name, self._setter_name)
+        )
+
+    @classmethod
+    def create(cls, var_name, default=None) -> "ClientStateVar":
+        """Create a local_state Var that can be accessed and updated on the client.
+
+        The `ClientStateVar` should be included in the highest parent component
+        that contains the components which will access and manipulate the client
+        state. It has no visual rendering, including it ensures that the
+        `useState` hook is called in the correct scope.
+
+        To render the var in a component, use the `value` property.
+
+        To update the var in a component, use the `set` property.
+
+        To access the var in an event handler, use the `retrieve` method with
+        `callback` set to the event handler which should receive the value.
+
+        To update the var in an event handler, use the `push` method with the
+        value to update.
+
+        Args:
+            var_name: The name of the variable.
+            default: The default value of the variable.
+
+        Returns:
+            ClientStateVar
+        """
+        if default is None:
+            default_var = Var.create_safe("", _var_is_local=False, _var_is_string=False)
+        elif not isinstance(default, Var):
+            default_var = Var.create_safe(default)
+        else:
+            default_var = default
+        setter_name = f"set{var_name.capitalize()}"
+        return cls(
+            _var_name="",
+            _setter_name=setter_name,
+            _getter_name=var_name,
+            _var_is_local=False,
+            _var_is_string=False,
+            _var_type=default_var._var_type,
+            _var_data=VarData.merge(
+                default_var._var_data,
+                VarData(  # type: ignore
+                    hooks={
+                        f"const [{var_name}, {setter_name}] = useState({default_var._var_name_unwrapped})": None,
+                        f"{_client_state_ref(var_name)} = {var_name}": None,
+                        f"{_client_state_ref(setter_name)} = {setter_name}": None,
+                    },
+                    imports={
+                        "react": [ImportVar(tag="useState", install=False)],
+                        f"/{constants.Dirs.STATE_PATH}": [ImportVar(tag="refs")],
+                    },
+                ),
+            ),
+        )
+
+    @property
+    def value(self) -> Var:
+        """Get a placeholder for the Var.
+
+        This property can only be rendered on the frontend.
+
+        To access the value in a backend event handler, see `retrieve`.
+
+        Returns:
+            an accessor for the client state variable.
+        """
+        return (
+            Var.create_safe(
+                _client_state_ref(self._getter_name),
+                _var_is_local=False,
+                _var_is_string=False,
+            )
+            .to(self._var_type)
+            ._replace(
+                merge_var_data=VarData(  # type: ignore
+                    imports={
+                        f"/{constants.Dirs.STATE_PATH}": [ImportVar(tag="refs")],
+                    }
+                )
+            )
+        )
+
+    @property
+    def set(self) -> Var:
+        """Set the value of the client state variable.
+
+        This property can only be attached to a frontend event trigger.
+
+        To set a value from a backend event handler, see `push`.
+
+        Returns:
+            A special EventChain Var which will set the value when triggered.
+        """
+        return (
+            Var.create_safe(
+                _client_state_ref(self._setter_name),
+                _var_is_local=False,
+                _var_is_string=False,
+            )
+            .to(EventChain)
+            ._replace(
+                merge_var_data=VarData(  # type: ignore
+                    imports={
+                        f"/{constants.Dirs.STATE_PATH}": [ImportVar(tag="refs")],
+                    }
+                )
+            )
+        )
+
+    def retrieve(self, callback: EventHandler | Callable | None = None) -> EventSpec:
+        """Pass the value of the client state variable to a backend EventHandler.
+
+        The event handler must `yield` or `return` the EventSpec to trigger the event.
+
+        Args:
+            callback: The callback to pass the value to.
+
+        Returns:
+            An EventSpec which will retrieve the value when triggered.
+        """
+        return call_script(_client_state_ref(self._getter_name), callback=callback)
+
+    def push(self, value: Any) -> EventSpec:
+        """Push a value to the client state variable from the backend.
+
+        The event handler must `yield` or `return` the EventSpec to trigger the event.
+
+        Args:
+            value: The value to update.
+
+        Returns:
+            An EventSpec which will push the value when triggered.
+        """
+        return call_script(f"{_client_state_ref(self._setter_name)}({value})")

reflex/state.py

@@ -279,11 +279,13 @@ class EventHandlerSetVar(EventHandler):
 
         Raises:
             AttributeError: If the given Var name does not exist on the state.
-            ValueError: If the given Var name is not a str
+            EventHandlerValueError: If the given Var name is not a str
         """
+        from reflex.utils.exceptions import EventHandlerValueError
+
         if args:
             if not isinstance(args[0], str):
-                raise ValueError(
+                raise EventHandlerValueError(
                     f"Var name must be passed as a string, got {args[0]!r}"
                 )
             # Check that the requested Var setter exists on the State at compile time.
@@ -357,6 +359,9 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
     # Whether the state has ever been touched since instantiation.
     _was_touched: bool = False
 
+    # Whether this state class is a mixin and should not be instantiated.
+    _mixin: ClassVar[bool] = False
+
     # A special event handler for setting base vars.
     setvar: ClassVar[EventHandler]
 
@@ -380,10 +385,12 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
             **kwargs: The kwargs to pass to the Pydantic init method.
 
         Raises:
-            RuntimeError: If the state is instantiated directly by end user.
+            ReflexRuntimeError: If the state is instantiated directly by end user.
         """
+        from reflex.utils.exceptions import ReflexRuntimeError
+
         if not _reflex_internal_init and not is_testing_env():
-            raise RuntimeError(
+            raise ReflexRuntimeError(
                 "State classes should not be instantiated directly in a Reflex app. "
                 "See https://reflex.dev/docs/state/ for further information."
             )
@@ -424,23 +431,30 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
         """
         return [
             v
-            for mixin in cls.__mro__
-            if mixin is cls or not issubclass(mixin, (BaseState, ABC))
+            for mixin in cls._mixins() + [cls]
             for v in mixin.__dict__.values()
             if isinstance(v, ComputedVar)
         ]
 
     @classmethod
-    def __init_subclass__(cls, **kwargs):
+    def __init_subclass__(cls, mixin: bool = False, **kwargs):
         """Do some magic for the subclass initialization.
 
         Args:
+            mixin: Whether the subclass is a mixin and should not be initialized.
             **kwargs: The kwargs to pass to the pydantic init_subclass method.
 
         Raises:
-            ValueError: If a substate class shadows another.
+            StateValueError: If a substate class shadows another.
         """
+        from reflex.utils.exceptions import StateValueError
+
         super().__init_subclass__(**kwargs)
+
+        cls._mixin = mixin
+        if mixin:
+            return
+
         # Event handlers should not shadow builtin state methods.
         cls._check_overridden_methods()
         # Computed vars should not shadow builtin state props.
@@ -471,7 +485,7 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
                 else:
                     # During normal operation, subclasses cannot have the same name, even if they are
                     # defined in different modules.
-                    raise ValueError(
+                    raise StateValueError(
                         f"The substate class '{cls.__name__}' has been defined multiple times. "
                         "Shadowing substate classes is not allowed."
                     )
@@ -536,7 +550,9 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
             for name, value in mixin.__dict__.items():
                 if isinstance(value, ComputedVar):
                     fget = cls._copy_fn(value.fget)
-                    newcv = ComputedVar(fget=fget, _var_name=value._var_name)
+                    newcv = value._replace(fget=fget)
+                    # cleanup refs to mixin cls in var_data
+                    newcv._var_data = None
                     newcv._var_set_state(cls)
                     setattr(cls, name, newcv)
                     cls.computed_vars[newcv._var_name] = newcv
@@ -612,8 +628,11 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
         return [
             mixin
             for mixin in cls.__mro__
-            if not issubclass(mixin, (BaseState, ABC))
-            and mixin not in [pydantic.BaseModel, Base]
+            if (
+                mixin not in [pydantic.BaseModel, Base, cls]
+                and issubclass(mixin, BaseState)
+                and mixin._mixin is True
+            )
         ]
 
     @classmethod
@@ -736,7 +755,7 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
         parent_states = [
             base
             for base in cls.__bases__
-            if types._issubclass(base, BaseState) and base is not BaseState
+            if issubclass(base, BaseState) and base is not BaseState and not base._mixin
         ]
         assert len(parent_states) < 2, "Only one parent state is allowed."
         return parent_states[0] if len(parent_states) == 1 else None  # type: ignore
@@ -829,10 +848,12 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
             prop: The variable to initialize
 
         Raises:
-            TypeError: if the variable has an incorrect type
+            VarTypeError: if the variable has an incorrect type
         """
+        from reflex.utils.exceptions import VarTypeError
+
         if not types.is_valid_var_type(prop._var_type):
-            raise TypeError(
+            raise VarTypeError(
                 "State vars must be primitive Python types, "
                 "Plotly figures, Pandas dataframes, "
                 "or subclasses of rx.Base. "
@@ -1454,6 +1475,9 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
         Yields:
             StateUpdate object
         """
+        from reflex.utils import telemetry
+        from reflex.utils.exceptions import ReflexError
+
         # Get the function to process the event.
         fn = functools.partial(handler.fn, state)
 
@@ -1489,9 +1513,11 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
                 yield state._as_state_update(handler, events, final=True)
 
         # If an error occurs, throw a window alert.
-        except Exception:
+        except Exception as ex:
             error = traceback.format_exc()
             print(error)
+            if isinstance(ex, ReflexError):
+                telemetry.send("error", context="backend", detail=str(ex))
             yield state._as_state_update(
                 handler,
                 window_alert("An error occurred. See logs for details."),
@@ -1688,10 +1714,12 @@ class BaseState(Base, ABC, extra=pydantic.Extra.allow):
         if initial:
             computed_vars = {
                 # Include initial computed vars.
-                prop_name: cv._initial_value
-                if isinstance(cv, ComputedVar)
-                and not isinstance(cv._initial_value, types.Unset)
-                else self.get_value(getattr(self, prop_name))
+                prop_name: (
+                    cv._initial_value
+                    if isinstance(cv, ComputedVar)
+                    and not isinstance(cv._initial_value, types.Unset)
+                    else self.get_value(getattr(self, prop_name))
+                )
                 for prop_name, cv in self.computed_vars.items()
             }
         elif include_computed:
@@ -1818,7 +1846,7 @@ class OnLoadInternalState(State):
         ]
 
 
-class ComponentState(Base):
+class ComponentState(State, mixin=True):
     """Base class to allow for the creation of a state instance per component.
 
     This allows for the bundling of UI and state logic into a single class,
@@ -1860,6 +1888,18 @@ class ComponentState(Base):
     # The number of components created from this class.
     _per_component_state_instance_count: ClassVar[int] = 0
 
+    @classmethod
+    def __init_subclass__(cls, mixin: bool = False, **kwargs):
+        """Overwrite mixin default to True.
+
+        Args:
+            mixin: Whether the subclass is a mixin and should not be initialized.
+            **kwargs: The kwargs to pass to the pydantic init_subclass method.
+        """
+        if ComponentState in cls.__bases__:
+            mixin = True
+        super().__init_subclass__(mixin=mixin, **kwargs)
+
     @classmethod
     def get_component(cls, *children, **props) -> "Component":
         """Get the component instance.

reflex/style.py

@@ -16,10 +16,10 @@ LIGHT_COLOR_MODE: str = "light"
 DARK_COLOR_MODE: str = "dark"
 
 # Reference the global ColorModeContext
-color_mode_var_data = VarData(  # type: ignore
+color_mode_var_data = VarData(
     imports={
-        f"/{constants.Dirs.CONTEXTS_PATH}": {ImportVar(tag="ColorModeContext")},
-        "react": {ImportVar(tag="useContext")},
+        f"/{constants.Dirs.CONTEXTS_PATH}": [ImportVar(tag="ColorModeContext")],
+        "react": [ImportVar(tag="useContext")],
     },
     hooks={
         f"const [ {constants.ColorMode.NAME}, {constants.ColorMode.TOGGLE} ] = useContext(ColorModeContext)": None,