refs.primitives

Module nustd.kv.refs.primitives.

virtuals-substrate refs for whole-blob compound values.

Unlike the decomposing container refs (ListRef / DictRef / SetRef, which fan a container out into per-element storage), these write the whole container as one opaque value via ItemPrimitiveSetCmd and read it back as a plain Python object. Each mixes in the matching collection Form, so the value still carries the full list / dict / tuple / set interface.

Use for opaque or heterogeneous containers that should round-trip whole rather than shape-decompose (log lines, raw account blobs, balance arrays, ...).

PrimitiveDictRef

A dict leaf in KV storage, written and read back whole as one blob.

PrimitiveDictRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.PrimitiveDictRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Stored as one opaque value, so the keys get no addresses of their own and cannot be reached or watched individually.
• Reads come back as a real Python dict, nested contents included.
• The write path is set with a whole dict. The key-level mutations inherited from the Dict surface (set_item, pop, update, ...) do not reach the stored blob and leave it as it was, without raising.
• DictRef is the other choice: it decomposes into per-key storage and gives per-key navigation and change observation.

Example

class Bag(Shape):
    meta = PrimitiveDictRef.slot()
run(Bag.meta.set({"a": 1, "b": [2, 3]}), ctx)
run(Bag.meta, ctx)

Methods

.set(value)

Store the whole dict as one leaf value.

Builds object.

Arguments

Yields

Nothing. It is a command, run for the write.

Notes

• Overrides the decomposing slot write, so the dict lands as one opaque value with no per-key children underneath it.
• Replaces whatever was there; keys already stored are not merged in.

Example

run(Bag.meta.set({"a": 1}), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.forms.collections.dict_.Dict:

From nu.forms.collections.abc.mapping.MutableMappingForm:

From nu.forms.collections.abc.mapping.MappingForm:

From nu.forms.collections.abc.collection.CollectionForm:

From nu.forms.collections.abc.sized.SizedForm:

From nu.forms.collections.abc.iterable.IterableForm:

From nu.forms.collections.abc.container.ContainerForm:

From nu.lang.forms.Form:

PrimitiveFrozenSetRef

A frozenset leaf in KV storage, written and read back whole as one blob.

PrimitiveFrozenSetRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.PrimitiveFrozenSetRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Reads come back as a real Python frozenset, so the type survives the round trip.
• Carries the read-only set surface only: union, intersection and the rest yield new values and never touch storage.
• Has no decomposing counterpart; a frozenset slot is always stored whole.

Example

class Bag(Shape):
    locked = PrimitiveFrozenSetRef.slot()
run(Bag.locked.set(frozenset({1, 2})), ctx)
run(Bag.locked, ctx)

Methods

.set(value)

Store the whole frozenset as one leaf value.

Builds object.

Arguments

Yields

Nothing. It is a command, run for the write.

Notes

• Replaces whatever was there.

Example

run(Bag.locked.set(frozenset({1, 2})), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.forms.collections.set_.FrozenSet:

From nu.forms.collections.abc.set_.SetLikeForm:

From nu.forms.collections.abc.collection.CollectionForm:

From nu.forms.collections.abc.sized.SizedForm:

From nu.forms.collections.abc.iterable.IterableForm:

From nu.forms.collections.abc.container.ContainerForm:

From nu.lang.forms.Form:

PrimitiveListRef

A list leaf in KV storage, written and read back whole as one blob.

PrimitiveListRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.PrimitiveListRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Stored as one opaque value, so the elements get no addresses of their own and cannot be reached or watched individually.
• Reads come back as a real Python list, so heterogeneous and nested contents round-trip as they were written.
• The write path is set with a whole list. The element-level mutations inherited from the List surface (append, insert, del_at, ...) do not reach the stored blob and leave it as it was, without raising.
• ListRef is the other choice: it decomposes into per-index storage and gives per-element navigation.

Example

class Bag(Shape):
    rows = PrimitiveListRef.slot()
run(Bag.rows.set([1, "two", {"three": 3}]), ctx)
run(Bag.rows, ctx)

Methods

.set(value)

Store the whole list as one leaf value.

Builds object.

Arguments

Yields

Nothing. It is a command, run for the write.

Notes

• Overrides the decomposing slot write, so the list lands as one opaque value with no per-index children underneath it.
• Replaces whatever was there; there is no merge with the value already stored.

Example

run(Bag.rows.set([1, "two"]), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.forms.collections.list_.List:

From nu.forms.collections.abc.sequence.MutableSequenceForm:

From nu.forms.collections.abc.sequence.SequenceForm:

From nu.forms.collections.abc.collection.CollectionForm:

From nu.forms.collections.abc.sized.SizedForm:

From nu.forms.collections.abc.iterable.IterableForm:

From nu.forms.collections.abc.container.ContainerForm:

From nu.forms.collections.abc.sliceable.SliceableForm:

From nu.lang.forms.Form:

PrimitiveSetRef

A set leaf in KV storage, written and read back whole as one blob.

PrimitiveSetRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.PrimitiveSetRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Reads come back as a real Python set, so membership and the set operators work on the value as they would in Python.
• The write path is set with a whole set. The element-level mutations inherited from the Set surface (add, discard, update, ...) do not reach the stored blob and leave it as it was, without raising.
• SetRef is the other choice: it decomposes into per-element storage and gives change observation.

Example

class Bag(Shape):
    members = PrimitiveSetRef.slot()
run(Bag.members.set({1, 2, 3}), ctx)
run(Bag.members, ctx)

Methods

.set(value)

Store the whole set as one leaf value.

Builds object.

Arguments

Yields

Nothing. It is a command, run for the write.

Notes

• Replaces whatever was there; it is not a union with the set already stored.

Example

run(Bag.members.set({1, 2}), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.forms.collections.set_.Set:

From nu.forms.collections.abc.set_.MutableSetForm:

From nu.forms.collections.abc.set_.SetLikeForm:

From nu.forms.collections.abc.collection.CollectionForm:

From nu.forms.collections.abc.sized.SizedForm:

From nu.forms.collections.abc.iterable.IterableForm:

From nu.forms.collections.abc.container.ContainerForm:

From nu.lang.forms.Form:

PrimitiveTupleRef

A tuple leaf in KV storage, written and read back whole as one blob.

PrimitiveTupleRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.PrimitiveTupleRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Reads come back as a real Python tuple, so the type survives the round trip rather than degrading to a list.
• Has no decomposing counterpart: a tuple slot is always stored whole.
• Elements get no addresses of their own, so nothing under it can be reached or watched individually.

Example

class Bag(Shape):
    pair = PrimitiveTupleRef.slot()
run(Bag.pair.set((1, "two")), ctx)
run(Bag.pair, ctx)

Methods

.set(value)

Store the whole tuple as one leaf value.

Builds object.

Arguments

Yields

Nothing. It is a command, run for the write.

Notes

• Replaces whatever was there.

Example

run(Bag.pair.set((1, "two")), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.forms.collections.tuple_.Tuple:

From nu.forms.collections.abc.sequence.SequenceForm:

From nu.forms.collections.abc.collection.CollectionForm:

From nu.forms.collections.abc.sized.SizedForm:

From nu.forms.collections.abc.iterable.IterableForm:

From nu.forms.collections.abc.container.ContainerForm:

From nu.forms.collections.abc.sliceable.SliceableForm:

From nu.lang.forms.Form: