type_bridge.fields.role

role

Role-player field references for type-safe query building.

This module provides field reference classes that enable type-safe filtering of role-player attributes in relations:

Employment.employee.age.gt(Age(30))
Employment.employer.name.contains(Name("Tech"))

These expressions return RolePlayerExpr instances that wrap the underlying comparison or string expressions with role context for proper TypeQL generation.

RolePlayerFieldRef

RolePlayerFieldRef(role_name, field_name, attr_type, player_types)

Field reference for role-player attributes.

Provides comparison methods that return RolePlayerExpr instead of regular ComparisonExpr, adding role context for proper TypeQL generation.

Example

Employment.employee.age # Returns RolePlayerNumericFieldRef[Age] Employment.employee.age.gt(Age(30)) # Returns RolePlayerExpr

Create a role-player field reference.

Parameters:

Name	Type	Description	Default
role_name	str	Name of the role (e.g., "employee")	required
field_name	str	Python field name on the player entity	required
attr_type	type[T]	Attribute type class	required
player_types	tuple[type[TypeDBType], ...]	Tuple of entity types that can play this role	required

Source code in type_bridge/fields/role.py

def __init__(
    self,
    role_name: str,
    field_name: str,
    attr_type: type[T],
    player_types: tuple[type[TypeDBType], ...],
):
    """Create a role-player field reference.

    Args:
        role_name: Name of the role (e.g., "employee")
        field_name: Python field name on the player entity
        attr_type: Attribute type class
        player_types: Tuple of entity types that can play this role
    """
    self.role_name = role_name
    self.field_name = field_name
    self.attr_type = attr_type
    self.player_types = player_types

lt

lt(value)

Create a less-than comparison expression.

Parameters:

Name	Type	Description	Default
value	T	Value to compare against	required

Returns:

Type	Description
RolePlayerExpr	RolePlayerExpr wrapping a less-than comparison

Source code in type_bridge/fields/role.py

def lt(self, value: T) -> RolePlayerExpr:
    """Create a less-than comparison expression.

    Args:
        value: Value to compare against

    Returns:
        RolePlayerExpr wrapping a less-than comparison
    """
    return self._wrap_expr(self.attr_type.lt(value))

gt

gt(value)

Create a greater-than comparison expression.

Parameters:

Name	Type	Description	Default
value	T	Value to compare against	required

Returns:

Type	Description
RolePlayerExpr	RolePlayerExpr wrapping a greater-than comparison

Source code in type_bridge/fields/role.py

def gt(self, value: T) -> RolePlayerExpr:
    """Create a greater-than comparison expression.

    Args:
        value: Value to compare against

    Returns:
        RolePlayerExpr wrapping a greater-than comparison
    """
    return self._wrap_expr(self.attr_type.gt(value))

lte

lte(value)

Create a less-than-or-equal comparison expression.

Parameters:

Name	Type	Description	Default
value	T	Value to compare against	required

Returns:

Type	Description
RolePlayerExpr	RolePlayerExpr wrapping a less-than-or-equal comparison

Source code in type_bridge/fields/role.py

def lte(self, value: T) -> RolePlayerExpr:
    """Create a less-than-or-equal comparison expression.

    Args:
        value: Value to compare against

    Returns:
        RolePlayerExpr wrapping a less-than-or-equal comparison
    """
    return self._wrap_expr(self.attr_type.lte(value))

gte

gte(value)

Create a greater-than-or-equal comparison expression.

Parameters:

Name	Type	Description	Default
value	T	Value to compare against	required

Returns:

Type	Description
RolePlayerExpr	RolePlayerExpr wrapping a greater-than-or-equal comparison

Source code in type_bridge/fields/role.py

def gte(self, value: T) -> RolePlayerExpr:
    """Create a greater-than-or-equal comparison expression.

    Args:
        value: Value to compare against

    Returns:
        RolePlayerExpr wrapping a greater-than-or-equal comparison
    """
    return self._wrap_expr(self.attr_type.gte(value))

eq

eq(value)

Create an equality comparison expression.

Parameters:

Name	Type	Description	Default
value	T	Value to compare against	required

Returns:

Type	Description
RolePlayerExpr	RolePlayerExpr wrapping an equality comparison

Source code in type_bridge/fields/role.py

def eq(self, value: T) -> RolePlayerExpr:
    """Create an equality comparison expression.

    Args:
        value: Value to compare against

    Returns:
        RolePlayerExpr wrapping an equality comparison
    """
    return self._wrap_expr(self.attr_type.eq(value))

neq

neq(value)

Create a not-equal comparison expression.

Parameters:

Name	Type	Description	Default
value	T	Value to compare against	required

Returns:

Type	Description
RolePlayerExpr	RolePlayerExpr wrapping a not-equal comparison

Source code in type_bridge/fields/role.py

def neq(self, value: T) -> RolePlayerExpr:
    """Create a not-equal comparison expression.

    Args:
        value: Value to compare against

    Returns:
        RolePlayerExpr wrapping a not-equal comparison
    """
    return self._wrap_expr(self.attr_type.neq(value))

RolePlayerStringFieldRef

RolePlayerStringFieldRef(role_name, field_name, attr_type, player_types)

Bases: RolePlayerFieldRef[T]

Role-player field reference for String attributes.

Provides additional string-specific operations like contains, like, regex, all wrapped in RolePlayerExpr for proper role context.

Example

Employment.employer.name # Returns RolePlayerStringFieldRef[Name] Employment.employer.name.contains(Name("Tech")) # Returns RolePlayerExpr

Source code in type_bridge/fields/role.py

def __init__(
    self,
    role_name: str,
    field_name: str,
    attr_type: type[T],
    player_types: tuple[type[TypeDBType], ...],
):
    """Create a role-player field reference.

    Args:
        role_name: Name of the role (e.g., "employee")
        field_name: Python field name on the player entity
        attr_type: Attribute type class
        player_types: Tuple of entity types that can play this role
    """
    self.role_name = role_name
    self.field_name = field_name
    self.attr_type = attr_type
    self.player_types = player_types

contains

contains(value)

Create a string contains expression.

Parameters:

Name	Type	Description	Default
value	T	Substring to search for	required

Returns:

Type	Description
RolePlayerExpr	RolePlayerExpr wrapping a contains expression

Source code in type_bridge/fields/role.py

def contains(self, value: T) -> RolePlayerExpr:
    """Create a string contains expression.

    Args:
        value: Substring to search for

    Returns:
        RolePlayerExpr wrapping a contains expression
    """
    return self._wrap_expr(self.attr_type.contains(value))

like

like(pattern)

Create a string pattern matching expression.

Parameters:

Name	Type	Description	Default
pattern	T	Pattern to match (SQL LIKE style)	required

Returns:

Type	Description
RolePlayerExpr	RolePlayerExpr wrapping a like expression

Source code in type_bridge/fields/role.py

def like(self, pattern: T) -> RolePlayerExpr:
    """Create a string pattern matching expression.

    Args:
        pattern: Pattern to match (SQL LIKE style)

    Returns:
        RolePlayerExpr wrapping a like expression
    """
    return self._wrap_expr(self.attr_type.like(pattern))

regex

regex(pattern)

Create a string regex expression.

Parameters:

Name	Type	Description	Default
pattern	T	Regex pattern to match	required

Returns:

Type	Description
RolePlayerExpr	RolePlayerExpr wrapping a regex expression

Source code in type_bridge/fields/role.py

def regex(self, pattern: T) -> RolePlayerExpr:
    """Create a string regex expression.

    Args:
        pattern: Regex pattern to match

    Returns:
        RolePlayerExpr wrapping a regex expression
    """
    return self._wrap_expr(self.attr_type.regex(pattern))

RolePlayerNumericFieldRef

RolePlayerNumericFieldRef(role_name, field_name, attr_type, player_types)

Bases: RolePlayerFieldRef[T]

Role-player field reference for numeric attributes.

Inherits comparison methods from RolePlayerFieldRef. Aggregation methods (sum, avg, etc.) are not supported for role-player fields as they require grouping context.

Example

Employment.employee.age # Returns RolePlayerNumericFieldRef[Age] Employment.employee.age.gt(Age(30)) # Returns RolePlayerExpr

Source code in type_bridge/fields/role.py

def __init__(
    self,
    role_name: str,
    field_name: str,
    attr_type: type[T],
    player_types: tuple[type[TypeDBType], ...],
):
    """Create a role-player field reference.

    Args:
        role_name: Name of the role (e.g., "employee")
        field_name: Python field name on the player entity
        attr_type: Attribute type class
        player_types: Tuple of entity types that can play this role
    """
    self.role_name = role_name
    self.field_name = field_name
    self.attr_type = attr_type
    self.player_types = player_types

RoleRef

RoleRef(role_name, player_types)

Reference to a role for type-safe attribute access.

Returned when accessing a Role descriptor from the Relation class level. Enables chained attribute access for building type-safe filter expressions.

Example

Employment.employee # Returns RoleRef[Person] Employment.employee.age # Returns RolePlayerNumericFieldRef[Age] Employment.employee.age.gt(Age(30)) # Returns RolePlayerExpr

For Role.multi() (polymorphic roles), attributes from all player types are available. If an attribute exists on at least one player type, it can be accessed.

Relations can also be role players

Permission.permitted_access # Returns RoleRef[Access] where Access is a Relation

Create a role reference.

Parameters:

Name	Type	Description	Default
role_name	str	Name of the role (e.g., "employee")	required
player_types	tuple[type[T], ...]	Tuple of types (Entity or Relation) that can play this role	required

Source code in type_bridge/fields/role.py

def __init__(
    self,
    role_name: str,
    player_types: tuple[type[T], ...],
):
    """Create a role reference.

    Args:
        role_name: Name of the role (e.g., "employee")
        player_types: Tuple of types (Entity or Relation) that can play this role
    """
    self.role_name = role_name
    self.player_types = player_types
    # Cache of collected attributes from all player types
    self._player_attrs: dict[str, tuple[type, Any]] | None = None

__getattr__

__getattr__(name)

Access role-player attribute for query building.

Parameters:

Name	Type	Description	Default
name	str	Attribute name to access	required

Returns:

Type	Description
RolePlayerFieldRef[Any]	Appropriate RolePlayerFieldRef subclass based on attribute type

Raises:

Type	Description
AttributeError	If attribute doesn't exist on any player type

Source code in type_bridge/fields/role.py

def __getattr__(self, name: str) -> RolePlayerFieldRef[Any]:
    """Access role-player attribute for query building.

    Args:
        name: Attribute name to access

    Returns:
        Appropriate RolePlayerFieldRef subclass based on attribute type

    Raises:
        AttributeError: If attribute doesn't exist on any player type
    """
    # Avoid infinite recursion for special attributes
    if name.startswith("_"):
        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")

    player_attrs = self._get_player_attrs()

    if name not in player_attrs:
        available = sorted(player_attrs.keys())
        raise AttributeError(
            f"Role '{self.role_name}' players do not have attribute '{name}'. "
            f"Available attributes: {available}"
        )

    attr_type, _attr_info = player_attrs[name]
    return self._make_field_ref(name, attr_type)

__dir__

__dir__()

Enable IDE autocompletion for available player attributes.

Returns:

Type	Description
list[str]	List of available attribute names from all player types

Source code in type_bridge/fields/role.py

def __dir__(self) -> list[str]:
    """Enable IDE autocompletion for available player attributes.

    Returns:
        List of available attribute names from all player types
    """
    return sorted(self._get_player_attrs().keys())