krrood.entity_query_language.verbalization.navigation_path

Classes

RelationStep	The data a relational hop renders from — the related type (the relative clause's head
PathStep	One hop of a navigation chain — a display name and the source reference it links to.

Functions

build_path_parts(→ List[PathStep])

Convert a walked chain into PathStep hops.

Module Contents

class krrood.entity_query_language.verbalization.navigation_path.RelationStep

The data a relational hop renders from — the related type (the relative clause’s head noun), the verb split into participle + preposition (so the preposition pied-pipes before “which”), and the owner class (for the verb’s source link).

value_type: type | None

The hop’s value type — the head noun of the relative clause (“the Robot”).

owner_class: type

The attribute’s owner class — supplies the verb’s source link.

participle: str

The past-participle verb word(s) (“assigned”) — the “… is assigned” tail.

preposition: str

The trailing preposition (“to”) — pied-piped to “to which …”.

referent_id: uuid.UUID | None = None

The navigated value node’s id. The relative clause is a referring expression for that entity, so a repeat mention of the same navigation reduces to a bare “the <Type>” (coreference) rather than repeating the whole “the Robot to which it is assigned”; None disables it.

is_agentive: bool = False

True for an agentive relation (preposition “by”), read in the active voice (“the Person who owns a Book”) instead of the passive relative clause (“the Person by which a Book is owned”).

active_verb: str = ''

The active present verb (“owns”) used for the active-voice reading of an agentive relation; unused for a non-agentive relation.

class krrood.entity_query_language.verbalization.navigation_path.PathStep

One hop of a navigation chain — a display name and the source reference it links to.

Replaces a bare (name, source_reference) tuple so the two halves are named (.name / .source_reference) rather than positional.

name: str

The display text for this hop (e.g. "amount", "handle[0]", "()").

source_reference: krrood.entity_query_language.verbalization.fragments.source_reference.SourceReference | None = None

The attribute’s source reference, or None for composite / index / call hops.

relation: RelationStep | None = None

When set, this hop is a relation named as a verb (assigned_to) and renders as a relative clause “the <Type> which <owner> is <verb-phrase>” instead of the genitive “the <attr> of <owner>”; None for a plain noun hop.

is_scalar_value: bool = False

True when this hop’s value is an atomic scalar (a number / string / date), not an entity. A scalar leaf possessed by a plural subject distributes (“their salaries”); an entity owner of further structure does not (“the begin and end of their period”).

ordinal: str | None = None

The ordinal phrase (“first”, “last”) when this attribute hop selects a single indexed element of a collection: the collection noun singularizes and takes the ordinal (“the first task” rather than “the first of the tasks”); None for a whole-collection hop.

property is_plain_attribute: bool

Returns:

True when this hop is a plain genitive attribute — it links to a source

attribute and is not a relative-clause relation, so an integer index can fold its ordinal into it (“the first task”).

property is_relation: bool

Returns:

True when this hop renders as a relative clause rather than a genitive.

>>> from krrood.entity_query_language.core.expression_structure import walk_chain
>>> from krrood.entity_query_language.verbalization.relational_attributes import relational_verb
>>> chain, _ = walk_chain(variable(Mission, []).assigned_to)
>>> build_path_parts(chain, relational_verb)[0].is_relation
True
>>> build_path_parts(walk_chain(variable(Robot, []).battery)[0])[0].is_relation
False

krrood.entity_query_language.verbalization.navigation_path.build_path_parts(chain: List[krrood.entity_query_language.core.mapped_variable.MappedVariable], relation_verb: Callable[[str], krrood.entity_query_language.verbalization.relational_attributes.RelationVerb | None] | None = None) → List[PathStep]

Convert a walked chain into PathStep hops.

Hop rules:

• Attribute nodes appear as the attribute name, linked to their source reference. When relation_verb recognises the name as a verb relation (returns its split verb), the hop is flagged relational, so it renders as a relative clause instead of a genitive.

• An integer Index node folds its ordinal (0 → "first") into the collection attribute it subscripts, which singularizes: “the first task of …” rather than “the first of the tasks of …” or a raw subscript ("tasks[0]"). An index that does not follow a plain attribute (e.g. on a call result) stays a standalone ordinal hop. Non-integer keys keep the "[key]" bracket form.

• Call nodes appear as "()" with no source reference.

• FlatVariable nodes are skipped.

Parameters:

• chain – Innermost-first chain list (nearest the root first).

• relation_verb – Optional name → split-verb recogniser, injected so this module stays decoupled from the grammar’s recognizers; None disables relational rendering.

Returns:

Ordered list of PathStep, innermost hop first.

>>> from krrood.entity_query_language.core.expression_structure import walk_chain
>>> chain, _ = walk_chain(variable(BankTransaction, []).amount_details.amount)
>>> [step.name for step in build_path_parts(chain)]
['amount_details', 'amount']