EntityNavigator
Navigate the lineage graph of scenarios, resources, views and notes.
A navigator wraps a set of entities of one type and exposes traversals to their direct and transitive neighbors (next/previous), plus tag propagation over the same graph.
Two traversal flavors coexist and are intentionally separate:
get_next_entities_recursive/get_previous_entities_recursivecollect every reachable entity into a flatNavigableEntitySet(with depth info) and discard edge information. Use these for "what's impacted" queries.propagate_tags/delete_propagated_tagswalk the same graph but must preserve per-edge provenance: each propagated tag carries an origin (TagOrigin) describing the immediate upstream entity that caused it. Because the origin depends on the edge kind (e.g. resource->view vs. resource->resource), these methods cannot be expressed on top of the flat-set recursion without losing attribution.
Both flavors apply the same two performance rules: hoist
get_next_*()/get_previous_*() queries out of per-entity loops, and
skip already-visited entities so reconverging paths don't re-walk subgraphs.
Initialize self. See help(type(self)) for accurate signature.
UnionRemove previously propagated copies of tags from every reachable downstream entity.
Inverse of propagate_tags -- traverses the same graph with the same
per-edge origin attribution and deletes the matching tag entries.
See propagate_tags for why this cannot be expressed on top of
get_next_entities_recursive.
listdict[gws_core.entity_navigator.entity_navigator_type.NavigableEntity, gws_core.tag.entity_tag_list.EntityTagList] | Noneset[gws_core.entity_navigator.entity_navigator_type.NavigableEntity] | NoneReturn the wrapped entities as a set.
setReturn the wrapped entities as a list. Order is not guaranteed (the underlying storage is a set).
listReturn an arbitrary entity from the set, or None if empty.
Useful when the caller knows the navigator wraps a single entity.
OptionalReturn the direct downstream neighbors of the wrapped entities.
Only one hop is followed (no recursion). Entities of any type listed in
requested_entities are merged into a single NavigableEntitySet.
listNavigableEntitySetReturn every entity transitively reachable downstream.
Traverses the lineage graph breadth-first. Each entity is visited once,
annotated with its depth in the returned NavigableEntitySet. Use this
for impact analysis ("what entities would be affected"). Edge-level
provenance is not preserved -- if you need to know which immediate
upstream caused a given downstream to be reached, use propagate_tags
instead.
list[gws_core.entity_navigator.entity_navigator_type.NavigableEntityType] | Nonebool - FalseNavigableEntitySetReturn the direct downstream notes. Empty by default; overridden by subclasses whose entity type has a notes-edge in the lineage graph.
EntityNavigatorNoteReturn the direct downstream resources. Empty by default; overridden by subclasses.
EntityNavigatorResourceReturn the direct downstream scenarios. Empty by default; overridden by subclasses.
EntityNavigatorScenarioReturn the direct downstream views. Empty by default; overridden by subclasses.
EntityNavigatorViewReturn every entity transitively reachable upstream.
Mirror of get_next_entities_recursive but walks the lineage graph in
the opposite direction (towards ancestors).
list[gws_core.entity_navigator.entity_navigator_type.NavigableEntityType] | Nonebool - FalseNavigableEntitySetReturn the direct upstream notes. Empty by default; overridden by subclasses.
EntityNavigatorNoteReturn the direct upstream resources. Empty by default; overridden by subclasses.
EntityNavigatorResourceReturn the direct upstream scenarios. Empty by default; overridden by subclasses.
EntityNavigatorScenarioReturn the direct upstream views. Empty by default; overridden by subclasses.
EntityNavigatorViewReturn True if at least one entity is wrapped.
boolReturn True if any direct downstream neighbor exists.
list[gws_core.entity_navigator.entity_navigator_type.NavigableEntityType] | NoneboolReturn True if no entities are wrapped.
boolPropagate the given tags to every transitively reachable downstream entity.
Each propagated tag carries an origin (TagOrigin) describing the
immediate upstream entity that caused it -- this is why we cannot reuse
get_next_entities_recursive here: that method flattens the graph
and discards edge information, while propagation needs per-edge
attribution. The origin's type and id depend on the edge kind:
scenario->resource yields SCENARIO_PROPAGATED, resource->next-resource
yields TASK_PROPAGATED, resource->view yields RESOURCE_PROPAGATED,
view->note yields VIEW_PROPAGATED.
Performance: get_next_*() queries are hoisted out of the per-entity
loop, and visited tracks entities whose downstream has already been
walked so reconverging paths in the DAG don't re-walk subgraphs.
listdict[gws_core.entity_navigator.entity_navigator_type.NavigableEntity, gws_core.tag.entity_tag_list.EntityTagList] | Noneset[gws_core.entity_navigator.entity_navigator_type.NavigableEntity] | NoneBuild the appropriate concrete navigator for a single entity, by type and id.
Raises if the entity does not exist or if entity_type is unknown.
NavigableEntityTypestrEntityNavigator