nrel.hive.util.dict_ops

Module Contents

Classes

EntityUpdateResult	Typed version of namedtuple.
DictOps

class nrel.hive.util.dict_ops.EntityUpdateResult

Bases: NamedTuple

Typed version of namedtuple.

Usage in Python versions >= 3.6:

class Employee(NamedTuple):
    name: str
    id: int

This is equivalent to:

Employee = collections.namedtuple('Employee', ['name', 'id'])

The resulting class has an extra __annotations__ attribute, giving a dict that maps field names to types. (The field names are also in the _fields attribute, which is part of the namedtuple API.) Alternative equivalent keyword syntax is also accepted:

Employee = NamedTuple('Employee', name=str, id=int)

In Python versions <= 3.5 use:

Employee = NamedTuple('Employee', [('name', str), ('id', int)])

entities: immutables.Map[nrel.hive.util.typealiases.EntityId, nrel.hive.model.entity.Entity] | None

locations: immutables.Map[nrel.hive.util.typealiases.GeoId, FrozenSet[nrel.hive.util.typealiases.EntityId]] | None

search: immutables.Map[nrel.hive.util.typealiases.GeoId, FrozenSet[nrel.hive.util.typealiases.EntityId]] | None

class nrel.hive.util.dict_ops.DictOps

K

V

classmethod iterate_vals(xs: immutables.Map[K, V], key: Callable[[V], _typeshed.SupportsRichComparison] | None = None) → Tuple[V, Ellipsis]

helper function for iterating on Maps in HIVE which sorts values by key unless a key function is provided. for all stateful Map collections that are being iterated on in HIVE, we need to sort them _somehow_ to guarantee deterministic runs.

if no key function is provided, the values are sorted by Map key. if a key function is provided, it takes the value type as input and returns a sortable value.

Parameters:

xs (immutables.Map[K, V]) – collection to iterate values of

Returns:

values of xs, sorted by key

Return type:

Tuple[V, …]

classmethod iterate_items(xs: immutables.Map[K, V], key: Callable[[Tuple[K, V]], _typeshed.SupportsRichComparison] | None = None) → List[Tuple[K, V]]

helper function for iterating on Maps in HIVE which sorts values by key unless a key function is provided. for all stateful Map collections that are being iterated on in HIVE, we need to sort them _somehow_ to guarantee deterministic runs.

Parameters:

xs (immutables.Map[K, V]) – collection to iterate values of

Returns:

values of xs, sorted by key

Return type:

Tuple[V, …]

classmethod iterate_sim_coll(collection: immutables.Map[K, V], filter_function: Callable[[V], bool] | None = None, sort_key: Callable | None = None) → Tuple[V, Ellipsis]

helper to iterate through a collection on the SimulationState with optional sort key function and filter function. performs filter before sort if both are provided.

Parameters:

• collection (immutables.Map[K, V]) – collection on SimulationState

• filter_function (Optional[Callable[[V], bool]], optional) – _description_, defaults to None

• sort_key (Optional[Callable], optional) – _description_, defaults to None

Returns:

_description_

Return type:

Tuple[V, …]

classmethod add_to_dict(xs: immutables.Map[K, V], obj_id: K, obj: V) → immutables.Map[K, V]

updates Dicts for arbitrary keys and values performs a shallow copy and update, treating Dict as an immutable hash table

Parameters:

• xs –

• obj_id –

• obj –

Returns:

classmethod remove_from_dict(xs: immutables.Map[K, V], obj_id: K) → immutables.Map[K, V]

updates Dicts for arbitrary keys and values performs a shallow copy and update, treating Dict as an immutable hash table

Parameters:

• xs –

• obj_id –

Returns:

classmethod merge_dicts(old: immutables.Map[K, V], new: immutables.Map[K, V]) → immutables.Map[K, V]

merges two Dictionaries, replacing old kv pairs with new ones

Parameters:

• old – the old Dict

• new – the new Dict

Returns:

a merged Dict

classmethod add_to_collection_dict(xs: immutables.Map[str, FrozenSet[V]], collection_id: str, obj_id: V) → immutables.Map[str, FrozenSet[V]]

updates Dicts that track collections of entities performs a shallow copy and update, treating Dict as an immutable hash table

Parameters:

• xs –

• collection_id –

• obj_id –

Returns:

classmethod add_to_stack_dict(xs: immutables.Map[str, Tuple[V, Ellipsis]], collection_id: str, obj: V) → immutables.Map[str, Tuple[V, Ellipsis]]

updates Dicts that hold a stack of entities; note that the head of the tuple represents the top of the stack; elements always get inserted into the head; performs a shallow copy and update, treating Dict as an immutable hash table

Parameters:

• xs –

• collection_id –

• obj_id –

Returns:

classmethod pop_from_stack_dict(xs: immutables.Map[str, Tuple[V, Ellipsis]], collection_id: str) → Tuple[V | None, immutables.Map[str, Tuple[V, Ellipsis]]]

pops an element from the stack and returns it; note that the head of the tuple represents the top of the stack; popped elements come from the tuple head; performs a shallow copy and update, treating Dict as an immutable hash table

Parameters:

• xs –

• collection_id –

• obj_id –

Returns:

classmethod remove_from_collection_dict(xs: immutables.Map[str, FrozenSet[V]], collection_id: str, obj_id: str) → immutables.Map[str, FrozenSet[V]]

updates Dicts that track collections of entities performs a shallow copy and update, treating Dict as an immutable hash table when a geoid has no ids after a remove, it deletes that geoid, to prevent geoid Dict memory leaks

Parameters:

• xs –

• collection_id –

• obj_id –

Returns:

classmethod update_entity_dictionaries(updated_entity: nrel.hive.model.entity.Entity, entities: immutables.Map[nrel.hive.util.typealiases.EntityId, nrel.hive.model.entity.Entity], locations: immutables.Map[nrel.hive.util.typealiases.GeoId, FrozenSet[nrel.hive.util.typealiases.EntityId]], search: immutables.Map[nrel.hive.util.typealiases.GeoId, FrozenSet[nrel.hive.util.typealiases.EntityId]], sim_h3_search_resolution: int) → EntityUpdateResult

updates all dictionaries related to an entity

Parameters:

• updated_entity – an entity which itself should have an “id” and a “geoid” attribute

• entities – the dictionary containing Entities by EntityId

• locations – the finest-resolution geoindex of this entity type

• search – the upper-level resolution geoindex

• sim_h3_search_resolution – the h3 resolution of the search collection

Returns:

the updated dictionaries