type_bridge.fields.base

base

Field reference system for type-safe query building.

This module provides field descriptors and references that enable type-safe query expressions like Person.age.gt(Age(30)).

FieldRef

FieldRef(field_name, attr_type, entity_type)

Type-safe reference to an entity field.

Returned when accessing entity class attributes (e.g., Person.age). Provides query methods like .gt(), .lt(), etc. that return typed expressions.

Create a field reference.

Parameters:

Name	Type	Description	Default
field_name	str	Python field name	required
attr_type	type[T]	Attribute type class	required
entity_type	Any	Entity type that owns this field	required

Source code in type_bridge/fields/base.py

def __init__(self, field_name: str, attr_type: type[T], entity_type: Any):
    """Create a field reference.

    Args:
        field_name: Python field name
        attr_type: Attribute type class
        entity_type: Entity type that owns this field
    """
    self.field_name = field_name
    self.attr_type = attr_type
    self.entity_type: Any = entity_type

lt

lt(value)

Create a less-than comparison expression.

Parameters:

Name	Type	Description	Default
value	T	Value to compare against	required

Returns:

Type	Description
ComparisonExpr[T]	ComparisonExpr for this field < value

Source code in type_bridge/fields/base.py

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

    Args:
        value: Value to compare against

    Returns:
        ComparisonExpr for this field < value
    """
    # Delegate to attribute class method
    return 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
ComparisonExpr[T]	ComparisonExpr for this field > value

Source code in type_bridge/fields/base.py

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

    Args:
        value: Value to compare against

    Returns:
        ComparisonExpr for this field > value
    """
    # Delegate to attribute class method
    return 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
ComparisonExpr[T]	ComparisonExpr for this field <= value

Source code in type_bridge/fields/base.py

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

    Args:
        value: Value to compare against

    Returns:
        ComparisonExpr for this field <= value
    """
    # Delegate to attribute class method
    return 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
ComparisonExpr[T]	ComparisonExpr for this field >= value

Source code in type_bridge/fields/base.py

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

    Args:
        value: Value to compare against

    Returns:
        ComparisonExpr for this field >= value
    """
    # Delegate to attribute class method
    return 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
ComparisonExpr[T]	ComparisonExpr for this field == value

Source code in type_bridge/fields/base.py

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

    Args:
        value: Value to compare against

    Returns:
        ComparisonExpr for this field == value
    """
    # Delegate to attribute class method
    return 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
ComparisonExpr[T]	ComparisonExpr for this field != value

Source code in type_bridge/fields/base.py

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

    Args:
        value: Value to compare against

    Returns:
        ComparisonExpr for this field != value
    """
    # Delegate to attribute class method
    return self.attr_type.neq(value)

StringFieldRef

StringFieldRef(field_name, attr_type, entity_type)

Bases: FieldRef[T]

Field reference for String attribute types.

Provides additional string-specific operations like contains, like, regex.

Source code in type_bridge/fields/base.py

def __init__(self, field_name: str, attr_type: type[T], entity_type: Any):
    """Create a field reference.

    Args:
        field_name: Python field name
        attr_type: Attribute type class
        entity_type: Entity type that owns this field
    """
    self.field_name = field_name
    self.attr_type = attr_type
    self.entity_type: Any = entity_type

contains

contains(value)

Create a string contains expression.

Parameters:

Name	Type	Description	Default
value	T	Substring to search for	required

Returns:

Type	Description
StringExpr[T]	StringExpr for this field contains value

Source code in type_bridge/fields/base.py

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

    Args:
        value: Substring to search for

    Returns:
        StringExpr for this field contains value
    """
    # Delegate to attribute class method
    return self.attr_type.contains(value)

like

like(pattern)

Create a string pattern matching expression (regex).

Parameters:

Name	Type	Description	Default
pattern	T	Regex pattern to match	required

Returns:

Type	Description
StringExpr[T]	StringExpr for this field like pattern

Source code in type_bridge/fields/base.py

def like(self, pattern: T) -> "StringExpr[T]":
    """Create a string pattern matching expression (regex).

    Args:
        pattern: Regex pattern to match

    Returns:
        StringExpr for this field like pattern
    """
    # Delegate to attribute class method
    return self.attr_type.like(pattern)

regex

regex(pattern)

Create a string regex expression (alias for like).

Parameters:

Name	Type	Description	Default
pattern	T	Regex pattern to match	required

Returns:

Type	Description
StringExpr[T]	StringExpr for this field matching pattern

Source code in type_bridge/fields/base.py

def regex(self, pattern: T) -> "StringExpr[T]":
    """Create a string regex expression (alias for like).

    Args:
        pattern: Regex pattern to match

    Returns:
        StringExpr for this field matching pattern
    """
    # Delegate to attribute class method
    return self.attr_type.regex(pattern)

NumericFieldRef

NumericFieldRef(field_name, attr_type, entity_type)

Bases: FieldRef[T]

Field reference for numeric attribute types.

Provides additional numeric-specific operations like sum, avg, max, min.

Source code in type_bridge/fields/base.py

def __init__(self, field_name: str, attr_type: type[T], entity_type: Any):
    """Create a field reference.

    Args:
        field_name: Python field name
        attr_type: Attribute type class
        entity_type: Entity type that owns this field
    """
    self.field_name = field_name
    self.attr_type = attr_type
    self.entity_type: Any = entity_type

sum

sum()

Create a sum aggregation expression.

Returns:

Type	Description
AggregateExpr[T]	AggregateExpr for sum of this field

Source code in type_bridge/fields/base.py

def sum(self) -> "AggregateExpr[T]":
    """Create a sum aggregation expression.

    Returns:
        AggregateExpr for sum of this field
    """
    from type_bridge.expressions import AggregateExpr

    return AggregateExpr(attr_type=self.attr_type, function="sum", field_name=self.field_name)

avg

avg()

Create an average (mean) aggregation expression.

Returns:

Type	Description
AggregateExpr[T]	AggregateExpr for average/mean of this field

Source code in type_bridge/fields/base.py

def avg(self) -> "AggregateExpr[T]":
    """Create an average (mean) aggregation expression.

    Returns:
        AggregateExpr for average/mean of this field
    """
    from type_bridge.expressions import AggregateExpr

    return AggregateExpr(attr_type=self.attr_type, function="mean", field_name=self.field_name)

max

max()

Create a maximum aggregation expression.

Returns:

Type	Description
AggregateExpr[T]	AggregateExpr for maximum of this field

Source code in type_bridge/fields/base.py

def max(self) -> "AggregateExpr[T]":
    """Create a maximum aggregation expression.

    Returns:
        AggregateExpr for maximum of this field
    """
    from type_bridge.expressions import AggregateExpr

    return AggregateExpr(attr_type=self.attr_type, function="max", field_name=self.field_name)

min

min()

Create a minimum aggregation expression.

Returns:

Type	Description
AggregateExpr[T]	AggregateExpr for minimum of this field

Source code in type_bridge/fields/base.py

def min(self) -> "AggregateExpr[T]":
    """Create a minimum aggregation expression.

    Returns:
        AggregateExpr for minimum of this field
    """
    from type_bridge.expressions import AggregateExpr

    return AggregateExpr(attr_type=self.attr_type, function="min", field_name=self.field_name)

median

median()

Create a median aggregation expression.

Returns:

Type	Description
AggregateExpr[T]	AggregateExpr for median of this field

Source code in type_bridge/fields/base.py

def median(self) -> "AggregateExpr[T]":
    """Create a median aggregation expression.

    Returns:
        AggregateExpr for median of this field
    """
    from type_bridge.expressions import AggregateExpr

    return AggregateExpr(
        attr_type=self.attr_type, function="median", field_name=self.field_name
    )

std

std()

Create a standard deviation aggregation expression.

Returns:

Type	Description
AggregateExpr[T]	AggregateExpr for standard deviation of this field

Source code in type_bridge/fields/base.py

def std(self) -> "AggregateExpr[T]":
    """Create a standard deviation aggregation expression.

    Returns:
        AggregateExpr for standard deviation of this field
    """
    from type_bridge.expressions import AggregateExpr

    return AggregateExpr(attr_type=self.attr_type, function="std", field_name=self.field_name)

FieldDescriptor

FieldDescriptor(field_name, attr_type)

Descriptor for entity fields that supports dual behavior: - Class-level access: Returns FieldRef[T] for query building - Instance-level access: Returns T (the attribute value)

Create a field descriptor.

Parameters:

Name	Type	Description	Default
field_name	str	Python field name	required
attr_type	type[T]	Attribute type class	required

Source code in type_bridge/fields/base.py

def __init__(self, field_name: str, attr_type: type[T]):
    """Create a field descriptor.

    Args:
        field_name: Python field name
        attr_type: Attribute type class
    """
    self.field_name = field_name
    self.attr_type = attr_type

__get__

__get__(instance: None, owner: Any) -> FieldRef[T]

__get__(instance: Entity, owner: Any) -> T | None

__get__(instance, owner)

Get field value or field reference.

Parameters:

Name	Type	Description	Default
instance	Entity | None	Entity instance (None for class-level access)	required
owner	Any	Entity class	required

Returns:

Type	Description
FieldRef[T] | T | None	FieldRef[T] for class-level access, T | None for instance-level access

Source code in type_bridge/fields/base.py

def __get__(self, instance: "Entity | None", owner: Any) -> "FieldRef[T] | T | None":
    """Get field value or field reference.

    Args:
        instance: Entity instance (None for class-level access)
        owner: Entity class

    Returns:
        FieldRef[T] for class-level access, T | None for instance-level access
    """
    if instance is None:
        # Class-level access: return FieldRef for query building
        return self._make_field_ref(owner)
    # Instance-level access: return attribute value from Pydantic model
    # Pydantic stores field values in instance.__dict__
    return instance.__dict__.get(self.field_name)

__set__

__set__(instance, value)

Set field value on instance.

Parameters:

Name	Type	Description	Default
instance	Entity	Entity instance	required
value	T	Attribute value to set	required

Source code in type_bridge/fields/base.py

def __set__(self, instance: "Entity", value: T) -> None:
    """Set field value on instance.

    Args:
        instance: Entity instance
        value: Attribute value to set
    """
    # Store directly in instance __dict__
    # Note: We don't call validate_assignment() here because:
    # 1. The model_validator _wrap_raw_values already handles attribute wrapping
    # 2. Calling validate_assignment triggers the model validator which would
    #    call object.__setattr__ and trigger this __set__ again (infinite recursion)
    # Cast needed because pyright sees __dict__ as potentially MappingProxyType
    inst_dict = cast(dict[str, Any], instance.__dict__)
    inst_dict[self.field_name] = value