type_bridge.typed.references

references

Owner-aware typed-query references backed by opaque native handles.

Selection

Bases: _ImmutableNativeValue, Generic[OutputT_co], ABC

Covariant output-only view of one native selection handle.

Predicate

Predicate()

Bases: _ImmutableNativeValue

Immutable boolean predicate whose referenced bindings remain native.

Source code in type_bridge/typed/references.py

def __init__(self) -> None:
    raise TypeError("Predicate values are created by bound reference operations")

and_

and_(other)

Return a persistent conjunction of this predicate and other.

Source code in type_bridge/typed/references.py

def and_(self, other: Predicate) -> Predicate:
    """Return a persistent conjunction of this predicate and ``other``."""
    return Predicate._from_native(self.__handle.and_(other.__handle))

or_

or_(other)

Return a persistent disjunction of this predicate and other.

Source code in type_bridge/typed/references.py

def or_(self, other: Predicate) -> Predicate:
    """Return a persistent disjunction of this predicate and ``other``."""
    return Predicate._from_native(self.__handle.or_(other.__handle))

not_

not_()

Return a persistent negation of this predicate.

Source code in type_bridge/typed/references.py

def not_(self) -> Predicate:
    """Return a persistent negation of this predicate."""
    return Predicate._from_native(self.__handle.not_())

QueryOrder

QueryOrder()

Bases: _ImmutableNativeValue

Opaque stable-order term created from an order-capable bound field.

Source code in type_bridge/typed/references.py

def __init__(self) -> None:
    raise TypeError("QueryOrder values are created by BoundField.asc/desc")

BoundField

BoundField()

Bases: _ImmutableNativeValue

Opaque field bound to one invariant native variable occurrence.

Source code in type_bridge/typed/references.py

def __init__(self) -> None:
    raise TypeError("BoundField values are created by BoundVar.field")

eq

eq(value)

Compare this field for equality with a typed literal or bound field.

Source code in type_bridge/typed/references.py

def eq(self, value: AttributeT | BoundField[AttributeT]) -> Predicate:
    """Compare this field for equality with a typed literal or bound field."""
    return self._compare("equal", value)

eq_field

eq_field(field)

Compare this field with another compatible bound field.

Source code in type_bridge/typed/references.py

def eq_field(self, field: BoundField[AttributeT]) -> Predicate:
    """Compare this field with another compatible bound field."""
    return self._compare("equal", field)

neq

neq(value)

Compare this field for inequality with a typed literal or bound field.

Source code in type_bridge/typed/references.py

def neq(self, value: AttributeT | BoundField[AttributeT]) -> Predicate:
    """Compare this field for inequality with a typed literal or bound field."""
    return self._compare("not_equal", value)

BoundRole

BoundRole()

Bases: _ImmutableNativeValue

Opaque relation role bound to one native relation variable.

Source code in type_bridge/typed/references.py

def __init__(self) -> None:
    raise TypeError("BoundRole values are created by BoundVar.role")

connects

connects(player)

Require this role to connect a compatible native bound variable.

Source code in type_bridge/typed/references.py

def connects(self, player: _PlayerBinding[PlayerT]) -> Predicate:
    """Require this role to connect a compatible native bound variable."""
    if not isinstance(player, BoundVar):
        raise TypeError("role players must be BoundVar values")
    return Predicate._from_native(self.__handle.connects(player._native_binding()))

is_

is_(player)

Require this role to be played by a compatible bound variable.

Source code in type_bridge/typed/references.py

def is_(self, player: _PlayerBinding[PlayerT]) -> Predicate:
    """Require this role to be played by a compatible bound variable."""
    return self.connects(player)

BoundVar

BoundVar()

Bases: Selection[ModelT], _PlayerBinding[ModelT]

Invariant model variable backed by one fresh native binding handle.

Source code in type_bridge/typed/references.py

def __init__(self) -> None:
    raise TypeError("BoundVar values are created by QuerySession.var")

field

field(reference: type[StringAttributeT]) -> _StringBoundField[StringAttributeT]

field(reference: type[NumericAttributeT]) -> _OrderedBoundField[NumericAttributeT]

field(reference: type[OrderedAttributeT]) -> _OrderedBoundField[OrderedAttributeT]

field(reference: type[AttributeT]) -> BoundField[AttributeT]

field(reference: StringFieldRef[StringAttributeT, ModelT]) -> _StringBoundField[StringAttributeT]

field(reference: NumericFieldRef[NumericAttributeT, ModelT]) -> _OrderedBoundField[NumericAttributeT]

field(reference: OrderedFieldRef[OrderedAttributeT, ModelT]) -> _OrderedBoundField[OrderedAttributeT]

field(reference: FieldRef[AttributeT, ModelT]) -> BoundField[AttributeT]

field(reference)

Bind an owned attribute class or legacy model field reference.

Source code in type_bridge/typed/references.py

def field(self, reference: Any) -> Any:
    """Bind an owned attribute class or legacy model field reference."""
    if isinstance(reference, type) and issubclass(reference, Attribute):
        field_name = self.__field_name_for_attribute(reference)
        handle = self.__handle.field(field_name)
        if issubclass(reference, String):
            return _StringBoundField._from_native(handle)
        if issubclass(reference, (NumericAttribute, Date, DateTime, DateTimeTZ)):
            return _OrderedBoundField._from_native(handle)
        return BoundField._from_native(handle)

    if not isinstance(reference, FieldRef):
        raise TypeError(
            "BoundVar.field requires an owned Attribute class or owner-aware FieldRef"
        )
    model_type_name = self.__stable_model_type_name()
    owner = _typed_query_field_reference_owner(reference)
    if owner is None:
        raise TypeError("BoundVar.field requires a FieldRef emitted by a model descriptor")
    owner_type, owner_type_name = owner
    if owner_type_name == model_type_name and owner_type is not self.__model:
        raise TypeError("BoundVar.field reference owner does not match the bound model")
    handle = self.__handle.field_owned_by(owner_type_name, reference.field_name)
    if isinstance(reference, StringFieldRef):
        return _StringBoundField._from_native(handle)
    if isinstance(reference, (NumericFieldRef, OrderedFieldRef)):
        return _OrderedBoundField._from_native(handle)
    return BoundField._from_native(handle)

__field_name_for_attribute

__field_name_for_attribute(attribute)

Resolve one exact attribute class through this binding's model owner.

Source code in type_bridge/typed/references.py

def __field_name_for_attribute(self, attribute: type[Attribute]) -> str:
    """Resolve one exact attribute class through this binding's model owner."""
    self.__stable_model_type_name()
    matches = [
        field_name
        for field_name, info in self.__model.get_all_attributes().items()
        if info.typ is attribute
    ]
    if not matches:
        raise TypeError(f"{self.__model.__name__} does not own attribute {attribute.__name__}")
    if len(matches) != 1:
        joined = ", ".join(sorted(matches))
        raise TypeError(
            f"{self.__model.__name__} owns attribute {attribute.__name__} through "
            f"multiple fields ({joined}); use the owner-aware model field reference"
        )
    return matches[0]

role

role(reference)

Bind one owner-aware relation role reference to this variable.

Source code in type_bridge/typed/references.py

def role(self, reference: RoleRef[PlayerT, ModelT]) -> BoundRole[PlayerT]:
    """Bind one owner-aware relation role reference to this variable."""
    if not isinstance(reference, RoleRef):
        raise TypeError("BoundVar.role requires an owner-aware RoleRef")
    model_type_name = self.__stable_model_type_name()
    owner = _typed_query_role_reference_owner(reference)
    if owner is None:
        raise TypeError("BoundVar.role requires a RoleRef emitted by a model descriptor")
    owner_type, owner_type_name = owner
    if owner_type_name == model_type_name and owner_type is not self.__model:
        raise TypeError("BoundVar.role reference owner does not match the bound model")
    return BoundRole._from_native(
        self.__handle.role_owned_by(owner_type_name, reference.role_name)
    )

collect

collect()

Return a persistent collected selection for this variable.

Source code in type_bridge/typed/references.py

def collect(self) -> Collected[ModelT]:
    """Return a persistent collected selection for this variable."""
    model_type_name = self.__stable_model_type_name()
    return Collected._from_native(self.__handle.collect(), self.__model, model_type_name)

Collected

Collected()

Bases: Selection[tuple[ModelT, ...]]

Persistent collected-output selection for one bound model variable.

Source code in type_bridge/typed/references.py

def __init__(self) -> None:
    raise TypeError("Collected values are created by BoundVar.collect")

distinct

distinct()

Return an identity-distinct persistent collection selection.

Source code in type_bridge/typed/references.py

def distinct(self) -> Collected[ModelT]:
    """Return an identity-distinct persistent collection selection."""
    return Collected._from_native(
        self.__handle.distinct(),
        self.__model,
        self.__model_type_name,
    )

order_by

order_by(order)

Append one native collection-member order term persistently.

Source code in type_bridge/typed/references.py

def order_by(self, order: QueryOrder) -> Collected[ModelT]:
    """Append one native collection-member order term persistently."""
    return Collected._from_native(
        self.__handle.order_by(order._native_order()),
        self.__model,
        self.__model_type_name,
    )