diff --git a/docs/changelog/upgrading/upgrading-to-0-10.md b/docs/changelog/upgrading/upgrading-to-0-10.md index d2aff4c1c6c..d95e968f1d0 100644 --- a/docs/changelog/upgrading/upgrading-to-0-10.md +++ b/docs/changelog/upgrading/upgrading-to-0-10.md @@ -9,7 +9,7 @@ This page covers the 0.10 changes most likely to break an existing app, or to be ## Reading a backend var on a state class -Reading a backend var on the state class, such as `State._items`, now returns its `Field` instead of the var's default value ([#7312](https://github.com/reflex-dev/reflex/pull/7312)). Passing it to a component raises `ChildrenTypeError` (as a child); a prop may raise `BackendVarFormatError` when its value is built or rendered (earlier 0.10 releases may instead raise `TypeError: Unsupported type for LiteralVar`), while typed props can still reject it with `TypeError` during component creation. Turning it into text with an f-string, `str.format()`, `str()` or `%` raises `BackendVarFormatError` (earlier 0.10 releases embed the `Field` text for `!s`, `str()` and `%`; `!r` and `repr()` still do). Reading the var on a state instance, such as `self._items`, is unchanged. +Reading a backend var on the state class, such as `State._items`, now returns its `Field` instead of the var's default value ([#7312](https://github.com/reflex-dev/reflex/pull/7312)). Passing it to a component as a child or a prop raises `BackendVarFormatError` (earlier releases may instead raise `ChildrenTypeError` for a child, `TypeError` for a typed prop, or `TypeError: Unsupported type for LiteralVar` when the value is built or rendered). Turning it into text with an f-string, `str.format()`, `str()` or `%` raises `BackendVarFormatError` (earlier 0.10 releases embed the `Field` text for `!s`, `str()` and `%`; `!r` and `repr()` still do). Reading the var on a state instance, such as `self._items`, is unchanged. Replace the class read with what the code meant: diff --git a/docs/changelog/upgrading/upgrading-to-0-11.md b/docs/changelog/upgrading/upgrading-to-0-11.md index 8bcf0ae96fc..75e16fa9749 100644 --- a/docs/changelog/upgrading/upgrading-to-0-11.md +++ b/docs/changelog/upgrading/upgrading-to-0-11.md @@ -241,7 +241,7 @@ def serialize_point(point: Point) -> dict: ## Printing a backend var on a state class -A backend var read on the state class, such as `State._secret`, is a `Field` since 0.10. In 0.11, `print()`, logging and `str()` of it raise `BackendVarFormatError`, as f-strings already did ([#7651](https://github.com/reflex-dev/reflex/pull/7651)). The same error replaces the `TypeError` or `ValueError` raised when the var is passed where a frontend value is needed, such as a component prop, `rx.toast(State._secret)`, or the `title`, `description` or `image` of `app.add_page(...)`. +A backend var read on the state class, such as `State._secret`, is a `Field` since 0.10. In 0.11, `print()`, logging and `str()` of it raise `BackendVarFormatError`, as f-strings already did ([#7651](https://github.com/reflex-dev/reflex/pull/7651)). The same error replaces the `TypeError` or `ValueError` raised when the var is passed where a frontend value is needed, such as a component child or prop, an event handler argument, `rx.toast(State._secret)`, or the `title`, `description`, `image` or `on_load` of `app.add_page(...)`. Comparing it with a value, as in `rx.cond(State._secret == "x", ...)`, or truth-testing it also raises, where it used to give a plain `False` or `True`. ```python class State(rx.State): diff --git a/news/+backend-var-on-load.bugfix.md b/news/+backend-var-on-load.bugfix.md new file mode 100644 index 00000000000..b0599fc859e --- /dev/null +++ b/news/+backend-var-on-load.bugfix.md @@ -0,0 +1 @@ +`app.add_page(...)` now raises `BackendVarFormatError` when `on_load` is a backend var such as `State._handler`, instead of accepting it. diff --git a/packages/reflex-base/news/+backend-var-ui-errors.bugfix.md b/packages/reflex-base/news/+backend-var-ui-errors.bugfix.md new file mode 100644 index 00000000000..04f5df626cc --- /dev/null +++ b/packages/reflex-base/news/+backend-var-ui-errors.bugfix.md @@ -0,0 +1 @@ +Using a backend var such as `State._secret` as a component child, a typed prop (`rx.el.div(title=State._secret)`, `rx.link(href=State._secret)`) or an event handler argument now raises `BackendVarFormatError`, which names the var and the fix. A child used to raise a `ChildrenTypeError` that named neither, and a typed prop or event argument a generic error that printed the var's default value. Comparing a backend var or a mixin's field with a value (`State._secret == "x"`) or truth-testing it now raises the same error, instead of a plain `False` or `True` that made `rx.cond` always take one branch. Fields still compare equal to themselves. diff --git a/packages/reflex-base/src/reflex_base/components/component.py b/packages/reflex-base/src/reflex_base/components/component.py index 8cbc6993e53..cb0ab853a5a 100644 --- a/packages/reflex-base/src/reflex_base/components/component.py +++ b/packages/reflex-base/src/reflex_base/components/component.py @@ -947,6 +947,7 @@ def _post_init(self, *args, **kwargs): Raises: TypeError: If an invalid prop is passed. ValueError: If an event trigger passed is not valid. + BackendVarFormatError: If a child or typed prop is a field with no frontend var. """ # Set the id and children initially. children = kwargs.get("children", []) @@ -991,6 +992,8 @@ def _post_init(self, *args, **kwargs): # Check whether the key is a component prop. if is_var: + if isinstance(value, Field): + raise value._no_frontend_var_error() try: kwargs[key] = LiteralVar.create(value) @@ -1286,6 +1289,9 @@ def _validate_children(cls, children: tuple | list): if isinstance(child, (tuple, list)): cls._validate_children(child) + if isinstance(child, Field): + raise child._no_frontend_var_error() + # Make sure the child is a valid type. if isinstance(child, dict) or not isinstance(child, ComponentChildTypes): error = ChildrenTypeError(component=cls.__name__, child=child) diff --git a/packages/reflex-base/src/reflex_base/event/__init__.py b/packages/reflex-base/src/reflex_base/event/__init__.py index 63844816912..0ddd680c6d0 100644 --- a/packages/reflex-base/src/reflex_base/event/__init__.py +++ b/packages/reflex-base/src/reflex_base/event/__init__.py @@ -807,8 +807,12 @@ def __call__(self, *args: Any, **kwargs: Any) -> "EventSpec": Raises: EventHandlerTypeError: If the arguments are invalid. + BackendVarFormatError: If an argument is a field with no frontend var. """ - from reflex_base.utils.exceptions import EventHandlerTypeError + from reflex_base.utils.exceptions import ( + BackendVarFormatError, + EventHandlerTypeError, + ) if args and isinstance(args[0], self.state or _base_state_type()): # A decorator stacked above @rx.event calls the handler like the @@ -875,6 +879,8 @@ def __call__(self, *args: Any, **kwargs: Any) -> "EventSpec": # Otherwise, convert to JSON. try: payload.append((Var(_js_expr=fn_arg), LiteralVar.create(arg))) + except BackendVarFormatError: + raise except TypeError as e: msg = f"Arguments to event handlers must be Vars or JSON-serializable. Got {arg!r} of type {type(arg)}." raise EventHandlerTypeError(msg) from e @@ -1040,8 +1046,12 @@ def add_args(self, *args: Var) -> "EventSpec": Raises: EventHandlerTypeError: If the arguments are invalid. + BackendVarFormatError: If an argument is a field with no frontend var. """ - from reflex_base.utils.exceptions import EventHandlerTypeError + from reflex_base.utils.exceptions import ( + BackendVarFormatError, + EventHandlerTypeError, + ) n_self_args = 1 if self.handler.state is not None else 0 @@ -1055,6 +1065,8 @@ def add_args(self, *args: Var) -> "EventSpec": try: for arg in args: values.append(LiteralVar.create(value=arg)) # noqa: PERF401, RUF100 + except BackendVarFormatError: + raise except TypeError as e: msg = f"Arguments to event handlers must be Vars or JSON-serializable. Got {arg!r} of type {type(arg)}." raise EventHandlerTypeError(msg) from e diff --git a/packages/reflex-base/src/reflex_base/vars/base.py b/packages/reflex-base/src/reflex_base/vars/base.py index 1e82c09d127..22626efdbe9 100644 --- a/packages/reflex-base/src/reflex_base/vars/base.py +++ b/packages/reflex-base/src/reflex_base/vars/base.py @@ -4480,6 +4480,56 @@ def __str__(self) -> str: """ raise self._no_frontend_var_error() + def _has_no_frontend_var(self) -> bool: + """Whether class access reaches the field itself, not a Var. + + Returns: + Whether the field is a backend var or a mixin's field. + """ + return self._var is None and ( + self._backend or getattr(self._owner, "_mixin", False) + ) + + def __eq__(self, other: object) -> bool: + """Compare by identity, refusing to compare a backend var with a value. + + Class access reaches a backend var's field itself, so ``State._x == "a"`` + would otherwise be a plain ``False``, and ``rx.cond`` on it would always + take the same branch. Comparing two fields still works, by identity. + ``!=`` uses this method too. + + Args: + other: The object to compare with. + + Returns: + Whether the two are the same field. + + Raises: + BackendVarFormatError: If the field has no frontend var and the + other object is not a field. + """ + if not isinstance(other, Field): + if self._has_no_frontend_var(): + raise self._no_frontend_var_error() + return NotImplemented + return self is other + + # Defining __eq__ would otherwise make fields unhashable. + __hash__ = object.__hash__ + + def __bool__(self) -> bool: + """Refuse to truth-test a backend var, which would always be true. + + Returns: + True, for a field with a frontend var. + + Raises: + BackendVarFormatError: If the field has no frontend var. + """ + if self._has_no_frontend_var(): + raise self._no_frontend_var_error() + return True + def _no_frontend_var_error(self) -> BackendVarFormatError: """Build the error for using the field where a frontend var is needed. diff --git a/reflex/app.py b/reflex/app.py index 3d9229c599c..eedfacfa4a0 100644 --- a/reflex/app.py +++ b/reflex/app.py @@ -296,10 +296,10 @@ def default_error_boundary(*children: Component, **props) -> Component: def _reject_page_meta_fields(*values: Any) -> None: - """Reject page metadata given as a field with no frontend var. + """Reject page metadata or on_load events given as a field with no frontend var. Args: - *values: The page metadata values. + *values: The page metadata values or on_load events. Raises: BackendVarFormatError: If a value is a field with no frontend var. @@ -1539,7 +1539,7 @@ def add_page( context: Values passed to page for custom page-specific logic. Raises: - BackendVarFormatError: When title, description or image is a field with no frontend var. + BackendVarFormatError: When title, description, image or on_load is a field with no frontend var. PageValueError: When the component is not set for a non-404 page. RouteValueError: When the specified route name already exists. ValueError: When the route syntax is invalid. @@ -1588,11 +1588,15 @@ def _prepare_page( The validated page descriptor and its dynamic route arguments. Raises: + BackendVarFormatError: When title, description, image or on_load is a field with no frontend var. PageValueError: When the component is not set for a non-404 page. RouteValueError: When a route cannot be derived. ValueError: When the route syntax is invalid. """ _reject_page_meta_fields(title, description, image) + _reject_page_meta_fields( + *(on_load if is_non_string_sequence(on_load) else [on_load]) + ) route = self._page_route_key(component, route) if route is None: msg = "Route must be set if component is not a callable." diff --git a/tests/units/components/test_component.py b/tests/units/components/test_component.py index 4ab5d08c602..99b612c3da1 100644 --- a/tests/units/components/test_component.py +++ b/tests/units/components/test_component.py @@ -49,6 +49,7 @@ ) from reflex.state import BaseState from reflex.utils import imports +from tests.units.field_errors import backend_var_error @pytest.mark.parametrize("name", ["div", "", None]) @@ -789,13 +790,14 @@ def test_component_create_unallowed_types(children, test_component): def test_component_create_backend_var_child(test_component): - """A backend var child reports its type rather than formatting the field.""" + """A backend var child raises the backend var format error.""" class BackendChildState(BaseState): _secret: int = 42 - with pytest.raises(ChildrenTypeError, match=r"received child of type Field\."): + with pytest.raises(BackendVarFormatError) as exc_info: test_component.create(BackendChildState._secret) + assert str(exc_info.value) == backend_var_error("BackendChildState._secret") class EventChildState(BaseState): @@ -844,14 +846,30 @@ def test_component_create_event_child(make_child, type_name, test_component): ] -def test_component_create_backend_var_prop(): - """A backend var passed to a typed prop reports its repr, not a format error.""" +class BackendPropState(BaseState): + """A state with a backend var, for typed prop misuse tests.""" - class BackendPropState(BaseState): - _size: str = "3" + _size: str = "3" - with pytest.raises(TypeError, match=r"got value Field\(default='3'"): - rx.heading("x", size=BackendPropState._size) # pyright: ignore[reportArgumentType] + +@pytest.mark.parametrize( + "create", + [ + lambda f: rx.heading("x", size=f), + lambda f: rx.el.div(title=f), + lambda f: rx.link("x", href=f), + ], + ids=["heading_size", "div_title", "link_href"], +) +def test_component_create_backend_var_prop(create: Callable[[Any], Component]): + """A backend var passed to a typed prop raises the backend var format error. + + Args: + create: Creates a component with the backend var as a prop. + """ + with pytest.raises(BackendVarFormatError) as exc_info: + create(BackendPropState._size) + assert str(exc_info.value) == backend_var_error("BackendPropState._size") class BackendSrcState(BaseState): diff --git a/tests/units/field_errors.py b/tests/units/field_errors.py new file mode 100644 index 00000000000..868fbff353d --- /dev/null +++ b/tests/units/field_errors.py @@ -0,0 +1,36 @@ +"""Expected messages of the error for a field with no frontend var.""" + +_REPR_HINT = " To print or log the field itself in server code, use repr()." + + +def backend_var_error(path: str) -> str: + """Build the full error message for using a backend var in the UI. + + Args: + path: The backend var as ``State._name``. + + Returns: + The complete error message. + """ + return ( + f"Backend var '{path}' exists only on the server and has no frontend" + f" value, so it cannot be used in the UI. Use {path}.default_value() for" + " its default value, declare it as ClassVar[...] for a constant shared by" + " all sessions, or use a regular state var for a value the UI should show" + " and update." + _REPR_HINT + ) + + +def mixin_var_error(path: str) -> str: + """Build the full error message for using a mixin's field in the UI. + + Args: + path: The field as ``Mixin.name``. + + Returns: + The complete error message. + """ + return ( + f"Var '{path}' is declared on a mixin state, which has no frontend vars." + " Access it through a state that includes the mixin instead." + _REPR_HINT + ) diff --git a/tests/units/reflex_base/vars/test_base.py b/tests/units/reflex_base/vars/test_base.py index 2be7bd6e83d..e9ed42477dd 100644 --- a/tests/units/reflex_base/vars/test_base.py +++ b/tests/units/reflex_base/vars/test_base.py @@ -90,6 +90,7 @@ from reflex.istate.data import ReflexURLCastedVar, RouterDataVar from reflex.istate.proxy import MutableProxy from reflex.state import BaseState, State, _override_base_method +from tests.units.field_errors import backend_var_error, mixin_var_error _MARKER_ATTR = "_marker" @@ -1933,6 +1934,62 @@ class Model(EvenMoreBasicBaseState): use(Model._secret) +@pytest.mark.parametrize( + "use", + [ + lambda f: f == "x", + lambda f: f != "x", + lambda f: f in ["x", "y"], + lambda f: bool(f), + ], + ids=["eq", "ne", "in_list", "bool"], +) +def test_backend_field_comparison_raises_format_error( + use: typing.Callable[[Any], Any], +): + """Comparing or truth-testing a backend var raises instead of a plain bool. + + Args: + use: Compares or truth-tests the backend field. + """ + + class Model(EvenMoreBasicBaseState): + _secret: str = "s" + + with pytest.raises(BackendVarFormatError) as exc_info: + use(Model._secret) + assert str(exc_info.value) == backend_var_error("Model._secret") + + +def test_backend_field_identity_and_hash_unchanged(): + """Fields still compare and hash by identity with other fields.""" + + class Model(EvenMoreBasicBaseState): + _secret: str = "s" + _other: str = "o" + + secret, other = Model._secret, Model._other + assert secret == secret + assert secret != other + assert {secret: 1, other: 2}[secret] == 1 + assert secret in [other, secret] + assert len({secret, other, secret}) == 2 + + +def test_mixin_field_comparison_raises_format_error(): + """Comparing or truth-testing a mixin's field says to use the including state.""" + + class Mixin(EvenMoreBasicBaseState, mixin=True): + count: int = 0 + + with pytest.raises(BackendVarFormatError) as eq_info: + Mixin.count == 1 # noqa: B015 + with pytest.raises(BackendVarFormatError) as bool_info: + bool(Mixin.count) + assert str(eq_info.value) == mixin_var_error("Mixin.count") + assert str(bool_info.value) == mixin_var_error("Mixin.count") + + def test_mixin_field_literal_var_raises_format_error(): """A mixin's field inside a LiteralVar says to use the including state.""" diff --git a/tests/units/test_app.py b/tests/units/test_app.py index b348f5f4eac..9791db530d1 100644 --- a/tests/units/test_app.py +++ b/tests/units/test_app.py @@ -110,6 +110,7 @@ SocketRecord, ) from tests.units.exception_handler_helpers import logged +from tests.units.field_errors import backend_var_error from .conftest import active_tracer, chdir, metric_points from .mock_redis import mock_redis @@ -341,6 +342,42 @@ def test_add_page_backend_var_meta_raises_format_error( app.add_page(index_page, route="/meta", **{key: BackendMetaState._meta}) # pyright: ignore[reportArgumentType] +def test_add_page_backend_var_meta_content_raises_format_error( + app: App, index_page: ComponentCallable +): + """A backend var in a meta tag's content raises when the page is compiled. + + Args: + app: The app to test. + index_page: The index page. + """ + app.add_page( + index_page, + route="/meta", + meta=[{"name": "x", "content": BackendMetaState._meta}], + ) + with pytest.raises(exceptions.BackendVarFormatError) as exc_info: + app._compile_page("meta") + assert str(exc_info.value) == backend_var_error("BackendMetaState._meta") + + +@pytest.mark.parametrize("as_list", [False, True]) +def test_add_page_backend_var_on_load_raises_format_error( + app: App, index_page: ComponentCallable, as_list: bool +): + """A backend var passed as on_load raises when the page is added. + + Args: + app: The app to test. + index_page: The index page. + as_list: Whether on_load is given as a list. + """ + on_load = [BackendMetaState._meta] if as_list else BackendMetaState._meta + with pytest.raises(exceptions.BackendVarFormatError) as exc_info: + app.add_page(index_page, route="/meta", on_load=on_load) # pyright: ignore[reportArgumentType] + assert str(exc_info.value) == backend_var_error("BackendMetaState._meta") + + def test_add_page_set_route(app: App, index_page: ComponentCallable): """Test adding a page to an app. diff --git a/tests/units/test_event.py b/tests/units/test_event.py index 538daadae01..7840e01149c 100644 --- a/tests/units/test_event.py +++ b/tests/units/test_event.py @@ -32,7 +32,6 @@ from reflex_base.utils.exceptions import ( BackendVarFormatError, EventHandlerArgTypeMismatchError, - EventHandlerTypeError, EventHandlerValueError, ) from reflex_base.utils.form import FormData @@ -42,6 +41,7 @@ import reflex as rx from reflex.state import BaseState +from tests.units.field_errors import backend_var_error def make_var(value) -> Var: @@ -266,20 +266,25 @@ def args_spec(value: Var[dict]) -> list[Var[dict]]: assert handler.prevent_default._type_hints is handler._type_hints -def test_backend_var_event_arg_reports_repr(): - """A backend var passed as an event arg reports its repr, not a format error.""" +def test_backend_var_event_arg_raises_format_error(): + """A backend var passed as an event arg raises the backend var format error.""" - class S(BaseState): + class BackendEventArgState(BaseState): _secret: int = 42 @event def on_event(self, value: int): pass - with pytest.raises(EventHandlerTypeError, match=r"Got Field\(default=42"): - S.on_event(S._secret) - with pytest.raises(EventHandlerTypeError, match=r"Got Field\(default=42"): - cast(EventSpec, S.on_event()).add_args(S._secret) # pyright: ignore[reportArgumentType] + expected = backend_var_error("BackendEventArgState._secret") + with pytest.raises(BackendVarFormatError) as call_info: + BackendEventArgState.on_event(BackendEventArgState._secret) + with pytest.raises(BackendVarFormatError) as add_args_info: + cast(EventSpec, BackendEventArgState.on_event()).add_args( + BackendEventArgState._secret # pyright: ignore[reportArgumentType] + ) + assert str(call_info.value) == expected + assert str(add_args_info.value) == expected class BackendTriggerState(BaseState):