hydra.overlay.python.util.persistent_map module

Persistent ordered map backed by a frozen dict (CPython C dict).

Mirrors hydra.util.PersistentMap from Hydra-Java. Iteration via keys() / values() / items() / __iter__ is in key-sorted order (Haskell semantics), achieved by sorting at iteration time using hydra.overlay.python.util._compare.compare.

This implementation uses a native dict as the backing store. Mutating methods (insert / delete / union / map_values / etc.) build a fresh dict and freeze it via _internal=True. Native dict operations are C-speed; the cost is O(n) copy on every mutation rather than O(log n) HAMT structure sharing.

Sorting is done with _compare.compare so that keys without a natural < (Hydra Term / Type / dataclasses) still get a deterministic order.

class hydra.overlay.python.util.persistent_map.PersistentMap(_inner: dict[Any, Any] | None = None, *, _internal: bool = False)

Bases: Mapping[K, V], Generic[K, V]

A persistent (immutable) map backed by a frozen native dict.

Construct via PersistentMap.empty(), PersistentMap.singleton(k, v), PersistentMap.from_pairs(...), or PersistentMap.from_mapping(...).

alter(f: Callable[[Any], Any], key: K) → PersistentMap[K, V]

bimap(fk: Callable[[K], K2], fv: Callable[[V], V2]) → PersistentMap[K2, V2]

contains_key(key: K) → bool

delete(key: K) → PersistentMap[K, V]

static empty() → PersistentMap[Any, Any]

filter(predicate: Callable[[V], bool]) → PersistentMap[K, V]

filter_with_key(predicate: Callable[[K, V], bool]) → PersistentMap[K, V]

fold(f: Callable[[R, K, V], R], initial: R) → R

static from_mapping(source: Mapping[K, V]) → PersistentMap[K, V]

static from_pairs(pairs: Iterable[tuple[K, V]]) → PersistentMap[K, V]

insert(key: K, value: V) → PersistentMap[K, V]

is_empty() → bool

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

keys_list() → list[K]

lookup(key: K) → Any | None

map_keys(f: Callable[[K], K2]) → PersistentMap[K2, V]

map_values(f: Callable[[V], V2]) → PersistentMap[K, V2]

static of_entries(*entries: tuple[K, V]) → PersistentMap[K, V]

static singleton(key: K, value: V) → PersistentMap[K, V]

to_list() → list[tuple[K, V]]

union(other: PersistentMap[K, V]) → PersistentMap[K, V]

Left-biased union: entries in self win on key collision.

Implemented as {**other._inner, **self._inner}: build other first, then overlay self → self values overwrite other on collision (left-biased). Pure C-speed, no Python-level loop.

values() → an object providing a view on D's values

values_list() → list[V]