feat: get_var_value and set_var_value for vars reading into a state var

BE
3h ago
+692-75

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 an ArrayVar builds a dataclass operation with _array and _index, the counterpart of ObjectItemOperation, 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 the var_operation wrapper 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] → (the user field 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, so State.a + State.b is its own root with no keys.
  • get_var_value resolves 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 a None on the way reads as None. An index reads the item Array.prototype.at reads, 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, so State.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's MutableProxy, which marks the field dirty, so the change reaches the frontend like any other mutation in a handler. It raises a new UnsettableVarValueError for a computed var, a var not associated with any state (like State.a + State.b), when the object to set the value on is None, when it is not tracked for changes (an object inside a tuple, which no MutableProxy wraps), for an index past either end, and for item assignment on a set. These are all checked before the write, because MutableProxy marks 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