sqlalchemy.orm.interfaces.PropComparator

class documentation

class PropComparator(operators.ColumnOperators):

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

View In Hierarchy

Defines SQL operators for .MapperProperty objects.

SQLAlchemy allows for operators to be redefined at both the Core and ORM level. .PropComparator is the base class of operator redefinition for ORM-level operations, including those of .ColumnProperty, .RelationshipProperty, and .CompositeProperty.

Note

With the advent of Hybrid properties introduced in SQLAlchemy 0.7, as well as Core-level operator redefinition in SQLAlchemy 0.8, the use case for user-defined .PropComparator instances is extremely rare. See :ref:`hybrids_toplevel` as well as :ref:`types_operators`.

User-defined subclasses of .PropComparator may be created. The built-in Python comparison and math operator methods, such as .operators.ColumnOperators.__eq__, .operators.ColumnOperators.__lt__, and .operators.ColumnOperators.__add__, can be overridden to provide new operator behavior. The custom .PropComparator is passed to the .MapperProperty instance via the comparator_factory argument. In each case, the appropriate subclass of .PropComparator should be used:

# definition of custom PropComparator subclasses

from sqlalchemy.orm.properties import \
                        ColumnProperty,\
                        CompositeProperty,\
                        RelationshipProperty

class MyColumnComparator(ColumnProperty.Comparator):
    def __eq__(self, other):
        return self.__clause_element__() == other

class MyRelationshipComparator(RelationshipProperty.Comparator):
    def any(self, expression):
        "define the 'any' operation"
        # ...

class MyCompositeComparator(CompositeProperty.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 .TypeEngine.comparator_factory attribute. See :ref:`types_operators` for more detail.

See Also

.ColumnProperty.Comparator

.RelationshipProperty.Comparator

.CompositeProperty.Comparator

.ColumnOperators

:ref:`types_operators`

.TypeEngine.comparator_factory

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

Inherited from ColumnOperators:

Method	`__add__`	Implement the `+` operator.
Method	`__contains__`	Undocumented
Method	`__div__`	Implement the `/` operator.
Method	`__eq__`	Implement the `==` operator.
Method	`__ge__`	Implement the `>=` operator.
Method	`__getitem__`	Implement the [] operator.
Method	`__gt__`	Implement the `>` operator.
Method	`__le__`	Implement the `<=` operator.
Method	`__lshift__`	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	`__radd__`	Implement the `+` operator in reverse.
Method	`__rdiv__`	Implement the `/` operator in reverse.
Method	`__rmod__`	Implement the `%` operator in reverse.
Method	`__rmul__`	Implement the `*` operator in reverse.
Method	`__rshift__`	implement the >> operator.
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 `_expression.all_` clause against the parent object.
Method	`any_`	Produce an `_expression.any_` clause against the parent object.
Method	`asc`	Produce a `_expression.asc` clause against the parent object.
Method	`between`	Produce a `_expression.between` clause against the parent object, given the lower and upper range.
Method	`collate`	Produce a `_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 `_expression.desc` clause against the parent object.
Method	`distinct`	Produce a `_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	`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	`nulls_first`	Produce a `_expression.nulls_first` clause against the parent object.
Method	`nulls_last`	Produce a `_expression.nulls_last` clause against the parent object.
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.
Class Variable	`timetuple`	Hack, allows datetime objects to be compared on the LHS.

Inherited from Operators (via ColumnOperators):

Method	`__and__`	Implement the `&` operator.
Method	`__invert__`	Implement the `~` operator.
Method	`__or__`	Implement the `\|` operator.
Method	`bool_op`	Return a custom boolean operator.
Method	`op`	Produce a generic operator function.
Method	`operate`	Operate on an argument.
Method	`reverse_operate`	Reverse operate on an argument.

@staticmethod
def any_op(a, b, **kwargs):

Undocumented

@staticmethod
def has_op(a, b, **kwargs):

Undocumented

@staticmethod
def of_type_op(a, class_):

Undocumented

def __clause_element__(self):

overridden in sqlalchemy.ext.hybrid.Comparator, sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.properties.CompositeProperty.Comparator, sqlalchemy.orm.properties.RelationshipProperty.Comparator

Undocumented

def __init__(self, prop, parentmapper, adapt_to_entity=None):

overridden in sqlalchemy.ext.hybrid.Comparator, sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.orm.properties.RelationshipProperty.Comparator

Undocumented

def _bulk_update_tuples(self, value):

overridden in sqlalchemy.orm.attributes.QueryableAttribute, sqlalchemy.ext.hybrid.ExprComparator, sqlalchemy.orm.properties.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 _expression.Update construct.

def adapt_to_entity(self, adapt_to_entity):

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 .AliasedInsp to produce corresponding expressions.

def and_(self, *criteria):

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'))
)

New in version 1.4.

Parameters
criterion	an optional ClauseElement formulated against the member class' table or attributes.
**kwargs	key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

Parameters
criterion	an optional ClauseElement formulated against the member class' table or attributes.
**kwargs	key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

Parameters
class_	a class or mapper indicating that criterion will be against this specific subclass.