sqlalchemy.orm.interfaces.PropComparator

class documentation

class PropComparator(SQLORMOperations[_T], Generic[_T], ColumnOperators): (source)

Known subclasses: sqlalchemy.ext.hybrid.Comparator, sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.descriptor_props.CompositeProperty.Comparator, sqlalchemy.orm.properties.ColumnProperty.Comparator, sqlalchemy.orm.properties.RelationshipProperty.Comparator

View In Hierarchy

Defines SQL operations for ORM mapped attributes. SQLAlchemy allows for operators to be redefined at both the Core and ORM level. :class:`.PropComparator` is the base class of operator redefinition for ORM-level operations, including those of :class:`.ColumnProperty`, :class:`.Relationship`, and :class:`.Composite`. User-defined subclasses of :class:`.PropComparator` may be created. The built-in Python comparison and math operator methods, such as :meth:`.operators.ColumnOperators.__eq__`, :meth:`.operators.ColumnOperators.__lt__`, and :meth:`.operators.ColumnOperators.__add__`, can be overridden to provide new operator behavior. The custom :class:`.PropComparator` is passed to the :class:`.MapperProperty` instance via the ``comparator_factory`` argument. In each case, the appropriate subclass of :class:`.PropComparator` should be used:: # definition of custom PropComparator subclasses from sqlalchemy.orm.properties import \ ColumnProperty,\ Composite,\ Relationship class MyColumnComparator(ColumnProperty.Comparator): def __eq__(self, other): return self.__clause_element__() == other class MyRelationshipComparator(Relationship.Comparator): def any(self, expression): "define the 'any' operation" # ... class MyCompositeComparator(Composite.Comparator): def __gt__(self, other): "redefine the 'greater than' operation" return sql.and_(*[a>b for a, b in zip(self.__clause_element__().clauses, other.__composite_values__())]) # application of custom PropComparator subclasses from sqlalchemy.orm import column_property, relationship, composite from sqlalchemy import Column, String class SomeMappedClass(Base): some_column = column_property(Column("some_column", String), comparator_factory=MyColumnComparator) some_relationship = relationship(SomeOtherClass, comparator_factory=MyRelationshipComparator) some_composite = composite( Column("a", String), Column("b", String), comparator_factory=MyCompositeComparator ) Note that for column-level operator redefinition, it's usually simpler to define the operators at the Core level, using the :attr:`.TypeEngine.comparator_factory` attribute. See :ref:`types_operators` for more detail. .. seealso:: :class:`.ColumnProperty.Comparator` :class:`.Relationship.Comparator` :class:`.Composite.Comparator` :class:`.ColumnOperators` :ref:`types_operators` :attr:`.TypeEngine.comparator_factory`

Method __clause_element__ Undocumented
Method __init__ Undocumented
Method adapt_to_entity Return a copy of this PropComparator which will use the given :class:`.AliasedInsp` to produce corresponding expressions.
Method and_ Add additional criteria to the ON clause that's represented by this relationship attribute.
Method any Return a SQL expression representing true if this element references a member which meets the given criterion.
Method has Return a SQL expression representing true if this element references a member which meets the given criterion.
Method of_type Redefine this object in terms of a polymorphic subclass, :func:`_orm.with_polymorphic` construct, or :func:`_orm.aliased` construct.
Method operate Operate on an argument.
Method reverse_operate Reverse operate on an argument.
Class Variable __slots__ Undocumented
Class Variable __visit_name__ Undocumented
Class Variable any_op Undocumented
Class Variable has_op Undocumented
Class Variable of_type_op Undocumented
Instance Variable prop Undocumented
Property adapter Produce a callable that adapts column expressions to suit an aliased version of this comparator.
Property info Undocumented
Property property Return the :class:`.MapperProperty` associated with this :class:`.PropComparator`.
Static Method _any_op Undocumented
Static Method _has_op Undocumented
Static Method _of_type_op Undocumented
Method _bulk_update_tuples Receive a SQL expression that represents a value in the SET clause of an UPDATE statement.
Method _criterion_exists Undocumented
Instance Variable _adapt_to_entity Undocumented
Instance Variable _parententity Undocumented
Property _parentmapper legacy; this is renamed to _parententity to be compatible with QueryableAttribute.

Inherited from SQLCoreOperations (via SQLORMOperations):

Method __add__ Implement the ``+`` operator.
Method __and__ Implement the ``&`` operator.
Method __contains__ Undocumented
Method __eq__ Implement the ``==`` operator.
Method __floordiv__ Implement the ``//`` operator.
Method __ge__ Implement the ``>=`` operator.
Method __getitem__ Implement the [] operator.
Method __gt__ Implement the ``>`` operator.
Method __invert__ Implement the ``~`` operator.
Method __le__ Implement the ``<=`` operator.
Method __lt__ Implement the ``<`` operator.
Method __mod__ Implement the ``%`` operator.
Method __mul__ Implement the ``*`` operator.
Method __ne__ Implement the ``!=`` operator.
Method __neg__ Implement the ``-`` operator.
Method __or__ Implement the ``|`` operator.
Method __radd__ Implement the ``+`` operator in reverse.
Method __rfloordiv__ Implement the ``//`` operator in reverse.
Method __rmod__ Implement the ``%`` operator in reverse.
Method __rmul__ Implement the ``*`` operator in reverse.
Method __rsub__ Implement the ``-`` operator in reverse.
Method __rtruediv__ Implement the ``/`` operator in reverse.
Method __sub__ Implement the ``-`` operator.
Method __truediv__ Implement the ``/`` operator.
Method all_ Produce an :func:`_expression.all_` clause against the parent object.
Method any_ Produce an :func:`_expression.any_` clause against the parent object.
Method asc Produce a :func:`_expression.asc` clause against the parent object.
Method between Produce a :func:`_expression.between` clause against the parent object, given the lower and upper range.
Method bool_op Return a custom boolean operator.
Method collate Produce a :func:`_expression.collate` clause against the parent object, given the collation string.
Method concat Implement the 'concat' operator.
Method contains Implement the 'contains' operator.
Method desc Produce a :func:`_expression.desc` clause against the parent object.
Method distinct Produce a :func:`_expression.distinct` clause against the parent object.
Method endswith Implement the 'endswith' operator.
Method ilike Implement the ``ilike`` operator, e.g. case insensitive LIKE.
Method in_ Implement the ``in`` operator.
Method is_ Implement the ``IS`` operator.
Method is_distinct_from Implement the ``IS DISTINCT FROM`` operator.
Method is_not Implement the ``IS NOT`` operator.
Method is_not_distinct_from Implement the ``IS NOT DISTINCT FROM`` operator.
Method isnot Undocumented
Method like Implement the ``like`` operator.
Method match Implements a database-specific 'match' operator.
Method not_ilike implement the ``NOT ILIKE`` operator.
Method not_in implement the ``NOT IN`` operator.
Method not_like implement the ``NOT LIKE`` operator.
Method notilike Undocumented
Method notin_ Undocumented
Method notlike Undocumented
Method nulls_first Produce a :func:`_expression.nulls_first` clause against the parent object.
Method nulls_last Produce a :func:`_expression.nulls_last` clause against the parent object.
Method nullsfirst Undocumented
Method nullslast Undocumented
Method op Produce a generic operator function.
Method regexp_match Implements a database-specific 'regexp match' operator.
Method regexp_replace Implements a database-specific 'regexp replace' operator.
Method startswith Implement the ``startswith`` operator.
Property _propagate_attrs Undocumented

Inherited from ColumnOperators (via SQLORMOperations, SQLCoreOperations):

Method __lshift__ implement the << operator.
Method __rshift__ implement the >> operator.
Method bitwise_and Produce a bitwise AND operation, typically via the ``&`` operator.
Method bitwise_lshift Produce a bitwise LSHIFT operation, typically via the ``<<`` operator.
Method bitwise_not Produce a bitwise NOT operation, typically via the ``~`` operator.
Method bitwise_or Produce a bitwise OR operation, typically via the ``|`` operator.
Method bitwise_rshift Produce a bitwise RSHIFT operation, typically via the ``>>`` operator.
Method bitwise_xor Produce a bitwise XOR operation, typically via the ``^`` operator, or ``#`` for PostgreSQL.
Method icontains Implement the ``icontains`` operator, e.g. case insensitive version of :meth:`.ColumnOperators.contains`.
Method iendswith Implement the ``iendswith`` operator, e.g. case insensitive version of :meth:`.ColumnOperators.endswith`.
Method isnot_distinct_from Undocumented
Method istartswith Implement the ``istartswith`` operator, e.g. case insensitive version of :meth:`.ColumnOperators.startswith`.
Class Variable timetuple Hack, allows datetime objects to be compared on the LHS.
Method _rconcat Implement an 'rconcat' operator.

Inherited from TypingOnly (via SQLORMOperations, SQLCoreOperations, ColumnOperators, Operators):

Method __init_subclass__ Undocumented
def __clause_element__(self) -> roles.ColumnsClauseRole: (source)
overridden in sqlalchemy.ext.hybrid.Comparator, sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.descriptor_props.CompositeProperty.Comparator, sqlalchemy.orm.properties.ColumnProperty.Comparator, sqlalchemy.orm.properties.RelationshipProperty.Comparator

Undocumented

def __init__(self, prop: MapperProperty[_T], parentmapper: _InternalEntityType[Any], adapt_to_entity: Optional[AliasedInsp[Any]] = None): (source)
overridden in sqlalchemy.ext.hybrid.Comparator, sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.properties.RelationshipProperty.Comparator

Undocumented

def adapt_to_entity(self, adapt_to_entity: AliasedInsp[Any]) -> PropComparator[_T]: (source)
overridden in sqlalchemy.ext.hybrid.Comparator, sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.properties.RelationshipProperty.Comparator

Return a copy of this PropComparator which will use the given :class:`.AliasedInsp` to produce corresponding expressions.

def and_(self, *criteria: _ColumnExpressionArgument[bool]) -> PropComparator[bool]: (source)
overrides sqlalchemy.orm.base.SQLORMOperations.and_
overridden in sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.properties.RelationshipProperty.Comparator

Add additional criteria to the ON clause that's represented by this relationship attribute. E.g.:: stmt = select(User).join( User.addresses.and_(Address.email_address != 'foo') ) stmt = select(User).options( joinedload(User.addresses.and_(Address.email_address != 'foo')) ) .. versionadded:: 1.4 .. seealso:: :ref:`orm_queryguide_join_on_augmented` :ref:`loader_option_criteria` :func:`.with_loader_criteria`

def any(self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any) -> ColumnElement[bool]: (source)
overrides sqlalchemy.orm.base.SQLORMOperations.any
overridden in sqlalchemy.orm.properties.RelationshipProperty.Comparator

Return a SQL expression representing true if this element references a member which meets the given criterion. The usual implementation of ``any()`` is :meth:`.Relationship.Comparator.any`. :param criterion: an optional ClauseElement formulated against the member class' table or attributes. :param \**kwargs: key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

def has(self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any) -> ColumnElement[bool]: (source)
overrides sqlalchemy.orm.base.SQLORMOperations.has
overridden in sqlalchemy.orm.properties.RelationshipProperty.Comparator

Return a SQL expression representing true if this element references a member which meets the given criterion. The usual implementation of ``has()`` is :meth:`.Relationship.Comparator.has`. :param criterion: an optional ClauseElement formulated against the member class' table or attributes. :param \**kwargs: key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

def of_type(self, class_: _EntityType[Any]) -> PropComparator[_T]: (source)
overrides sqlalchemy.orm.base.SQLORMOperations.of_type
overridden in sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.properties.RelationshipProperty.Comparator

Redefine this object in terms of a polymorphic subclass, :func:`_orm.with_polymorphic` construct, or :func:`_orm.aliased` construct. Returns a new PropComparator from which further criterion can be evaluated. e.g.:: query.join(Company.employees.of_type(Engineer)).\ filter(Engineer.name=='foo') :param \class_: a class or mapper indicating that criterion will be against this specific subclass. .. seealso:: :ref:`orm_queryguide_joining_relationships_aliased` - in the :ref:`queryguide_toplevel` :ref:`inheritance_of_type`

def operate(self, op: OperatorType, *other: Any, **kwargs: Any) -> ColumnElement[Any]: (source)
overrides sqlalchemy.sql.elements.SQLCoreOperations.operate
overridden in sqlalchemy.ext.hybrid.ExprComparator, sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.properties.ColumnProperty.Comparator

Operate on an argument. This is the lowest level of operation, raises :class:`NotImplementedError` by default. Overriding this on a subclass can allow common behavior to be applied to all operations. For example, overriding :class:`.ColumnOperators` to apply ``func.lower()`` to the left and right side:: class MyComparator(ColumnOperators): def operate(self, op, other, **kwargs): return op(func.lower(self), func.lower(other), **kwargs) :param op: Operator callable. :param \*other: the 'other' side of the operation. Will be a single scalar for most operations. :param \**kwargs: modifiers. These may be passed by special operators such as :meth:`ColumnOperators.contains`.

def reverse_operate(self, op: OperatorType, other: Any, **kwargs: Any) -> ColumnElement[Any]: (source)
overrides sqlalchemy.sql.elements.SQLCoreOperations.reverse_operate
overridden in sqlalchemy.ext.hybrid.ExprComparator, sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.properties.ColumnProperty.Comparator

Reverse operate on an argument. Usage is the same as :meth:`operate`.

__slots__: tuple[str, ...] = (source)
overrides sqlalchemy.orm.base.SQLORMOperations.__slots__
overridden in sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.properties.ColumnProperty.Comparator, sqlalchemy.orm.properties.RelationshipProperty.Comparator

Undocumented

__visit_name__: str = (source)
overridden in sqlalchemy.orm.attributes.QueryableAttribute

Undocumented

any_op = (source)

Undocumented

has_op = (source)

Undocumented

of_type_op = (source)

Undocumented

prop = (source)
overridden in sqlalchemy.orm.descriptor_props.CompositeProperty.Comparator, sqlalchemy.orm.properties.ColumnProperty.Comparator, sqlalchemy.orm.properties.RelationshipProperty.Comparator

Undocumented

@util.ro_non_memoized_property
adapter: Optional[_ORMAdapterProto] = (source)

Produce a callable that adapts column expressions to suit an aliased version of this comparator.

@util.ro_non_memoized_property
info: _InfoType = (source)
overridden in sqlalchemy.ext.hybrid.ExprComparator, sqlalchemy.orm.attributes.QueryableAttribute

Undocumented

@util.non_memoized_property
property: MapperProperty[_T] = (source)
overridden in sqlalchemy.ext.hybrid.Comparator

Return the :class:`.MapperProperty` associated with this :class:`.PropComparator`. Return values here will commonly be instances of :class:`.ColumnProperty` or :class:`.Relationship`.

@staticmethod
def _any_op(a: Any, b: Any, **kwargs: Any) -> Any: (source)

Undocumented

@staticmethod
def _has_op(left: Any, other: Any, **kwargs: Any) -> Any: (source)

Undocumented

@staticmethod
def _of_type_op(a: Any, class_: Any) -> Any: (source)

Undocumented

def _bulk_update_tuples(self, value: Any) -> Sequence[Tuple[_DMLColumnArgument, Any]]: (source)
overridden in sqlalchemy.ext.hybrid.ExprComparator, sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.descriptor_props.CompositeProperty.Comparator

Receive a SQL expression that represents a value in the SET clause of an UPDATE statement. Return a tuple that can be passed to a :class:`_expression.Update` construct.

def _criterion_exists(self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any) -> ColumnElement[Any]: (source)
overridden in sqlalchemy.orm.properties.RelationshipProperty.Comparator

Undocumented

_adapt_to_entity = (source)
overridden in sqlalchemy.orm.properties.RelationshipProperty.Comparator

Undocumented

_parententity = (source)
overridden in sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.properties.RelationshipProperty.Comparator

Undocumented

@util.ro_non_memoized_property
_parentmapper: Mapper[Any] = (source)

legacy; this is renamed to _parententity to be compatible with QueryableAttribute.