mapping

Module nu.forms.collections.abc.mapping.

Mapping collection: bases + mutations.

MappingForm = Collection + keys/values/items/get_item MutableMappingForm = Mapping + set_item/del_item/update/pop/popitem/setdefault/clear

Follows Python's collections.abc.Mapping / MutableMapping pattern.

MappingForm

Base for mapping values: key lookup plus key/value/item views.

MappingForm()

Path nu.forms.collections.abc.MappingForm.

Notes

• The five _wrap_* methods are the override seam: _wrap_value_result covers subscript and get_item; the other four cover collection-shaped results (keys, values, items, copy, merge). A concrete mapping Form overrides all five to pick its own result types.

Methods

a[key]

Value at key: mapping[key].

Builds ValueResultT.

Arguments

Yields

The value at key. EMPTY when self or key is EMPTY.

Notes

• Raises at evaluation time when key is missing, matching Python's dict[key]. Use get_item for a default instead of a raise.

Example

nu.run(nu.Dict({"a": 1})["a"])[0]

1

.keys()

All keys of the mapping: mapping.keys().

Builds CollectionResultT.

Yields

A view over the keys, in insertion order. EMPTY when self is EMPTY.

Example

nu.run(nu.Dict({"a": 1, "b": 2}).keys())[0]

dict_keys(['a', 'b'])

.values()

All values of the mapping: mapping.values().

Builds CollectionResultT.

Yields

A view over the values, in insertion order. EMPTY when self is EMPTY.

Example

nu.run(nu.Dict({"a": 1, "b": 2}).values())[0]

dict_values([1, 2])

.items()

All (key, value) pairs of the mapping: mapping.items().

Builds CollectionResultT.

Yields

A view over the (key, value) pairs, in insertion order. EMPTY when self is EMPTY.

Example

nu.run(nu.Dict({"a": 1, "b": 2}).items())[0]

dict_items([('a', 1), ('b', 2)])

.get_item(key, default=None)

Value at key, falling back to default: mapping.get_item(key, default).

Builds ValueResultT.

Arguments

Yields

The value at key, or default when key is missing and default is given. EMPTY when self or key is EMPTY.

Notes

• Omitting default does not make a missing key safe: with no default this behaves like mapping[key] and raises at evaluation time on a missing key. Pass a default to get Python dict.get-style fallback behaviour instead.

Examples

nu.run(nu.Dict({"a": 1}).get_item("a"))[0]

1

nu.run(nu.Dict({"a": 1}).get_item("b", 0))[0]

0

.copy()

Shallow copy of self: mapping.copy().

Builds CollectionResultT.

Yields

A new mapping with the same key/value pairs. EMPTY when self is EMPTY.

Example

nu.run(nu.Dict({"a": 1}).copy())[0]

{'a': 1}

.reversed_keys()

Keys in reverse insertion order: reversed(mapping).

Builds CollectionResultT.

Yields

An iterator over the keys, reversed. EMPTY when self is EMPTY.

Example

list(nu.run(nu.Dict({"a": 1, "b": 2}).reversed_keys())[0])

['b', 'a']

.reversed_values()

Values in reverse insertion order: reversed(mapping.values()).

Builds CollectionResultT.

Yields

An iterator over the values, reversed. EMPTY when self is EMPTY.

Example

list(nu.run(nu.Dict({"a": 1, "b": 2}).reversed_values())[0])

[2, 1]

.reversed_items()

(key, value) pairs in reverse insertion order: reversed(mapping.items()).

Builds CollectionResultT.

Yields

An iterator over the (key, value) pairs, reversed. EMPTY when self is EMPTY.

Example

list(nu.run(nu.Dict({"a": 1, "b": 2}).reversed_items())[0])

[('b', 2), ('a', 1)]

.merge(other)

Self and other merged into a new mapping, like Python's dict |.

Builds CollectionResultT.

Arguments

Yields

A new mapping holding self's entries overridden by other's. EMPTY when self or other is EMPTY.

Example

nu.run(nu.Dict({"a": 1}).merge({"b": 2}))[0]

{'a': 1, 'b': 2}

Inherited methods

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:

From builtins.object:

Undocumented: example.

MutableMappingForm

Base for mutable mapping values: adds in-place writes over MappingForm.

MutableMappingForm()

Path nu.forms.collections.abc.MutableMappingForm.

Notes

• set_item, del_item, update, and clear are Commands: they mutate slot 0 and yield nothing. Running them needs a Ref in slot 0, not a plain literal mapping.
• pop, popitem, setdefault, and merge_update are Actions: they mutate and yield a value.

Methods

.set_item(key, value)

Set the value at key, inserting the key if it's missing: mapping[key] = value.

Builds Any.

Arguments

Notes

• Mutating Command: mutates slot 0 in place, yields nothing. Needs a Ref in slot 0 to run; a plain literal mapping fails evaluation.

Example

d.set_item("b", 2)

.del_item(key)

Delete the entry at key: del mapping[key].

Builds Any.

Arguments

Notes

• Mutating Command: mutates slot 0 in place, yields nothing. Needs a Ref in slot 0 to run; a plain literal mapping fails evaluation.

Example

d.del_item("a")

.update(other)

Write other's entries into self, in place: mapping.update(other).

Builds Any.

Arguments

Notes

• Mutating Command: mutates slot 0 in place, yields nothing. Needs a Ref in slot 0 to run; a plain literal mapping fails evaluation.

Example

d.update({"b": 2})

.pop(key, default=None)

Remove key and yield its value, or default if key is missing.

Builds ValueResultT.

Arguments

Yields

The removed value, or default when key is missing. EMPTY when key is missing and no default is given.

Notes

• Mutates slot 0 (removes the entry) and yields a value: an Action, not a Command.
• Without a default, a missing key yields EMPTY rather than raising - unlike __getitem__/get_item with no default, which raise.
• An EMPTY self or key raises, as any write does.

Examples

nu.run(nu.Dict({"a": 1}).pop("a"))[0]

1

nu.run(nu.Dict({"a": 1}).pop("b", 0))[0]

0

.popitem()

Remove and yield an arbitrary (key, value) pair: mapping.popitem().

Builds ValueResultT.

Yields

The removed (key, value) pair. EMPTY when self has no entries. An EMPTY self raises, as any write does.

Notes

• Mutates slot 0 (removes the entry) and yields a value: an Action, not a Command.
• Removes in LIFO order, matching Python's dict.popitem.

Example

nu.run(nu.Dict({"a": 1, "b": 2}).popitem())[0]

('b', 2)

.setdefault(key, default=None)

Value at key, inserting default there first if key is missing.

Builds ValueResultT.

Arguments

Yields

The value already at key, or default once inserted. EMPTY when self or key is EMPTY.

Notes

• Mutates slot 0 (inserts the entry when key is missing) and yields a value: an Action, not a Command.
• Self is unchanged when key is already present; default is only inserted on a miss.

Examples

nu.run(nu.Dict({"a": 1}).setdefault("a", 9))[0]

1

nu.run(nu.Dict({"a": 1}).setdefault("b", 9))[0]

9

.merge_update(other)

Merge other into self in place, and yield self, like Python's dict |=.

Builds CollectionResultT.

Arguments

Yields

Self, updated with other's entries. EMPTY when self or other is EMPTY.

Notes

• Mutates slot 0 in place and yields the mutated mapping: an Action, not a Command, mirroring Python's dict.__ior__.

Example

nu.run(nu.Dict({"a": 1}).merge_update({"b": 2}))[0]

{'a': 1, 'b': 2}

.clear()

Remove all entries: mapping.clear().

Builds Any.

Notes

• Mutating Command: mutates slot 0 in place, yields nothing. Needs a Ref in slot 0 to run; a plain literal mapping fails evaluation.

Example

d.clear()

Inherited methods

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:

From builtins.object:

Undocumented: example.

ReactiveMappingForm

Reactive mapping: adds any-change observation over MutableMappingForm.

ReactiveMappingForm()

Path nu.forms.collections.abc.ReactiveMappingForm.

Notes

• The three tree-aware observers (on_child_change, on_children_change, on_descendants_change) are shape-domain and live on nu.domains.shape.collection.ReactiveCollectionForm, not here.

Methods

.on_change()

Subscribe to any change on this mapping slot.

Builds object.

Yields

A subscription/stream over change events. Needs a live reactive fabric to run.

Notes

• Fires on any mutation to this slot - set_item, del_item, update, pop, popitem, setdefault, merge_update, clear - without distinguishing which one.

Example

d.on_change()

Inherited methods

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:

From builtins.object:

Undocumented: example.