refs.mapping

Module nu.domains.shape.refs.mapping.

MappingRef hierarchy: key-value container Ref + Form mixin tiers.

MappingRef = shape.MappingForm + StructuredRef MutableMappingRef = shape.MutableMappingForm + MappingRef ReactiveMappingRef = shape.ReactiveMappingForm + MutableMappingRef

Navigation (ref[key]) is defined ONCE here and routes through the _wrap_item_ref hook: the child-Ref analogue of _wrap_value_result / _wrap_keys_result. Each substrate provides _wrap_item_ref (building its own item Ref) instead of re-overriding __getitem__, and binds the ItemResultT type parameter so ref[key] is statically the correct child Ref type. The blueprint leaves _wrap_item_ref abstract (like the other wrap hooks), so a substrate that forgets it is a loud NotImplementedError, not a silently broken domain Ref.

Name	Sort	Call	Meaning
MappingRef	`ref`	`MappingRef(address, parent_ref=None, owner_shape=None)`	Key-value container Ref; `ref[key]` navigates to the value's child Ref.
MutableMappingRef	`ref`	`MutableMappingRef(address, parent_ref=None, owner_shape=None)`	Mutable key-value container Ref.
ReactiveMappingRef	`ref`	`ReactiveMappingRef(address, parent_ref=None, owner_shape=None)`	Reactive key-value container Ref.

MappingRef

Key-value container Ref; ref[key] navigates to the value's child Ref.

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

Path nu.domains.shape.MappingRef. Kind Ref, sort ref, cardinality scalar.

Navigation is defined ONCE (__getitem__) and routes through _wrap_item_ref: the child-Ref analogue of _wrap_value_result. Each tier supplies the matching domain item Ref as its default; substrates override _wrap_item_ref to return their own substrate-backed item Ref and bind ItemResultT so ref[key] is statically the correct child Ref type.

Methods

`a[key]`

Navigate to the child Ref at key, with self as parent.

Builds ItemResultT.

Arguments

Name	Type	Default	Meaning
`key`	`object`

Undocumented: example.

Inherited methods

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

Call	Builds	Meaning
`.keys()`	`CollectionResultT`	All keys of the mapping: mapping.keys().
`.values()`	`CollectionResultT`	All values of the mapping: mapping.values().
`.items()`	`CollectionResultT`	All (key, value) pairs of the mapping: mapping.items().
`.get_item(key, default=None)`	`ValueResultT`	Value at key, falling back to default: mapping.get_item(key, default).
`.copy()`	`CollectionResultT`	Shallow copy of self: mapping.copy().
`.reversed_keys()`	`CollectionResultT`	Keys in reverse insertion order: reversed(mapping).
`.reversed_values()`	`CollectionResultT`	Values in reverse insertion order: reversed(mapping.values()).
`.reversed_items()`	`CollectionResultT`	(key, value) pairs in reverse insertion order: reversed(mapping.items()).
`.merge(other)`	`CollectionResultT`	Self and other merged into a new mapping: mapping \| other.

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

Call	Builds	Meaning
`.extract()`	`object`	Materialise the full subtree rooted at self.

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

Call	Builds	Meaning
`.len()`	`Int`	Length of self.

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

Call	Builds	Meaning
`iter(a)`	`Iterator[ElementT]`	Open self into a lazy iterator stream (Python's `iter`).

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

Call	Builds	Meaning
`.contains(item)`	`Bool`	Whether item is a member of self.

From nu.domains.shape.forms.collection.CollectionForm:

Call	Builds	Meaning
`.exists()`	`Exists`	Build an `Exists` query.
`.missing()`	`Missing`	Build a `Missing` query.

From nu.lang.forms.Form:

Call	Builds	Meaning
`.is_empty()`	`Bool`	True if this Form yields the EMPTY sentinel.
`.is_invalid()`	`Bool`	True if this Form yields the INVALID sentinel.
`.is_sentinel()`	`Bool`	True if this Form yields either sentinel (EMPTY or INVALID).
`.not_empty()`	`Bool`	True if this Form does not yield EMPTY.
`.not_invalid()`	`Bool`	True if this Form does not yield INVALID.

Undocumented: example.

MutableMappingRef

Mutable key-value container Ref.

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

Path nu.domains.shape.MutableMappingRef. Kind Ref, sort ref, cardinality scalar.

Adds: set(k,v), delete(k), update(), store(v), erase() on top of MappingRef.

Inherited methods

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

Call	Builds	Meaning
`.set_item(key, value)`	`Any`	Set the value at key, inserting the key if it's missing: mapping[key] = value.
`.del_item(key)`	`Any`	Delete the entry at key: del mapping[key].
`.update(other)`	`Any`	Write other's entries into self, in place: mapping.update(other).
`.pop(key, default=None)`	`ValueResultT`	Remove key and yield its value, or default if key is missing.
`.popitem()`	`ValueResultT`	Remove and yield an arbitrary (key, value) pair: mapping.popitem().
`.setdefault(key, default=None)`	`ValueResultT`	Value at key, inserting default there first if key is missing.
`.merge_update(other)`	`CollectionResultT`	Merge other into self in place, and yield self: mapping \|= other.
`.clear()`	`Any`	Remove all entries: mapping.clear().

From nu.domains.shape.refs.mapping.MappingRef:

Call	Builds	Meaning
`a[key]`	`ItemResultT`	Navigate to the child Ref at `key`, with self as parent.

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

Call	Builds	Meaning
`.keys()`	`CollectionResultT`	All keys of the mapping: mapping.keys().
`.values()`	`CollectionResultT`	All values of the mapping: mapping.values().
`.items()`	`CollectionResultT`	All (key, value) pairs of the mapping: mapping.items().
`.get_item(key, default=None)`	`ValueResultT`	Value at key, falling back to default: mapping.get_item(key, default).
`.copy()`	`CollectionResultT`	Shallow copy of self: mapping.copy().
`.reversed_keys()`	`CollectionResultT`	Keys in reverse insertion order: reversed(mapping).
`.reversed_values()`	`CollectionResultT`	Values in reverse insertion order: reversed(mapping.values()).
`.reversed_items()`	`CollectionResultT`	(key, value) pairs in reverse insertion order: reversed(mapping.items()).
`.merge(other)`	`CollectionResultT`	Self and other merged into a new mapping: mapping \| other.

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

Call	Builds	Meaning
`.extract()`	`object`	Materialise the full subtree rooted at self.

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

Call	Builds	Meaning
`.len()`	`Int`	Length of self.

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

Call	Builds	Meaning
`iter(a)`	`Iterator[ElementT]`	Open self into a lazy iterator stream (Python's `iter`).

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

Call	Builds	Meaning
`.contains(item)`	`Bool`	Whether item is a member of self.

From nu.domains.shape.forms.collection.MutableCollectionForm:

Call	Builds	Meaning
`.set(value)`	`SetCmd`	Build a `SetCmd`.
`.erase()`	`Erase`	Build an `Erase`.
`.init(value)`	`IfDo`	Set `value` iff the collection is currently missing.

From nu.domains.shape.forms.collection.CollectionForm:

Call	Builds	Meaning
`.exists()`	`Exists`	Build an `Exists` query.
`.missing()`	`Missing`	Build a `Missing` query.

From nu.lang.forms.Form:

Call	Builds	Meaning
`.is_empty()`	`Bool`	True if this Form yields the EMPTY sentinel.
`.is_invalid()`	`Bool`	True if this Form yields the INVALID sentinel.
`.is_sentinel()`	`Bool`	True if this Form yields either sentinel (EMPTY or INVALID).
`.not_empty()`	`Bool`	True if this Form does not yield EMPTY.
`.not_invalid()`	`Bool`	True if this Form does not yield INVALID.

Undocumented: example.

ReactiveMappingRef

Reactive key-value container Ref.

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

Path nu.domains.shape.ReactiveMappingRef. Kind Ref, sort ref, cardinality scalar.

Adds: on_change() (generic), on_child_change(), on_children_change(), on_descendants_change() (shape-domain) on top of MutableMappingRef.

Inherited methods

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

Call	Builds	Meaning
`.on_change()`	`object`	Subscribe to any change on this mapping slot.

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

Call	Builds	Meaning
`.set_item(key, value)`	`Any`	Set the value at key, inserting the key if it's missing: mapping[key] = value.
`.del_item(key)`	`Any`	Delete the entry at key: del mapping[key].
`.update(other)`	`Any`	Write other's entries into self, in place: mapping.update(other).
`.pop(key, default=None)`	`ValueResultT`	Remove key and yield its value, or default if key is missing.
`.popitem()`	`ValueResultT`	Remove and yield an arbitrary (key, value) pair: mapping.popitem().
`.setdefault(key, default=None)`	`ValueResultT`	Value at key, inserting default there first if key is missing.
`.merge_update(other)`	`CollectionResultT`	Merge other into self in place, and yield self: mapping \|= other.
`.clear()`	`Any`	Remove all entries: mapping.clear().

From nu.domains.shape.refs.mapping.MappingRef:

Call	Builds	Meaning
`a[key]`	`ItemResultT`	Navigate to the child Ref at `key`, with self as parent.

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

Call	Builds	Meaning
`.keys()`	`CollectionResultT`	All keys of the mapping: mapping.keys().
`.values()`	`CollectionResultT`	All values of the mapping: mapping.values().
`.items()`	`CollectionResultT`	All (key, value) pairs of the mapping: mapping.items().
`.get_item(key, default=None)`	`ValueResultT`	Value at key, falling back to default: mapping.get_item(key, default).
`.copy()`	`CollectionResultT`	Shallow copy of self: mapping.copy().
`.reversed_keys()`	`CollectionResultT`	Keys in reverse insertion order: reversed(mapping).
`.reversed_values()`	`CollectionResultT`	Values in reverse insertion order: reversed(mapping.values()).
`.reversed_items()`	`CollectionResultT`	(key, value) pairs in reverse insertion order: reversed(mapping.items()).
`.merge(other)`	`CollectionResultT`	Self and other merged into a new mapping: mapping \| other.

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

Call	Builds	Meaning
`.extract()`	`object`	Materialise the full subtree rooted at self.

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

Call	Builds	Meaning
`.len()`	`Int`	Length of self.

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

Call	Builds	Meaning
`iter(a)`	`Iterator[ElementT]`	Open self into a lazy iterator stream (Python's `iter`).

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

Call	Builds	Meaning
`.contains(item)`	`Bool`	Whether item is a member of self.

From nu.domains.shape.forms.collection.ReactiveCollectionForm:

Call	Builds	Meaning
`.on_child_change(address)`	`OnChildChange`	Observe changes at a specific child address.
`.on_children_change()`	`OnChildrenChange`	Observe changes across all direct children.
`.on_descendants_change()`	`OnDescendantsChange`	Observe changes across descendants matching `pattern`.

From nu.domains.shape.forms.collection.MutableCollectionForm:

Call	Builds	Meaning
`.set(value)`	`SetCmd`	Build a `SetCmd`.
`.erase()`	`Erase`	Build an `Erase`.
`.init(value)`	`IfDo`	Set `value` iff the collection is currently missing.

From nu.domains.shape.forms.collection.CollectionForm:

Call	Builds	Meaning
`.exists()`	`Exists`	Build an `Exists` query.
`.missing()`	`Missing`	Build a `Missing` query.

From nu.lang.forms.Form:

Call	Builds	Meaning
`.is_empty()`	`Bool`	True if this Form yields the EMPTY sentinel.
`.is_invalid()`	`Bool`	True if this Form yields the INVALID sentinel.
`.is_sentinel()`	`Bool`	True if this Form yields either sentinel (EMPTY or INVALID).
`.not_empty()`	`Bool`	True if this Form does not yield EMPTY.
`.not_invalid()`	`Bool`	True if this Form does not yield INVALID.

Undocumented: example.

refs.mapping

MappingRef

a[key]

MutableMappingRef

ReactiveMappingRef

On this page

`a[key]`