mapping

Module nu.domains.shape.mapping.

Mapping family: a key-value collection in a shape fabric.

Forms weave the Python mapping surface with the shape collection ops, tier by tier, and type every result by what the slot declared: a value reads as the declared value's form, and keys, values, items and whole-mapping results carry the declared types on.

Refs add descent. ref[key] is the child ref at that key, built by the fabric from the declared value, because only the fabric knows which of its refs holds that value.

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 here and routes through _wrap_item_ref, the one hook that returns a ref rather than a form. It is a substrate plug-point on StructuredRef: the child is always a fabric's own ref, so the fabric's substrate base supplies it, and a fabric that leaves it out fails loudly.

Methods

`a[key]`

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

Builds StructuredRef.

Arguments

Name	Type	Default	Meaning
`key`	`object`

Undocumented: example.

Inherited methods

From nu.domains.shape.mapping.MappingForm:

Call	Builds	Meaning
`.iter()`	`Iterator`	A lazy stream over its keys, typed by the declared key.

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, like Python's dict `\|`.

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.container.ContainerForm:

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

From nu.domains.shape.collection.CollectionForm:

Call	Builds	Meaning
`.exists()`	`Bool`	Whether this collection slot holds a value, as a `Bool`.
`.missing()`	`Bool`	Whether this slot holds no value, as a `Bool`: the negation of `exists()`.

From nu.lang.forms.Form:

Call	Builds	Meaning
`a == b`	`Bool`	Self equal to other by value: an `Eq` term, never a Python bool.
`a != b`	`Bool`	Self not equal to other by value: a `Ne` term, never a Python bool.
`.is_empty()`	`Bool`	True if this Form yields the EMPTY sentinel.
`.not_empty()`	`Bool`	True if this Form does not yield EMPTY.
`.fallback(*alternatives)`	`Self`	The first of this value and `alternatives` that is not EMPTY.

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, like Python's dict `\|=`.
`.clear()`	`Any`	Remove all entries: mapping.clear().

From nu.domains.shape.mapping.MappingRef:

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

From nu.domains.shape.mapping.MappingForm:

Call	Builds	Meaning
`.iter()`	`Iterator`	A lazy stream over its keys, typed by the declared key.

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, like Python's dict `\|`.

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.container.ContainerForm:

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

From nu.domains.shape.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.collection.CollectionForm:

Call	Builds	Meaning
`.exists()`	`Bool`	Whether this collection slot holds a value, as a `Bool`.
`.missing()`	`Bool`	Whether this slot holds no value, as a `Bool`: the negation of `exists()`.

From nu.lang.forms.Form:

Call	Builds	Meaning
`a == b`	`Bool`	Self equal to other by value: an `Eq` term, never a Python bool.
`a != b`	`Bool`	Self not equal to other by value: a `Ne` term, never a Python bool.
`.is_empty()`	`Bool`	True if this Form yields the EMPTY sentinel.
`.not_empty()`	`Bool`	True if this Form does not yield EMPTY.
`.fallback(*alternatives)`	`Self`	The first of this value and `alternatives` that is not EMPTY.

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, like Python's dict `\|=`.
`.clear()`	`Any`	Remove all entries: mapping.clear().

From nu.domains.shape.mapping.MappingRef:

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

From nu.domains.shape.mapping.MappingForm:

Call	Builds	Meaning
`.iter()`	`Iterator`	A lazy stream over its keys, typed by the declared key.

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, like Python's dict `\|`.

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.container.ContainerForm:

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

From nu.domains.shape.collection.ReactiveCollectionForm:

Call	Builds	Meaning
`.on_child_change(address)`	`OnChildChange`	Observe writes at one child's own address; for its subtree use `on_descendants_change`.
`.on_children_change()`	`OnChildrenChange`	Observe writes at the direct children only; for subtrees use `on_descendants_change`.
`.on_descendants_change()`	`OnDescendantsChange`	Observe changes across descendants matching `pattern`.

From nu.domains.shape.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.collection.CollectionForm:

Call	Builds	Meaning
`.exists()`	`Bool`	Whether this collection slot holds a value, as a `Bool`.
`.missing()`	`Bool`	Whether this slot holds no value, as a `Bool`: the negation of `exists()`.

From nu.lang.forms.Form:

Call	Builds	Meaning
`a == b`	`Bool`	Self equal to other by value: an `Eq` term, never a Python bool.
`a != b`	`Bool`	Self not equal to other by value: a `Ne` term, never a Python bool.
`.is_empty()`	`Bool`	True if this Form yields the EMPTY sentinel.
`.not_empty()`	`Bool`	True if this Form does not yield EMPTY.
`.fallback(*alternatives)`	`Self`	The first of this value and `alternatives` that is not EMPTY.

Undocumented: example.

mapping

MappingRef

a[key]

MutableMappingRef

ReactiveMappingRef

On this page

`a[key]`