transform

Module nu.core.transform.

Transform atoms: Python's iterable-transforming builtins.

Maps Python's builtins that take an iterable and yield another iterable onto Nu Queries. Pure shape over their source; effects only ride in through Ref children.

Builtins covered (Python -> Nu):

• map -> Map, filter -> Filter, sorted -> Sorted

Plus three transforms kept as core: SortBy (ordered by a key expression), Flatten (one-level concat) and Unique (drop already-seen, order preserved).

Map, Filter, SortBy, Flatten and Unique are StreamQueries: stream in, stream out. Sorted is a ScalarQuery, like Python's sorted: ordering must see every item before it yields the first, so it takes an iterable value and yields a list rather than posing as a stream.

Map, Filter and SortBy bind each item into ctx.attrs under a name and evaluate a Nu child against it. The child is usually a lambda over the item (lambda x: x > 1): it runs once, at construction, with a ref to the item and returns the child tree, and the name is minted for it. Given as a plain tree instead, the child reads the item with Attr(<name>) under an explicit name, itself a child (a Literal or a Ref computed elsewhere, never an opaque payload). The item is bound with ctx.attrs.let for the evaluation of that one item, so it shadows an outer name of the same spelling and never outlives the item.

Filter

Keeps the items of a stream child for which a predicate holds (lazy).

Filter(source, predicate, key=None)

Path nu.core.Filter. Kind StreamQuery, sort stream_query, cardinality stream. Arity 3 (2 required).

Arguments

Yields

A stream no longer than source (stream in, stream out), holding the items where predicate held.

Notes

• The same scoped binding, and the same lambda form, as Map.
• An EMPTY predicate result counts as false and drops the item, like any falsy value.
• Pulled lazily, one item at a time.

Examples

nu.run(nu.Collect(nu.Filter(nu.Iter([1, 2, 3, 4]), lambda x: x > 2)))[0]

[3, 4]

The same with the default name:

nu.run(nu.Collect(nu.Filter(nu.Iter([1, 2, 3, 4]), nu.Gt(nu.Attr("item"), 2))))[0]

[3, 4]

Flatten

Concatenates a source of iterables one level into a flat stream (lazy).

Flatten(source)

Path nu.core.Flatten. Kind StreamQuery, sort stream_query, cardinality stream. Arity 1 (1 required).

Arguments

Yields

A stream of every item from every sub-iterable of source, in order (stream in, stream out).

Notes

• Only one level deep - an item that yields more iterables stays nested.
• No sentinel check of its own: an EMPTY sub-item is treated like any other value and raises since it isn't iterable.

Example

nu.run(nu.Collect(nu.Flatten(nu.Iter([[1, 2], [3], [4, 5]]))))[0]

[1, 2, 3, 4, 5]

Map

Applies a query child to every item of a stream child (lazy).

Map(source, transform, key=None)

Path nu.core.Map. Kind StreamQuery, sort stream_query, cardinality stream. Arity 3 (2 required).

Arguments

Yields

A stream the same length as source (stream in, stream out), each item transform's result.

Notes

• The lambda runs once, at construction, and gets a ref, not a value: it builds the tree and never branches on the item in Python.
• The name belongs to the lambda's code: nested lambdas each get their own, while one lambda used again inside its own body shadows the outer binding, as with nu.let. An explicit key keeps both readable.
• key is itself a child (a Literal or a Ref), not a raw string, so it can be computed rather than fixed at write time.
• The binding lasts for that item's transform and is released before the result is yielded, so it never reaches the consumer.
• Pulled lazily, one item at a time; nothing runs ahead of the pull.
• No sentinel check of its own: an EMPTY item, or an EMPTY result from transform, passes straight through as a value rather than collapsing.

Examples

nu.run(nu.Collect(nu.Map(nu.Iter([1, 2, 3]), lambda x: nu.Int(x) + 1)))[0]

[2, 3, 4]

The same with an explicit name:

nu.run(nu.Collect(nu.Map(nu.Iter([1, 2, 3]), nu.Add(nu.Attr("n"), 1), key="n")))[0]

[2, 3, 4]

SortBy

Its source child, ordered by a per-item key expression (eager).

SortBy(source, key, reverse=False, item=None)

Path nu.core.SortBy. Kind StreamQuery, sort stream_query, cardinality stream. Arity 4 (2 required).

Arguments

Yields

A stream holding every item of source, ordered by key (stream in, stream out).

Notes

• The same scoped binding, and the same lambda form, as Map / Filter.
• Drains and sorts the whole source before yielding anything, so a pull on its output waits for the whole source.

Examples

nu.run(nu.Collect(nu.SortBy(nu.Iter(["bb", "a", "ccc"]), lambda s: nu.Len(s))))[0]

['a', 'bb', 'ccc']

The same with the default name:

nu.run(nu.Collect(nu.SortBy(nu.Iter(["bb", "a", "ccc"]), nu.Len(nu.Attr("item")))))[0]

['a', 'bb', 'ccc']

Sorted

Its iterable child collected into an ascending list (sorted).

Sorted(source)

Path nu.core.Sorted. Kind ScalarQuery, sort scalar_query, cardinality scalar. Arity 1 (1 required).

Arguments

Yields

A new list holding every item of source, ascending. EMPTY when the child is EMPTY.

Notes

• Takes an iterable value, like the collection casts. A stream is drained into one first with Collect.
• Items must support ordering against each other.
• An EMPTY item is compared like any other value and raises if it can't be ordered against the rest.

Examples

nu.run(nu.Sorted([3, 1, 2]))[0]

[1, 2, 3]

nu.run(nu.Sorted(nu.Collect(nu.Iter({"b", "a"}))))[0]

['a', 'b']

Unique

Yields each item of a source child once, first-seen order (lazy).

Unique(source)

Path nu.core.Unique. Kind StreamQuery, sort stream_query, cardinality stream. Arity 1 (1 required).

Arguments

Yields

A stream holding each distinct item of source once, in first-seen order (stream in, stream out).

Notes

• Items must be hashable.
• Keeps every distinct item seen so far to check membership, so memory grows with the number of distinct items, not the length of source.
• No sentinel check of its own: an EMPTY item is kept like any other value and only passes through once.

Example

nu.run(nu.Collect(nu.Unique(nu.Iter([1, 2, 1, 3, 2]))))[0]

[1, 2, 3]