hydra.overlay.python.util.cons_list module

Persistent (immutable) sequence backed by a native tuple.

Mirrors hydra.util.ConsList from Hydra-Java. Implements collections.abc.Sequence so a ConsList IS a Sequence. Public APIs can stay typed as Sequence[E] while internals get C-speed indexing, iteration, and concatenation.

This implementation uses a native tuple as the backing store, with a _start offset marking the logical beginning of the list within that tuple. head/tail/drop are O(1): tail shares the same backing tuple with _start incremented, no copy. cons (prepend) is still O(n) by design – in codegen-heavy workloads, the dominant cost turned out to be allocation per cell in a linked-list version, so the tuple copy wins despite the asymptotic loss for prepend.

class hydra.overlay.python.util.cons_list.ConsList(_inner: tuple[Any, ...] | None = None, _start: int = 0, *, _internal: bool = False)

Bases: Sequence[T], Generic[T]

A persistent (immutable) sequence backed by a native tuple plus offset.

Construct via ConsList.empty(), ConsList.cons(x, xs), ConsList.singleton(x), ConsList.of(...), or ConsList.from_iterable(...). Direct __init__ is gated.

concat(other: ConsList[T]) → ConsList[T]

static cons(value: T, tail: ConsList[T]) → ConsList[T]

drop(n: int) → ConsList[T]

static empty() → ConsList[Any]

filter(predicate: Callable[[T], bool]) → ConsList[T]

foldl(f: Callable[[R, T], R], initial: R) → R

foldr(f: Callable[[T, R], R], initial: R) → R

static from_iterable(values: Iterable[T]) → ConsList[T]

property head: T

init() → ConsList[T]

is_empty() → bool

last() → T

map(f: Callable[[T], U]) → ConsList[U]

static of(*elements: T) → ConsList[T]

reverse() → ConsList[T]

static singleton(value: T) → ConsList[T]

property tail: ConsList[T]

take(n: int) → ConsList[T]