feat: get_var_value and set_var_value for vars reading into a state var
get_var_value only resolves a var that is a state field or computed var. A var that reads into one raises UnretrievableVarValueError, even though the backend holds everything needed to resolve it:
await self.get_var_value(State.user.tags[0]) # raises
await self.get_var_value(State.rows[State.selected]) # raises
There is also no way to go the other direction and set the value such a var points at. Code that receives a var for a nested value has to take the var apart itself to find the field and the attribute names, as an admin/form library does when a form field is bound to State.instance.address.city. That means reading private var internals: ObjectItemOperation._object/._key, ToOperation._original, and for array indexing the _args of an anonymous CustomVarOperation, found by matching the name of the first parameter of array_item_operation.
This PR adds the pieces for that:
ArrayItemOperation: indexing anArrayVarbuilds a dataclass operation with_arrayand_index, the counterpart ofObjectItemOperation, instead of going through@var_operation. The rendered JS (array?.at?.(index)), the item type and the var data are the same. Building it skips thevar_operationwrapper and is about 40% faster (3.85 → 2.19 µs per index on my machine), which matters because indexing is the hot operation in a foreach body.reflex_base.vars.object.var_access_path(var)splits a var into the var it reads from and the keys it reads on the way:State.user.tags[0]→ (theuserfield var,("tags", 0)). It follows attribute access, item access and array indexing through any casts. A literal key comes back as its Python value, any other key as its var. Any other operation ends the walk, soState.a + State.bis its own root with no keys.get_var_valueresolves such vars: it resolves the root as before (from its own var data, so #6629 stays fixed), then reads each key the way optional chaining does on the frontend. A missing key or aNoneon the way reads asNone. An index reads the itemArray.prototype.atreads, so a fractional one is truncated toward zero. A set reads in the order the frontend gets it: sorted where it can be in a literal, which renders it that way, and in its own order in state, which serializes it that way. A key that is itself a var is resolved first, soState.rows[State.selected]works, also across states. A literal root resolves without any state, and a var a literal holds resolves to its value.set_var_value(var, value)is the counterpart. A nested value is set through the field'sMutableProxy, which marks the field dirty, so the change reaches the frontend like any other mutation in a handler. It raises a newUnsettableVarValueErrorfor a computed var, a var not associated with any state (likeState.a + State.b), when the object to set the value on isNone, when it is not tracked for changes (an object inside a tuple, which noMutableProxywraps), for an index past either end, and for item assignment on a set. These are all checked before the write, becauseMutableProxymarks the field dirty before it assigns.
first_tag = await self.get_var_value(OtherState.user.tags[0])
await self.set_var_value(OtherState.user.tags[0], "featured")
Behavior change: get_var_value(State.items[0]) and get_var_value(State.mapping["a"]) used to raise UnretrievableVarValueError (the #6629 regression test pinned that). Now they return the value they read. Arithmetic and other operations still raise. array_item_operation is gone from reflex_base.vars.sequence: it was an undocumented module-level helper, and ArrayVar.__getitem__ was its only caller.
Open question: is set_var_value welcome as public API? The other three pieces work without it, but an admin or form library is the main user of var_access_path, and without set_var_value each such library has to reimplement walking the path and writing through the proxy.
Performance: tests/benchmarks/test_var_value.py benchmarks get_var_value and set_var_value on a plain field, an attribute read through an array item, a read whose index is a var, and the matching writes (1,000 per measured call). Uninstrumented on my machine: a plain field read takes 1.42 µs, down from 1.66 µs before this PR, a nested read 7.5 µs, a read with a var index 8.9 µs, a nested write 7.1 µs. About 40% of a nested read is MutableProxy wrapping each object on the way. I kept that: a nested read hands back the same tracked object as self.user.tags in a handler, and the write needs the proxy to mark the field dirty and to enforce the lock in background tasks. Literal keys are not awaited, and _read_key tests the class a proxy wraps, so it skips the failed check of the proxy's own type that isinstance makes first.
reflex now requires reflex-base >= 0.11.1.dev0, following "Sibling dependency floors". MutableProxy.__setitem__ and __delitem__ now take key: Any, as __getitem__ already did: they were annotated str, which a list index is not.
Docs: the get_var_value section in docs/state_structure/overview.md now covers nested vars and set_var_value. News fragments for reflex and reflex-base.
Tests: var_access_path in tests/units/reflex_base/vars/test_object.py (attribute, item and index access through casts, keys that are vars, other operations as roots), index rendering for int, bool and var indexes in test_sequence.py, nested reads in test_get_var_value_reads_into_fields (attributes, int and str keys, negative indexes, var keys, a literal root and the vars it holds, missing keys, another state), test_set_var_value / test_set_var_value_rejects_what_it_cannot_set (root and nested writes with the exact dirty vars, another state, each error with its full message), all against the in-process, disk and redis state managers, test_var_value_through_tuples_and_sets (including literal versus state set order) and test_var_value_indexes_like_array_at (fractional, negative, NaN and infinite indexes, and a write past the end that leaves nothing dirty). ArrayItemOperation is registered in test_get_leaf_vars_sorts_every_cached_operation. The unit suite passes; ruff and pyright are clean.
🤖 Generated with Claude Code