refs.containers

Module nu.mem.refs.containers.

mem containers: collections whose elements each get an address of their own.

A container slot declares the value it holds, and that declaration types it throughout. Descent (ref[k], ref[i], ref.field) lands on the mem ref for the declared value, and every value an op reads is that value's form. A container reads as the live object held in the data dict.

DictRef

A mapping slot in the dict substrate, holding one plain dict of values.

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

Path nu.mem.DictRef. Kind Ref, sort ref, cardinality scalar.

Subscripting descends rather than reads: ref[k] is a ref at that key inside the stored dict, settable and erasable on its own. The declared value picks it: a core Python type lands on its mem leaf (int on IntRef), a Shape on a ShapeRef for that shape, a mem leaf class on itself, and anything else, a standard-library type included, on ObjectRef. The mapping calls (keys, items, update, ...) act on the dict as a whole.

Notes

• The stored value is an ordinary dict and a read hands back that live object, so a mutation through the ref is visible to anyone else holding it.
• Value reads (get_item, pop, setdefault) are the declared value's form, and values, items and copy carry the declared types on.
• Writing through a key creates the dict and every level above it; the in-place calls instead read the container first and do nothing while the slot is absent, so set an empty dict before the first set_item.
• The declared types shape the refs and forms; nothing coerces or rejects what is written.

Example

class Port(nu.Shape):
    meta = nu.DictRef.slot(int)
data = {"meta": {"a": 1}}
ctx = nu.Context().bind(dict, data, Port)
_ = nu.run(Port.meta["b"].set(2), ctx)
nu.run(Port.meta["b"] + 1, ctx)[0]
nu.run(Port.meta.len(), ctx)[0]

3
2

Methods

.iter()

A lazy stream over the keys, each the declared key's form.

Builds Iterator[K].

Undocumented: example.

a[key]

The mem ref for the declared value at key.

Builds StructuredRef.

Arguments

Undocumented: example.

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

From nu.domains.shape.collection.MutableCollectionForm:

From nu.domains.shape.collection.CollectionForm:

From nu.lang.forms.Form:

ListRef

A sequence slot in the dict substrate, holding one plain list of values.

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

Path nu.mem.ListRef. Kind Ref, sort ref, cardinality scalar.

Subscripting with an int descends rather than reads: ref[i] is the mem ref for the declared value at that index, settable and erasable on its own, picked as on a DictRef. A slice instead routes to the sequence-level slice call and yields a new list.

Notes

• The stored value is an ordinary list and a read hands back that live object, so a mutation through the ref is visible to anyone else holding it.
• Element reads (first_elem, pop) are the declared value's form; a slice is a List carrying the declared type on.
• In-place calls read the container first and do nothing when the slot is absent, so set an empty list before the first append.
• An index past the end reads EMPTY rather than raising, like any other broken path.

Example

class Port(nu.Shape):
    tags = nu.ListRef.slot(str)
data = {"tags": ["a"]}
ctx = nu.Context().bind(dict, data, Port)
_ = nu.run(Port.tags.append("b"), ctx)
nu.run(Port.tags[1].upper(), ctx)[0]
data

'B'
{'tags': ['a', 'b']}

Methods

.iter()

A lazy stream over the elements, each the declared value's form.

Builds Iterator[T].

Undocumented: example.

a[key]

The mem ref for the declared value at index; a slice is a List.

Builds StructuredRef.

Arguments

Undocumented: example.

Inherited methods

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

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

From nu.domains.shape.collection.MutableCollectionForm:

From nu.domains.shape.collection.CollectionForm:

From nu.lang.forms.Form:

SetRef

A set slot in the dict substrate, holding one plain set of values.

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

Path nu.mem.SetRef. Kind Ref, sort ref, cardinality scalar.

No descent: a set has no addresses, so there is no child ref to navigate to. Everything happens through the set calls - membership, the algebra (union, difference, ...), and the in-place mutations.

Notes

• The stored value is an ordinary set and a read hands back that live object, so elements must be hashable and iteration order is whatever Python gives.
• The declared value types what comes out: pop is its form, and the set algebra yields a Set carrying it on.
• In-place calls read the container first and do nothing when the slot is absent, so set an empty set before the first add.

Example

class Port(nu.Shape):
    members = nu.SetRef.slot(str)
ctx = nu.Context().bind(dict, {"members": {"a"}}, Port)
_ = nu.run(Port.members.add("b"), ctx)
sorted(nu.run(Port.members, ctx)[0])

['a', 'b']

Methods

.iter()

A lazy stream over the elements, each the declared value's form.

Builds Iterator[T].

Undocumented: example.

Inherited methods

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

From nu.domains.shape.collection.MutableCollectionForm:

From nu.domains.shape.collection.CollectionForm:

From nu.lang.forms.Form:

ShapeRef

A nested Shape slot in the dict substrate, stored as an inner dict.

ShapeRef(address, shape_type, parent_ref=None, owner_shape=None)

Path nu.mem.ShapeRef. Kind Ref, sort ref, cardinality scalar.

Attribute access descends: ref.field resolves the named slot on the held Shape class and hands back that field's own ref, parented here, so dot chains navigate arbitrarily deep before anything is read. The mapping calls on the ref itself act on the inner dict as a whole.

Notes

• The inner dict does not have to exist first: writing through a field creates every level on the way down.
• Nothing enforces the Shape: keys the class never declared can sit in the same dict and are read only through the mapping calls.

Example

class Order(nu.Shape):
    symbol = nu.StrRef.slot()
class Book(nu.Shape):
    best = nu.ShapeRef.slot(Order)
data = {}
ctx = nu.Context().bind(dict, data, Book)
_ = nu.run(Book.best.symbol.set("AAPL"), ctx)
data

{'best': {'symbol': 'AAPL'}}

Inherited methods

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

From nu.domains.shape.shape.ShapeRef:

From nu.domains.shape.mapping.MappingForm:

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

From nu.domains.shape.collection.MutableCollectionForm:

From nu.domains.shape.collection.CollectionForm:

From nu.lang.forms.Form: