deprecated CompositeProperty 'comparator' which is now

named 'comparator_factory'.

diff --git a/doc/build/content/mappers.txt b/doc/build/content/mappers.txt
index 297a5167ef65f532969817e3134f153b638e777d..acf48bb17560ff11056922ac49d89061f0828120 100644 (file)
--- a/doc/build/content/mappers.txt
+++ b/doc/build/content/mappers.txt
@@ -289,23 +289,23 @@ We can now use the `Vertex` instances as well as querying as though the `start`
 
     v2 = session.query(Vertex).filter(Vertex.start == Point(3, 4))
 
-The "equals" comparison operation by default produces an AND of all corresponding columns equated to one another.  If you'd like to override this, or define the behavior of other SQL operators for your new type, the `composite()` function accepts an extension object of type `sqlalchemy.orm.PropComparator`:
+The "equals" comparison operation by default produces an AND of all corresponding columns equated to one another.  This can be changed using the `comparator_factory`, described in [advdatamapping_mapper_attributes_comparators](rel:advdatamapping_mapper_attributes_comparators)
 
     {python}
-    from sqlalchemy.orm import PropComparator
+    from sqlalchemy.orm.properties import CompositeProperty
     from sqlalchemy import sql
 
-    class PointComparator(PropComparator):
+    class PointComparator(CompositeProperty.Comparator):
         def __gt__(self, other):
             """define the 'greater than' operation"""
 
             return sql.and_(*[a>b for a, b in
-                              zip(self.prop.columns,
+                              zip(self.__clause_element__().clauses,
                                   other.__composite_values__())])
 
     maper(Vertex, vertices, properties={
-        'start': composite(Point, vertices.c.x1, vertices.c.y1, comparator=PointComparator),
-        'end': composite(Point, vertices.c.x2, vertices.c.y2, comparator=PointComparator)
+        'start': composite(Point, vertices.c.x1, vertices.c.y1, comparator_factory=PointComparator),
+        'end': composite(Point, vertices.c.x2, vertices.c.y2, comparator_factory=PointComparator)
     })
 
 #### Controlling Ordering {@name=orderby}

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index c9066fb6c7e64d1783ef66ea85a80d34a3de20a2..ad19d796964a50d8881c7f07a0be344019e3def1 100644 (file)
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -211,7 +211,7 @@ def relation(argument, secondary=None, **kwargs):
           used in place of a plain list for storing elements.
 
         comparator_factory
-          a class which extends sqlalchemy.orm.properties.RelationProperty.Comparator
+          a class which extends ``sqlalchemy.orm.properties.RelationProperty.Comparator``
           which provides custom SQL clause generation for comparison operations.
           
         extension
@@ -404,7 +404,7 @@ def column_property(*args, **kwargs):
           list of Column objects to be mapped.
 
       comparator_factory
-        a class which extends sqlalchemy.orm.properties.RelationProperty.Comparator
+        a class which extends ``sqlalchemy.orm.properties.ColumnProperty.Comparator``
         which provides custom SQL clause generation for comparison operations.
 
       group
@@ -485,9 +485,9 @@ def composite(class_, *cols, **kwargs):
       load immediately, and is instead loaded when the attribute is first
       accessed on an instance.  See also [sqlalchemy.orm#deferred()].
 
-    comparator
-      An optional instance of [sqlalchemy.orm#PropComparator] which provides
-      SQL expression generation functions for this composite type.
+    comparator_factory
+      a class which extends ``sqlalchemy.orm.properties.CompositeProperty.Comparator``
+      which provides custom SQL clause generation for comparison operations.
 
     extension
       an [sqlalchemy.orm.interfaces#AttributeExtension] instance, 

diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index 714b18047413ec83da0f159c995f176bf9a3bc10..6404b8349efca6238f2c28437e1e454150b661fc 100644 (file)
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -41,7 +41,7 @@ class ColumnProperty(StrategizedProperty):
         self.columns = [expression._labeled(c) for c in columns]
         self.group = kwargs.pop('group', None)
         self.deferred = kwargs.pop('deferred', False)
-        self.comparator_factory = kwargs.pop('comparator_factory', ColumnProperty.ColumnComparator)
+        self.comparator_factory = kwargs.pop('comparator_factory', self.__class__.Comparator)
         self.extension = kwargs.pop('extension', None)
         util.set_creation_order(self)
         if self.deferred:
@@ -108,10 +108,12 @@ class CompositeProperty(ColumnProperty):
     """subclasses ColumnProperty to provide composite type support."""
     
     def __init__(self, class_, *columns, **kwargs):
+        if 'comparator' in kwargs:
+            util.warn_deprecated("The 'comparator' argument to CompositeProperty is deprecated.  Use comparator_factory.")
+            kwargs['comparator_factory'] = kwargs['comparator']
         super(CompositeProperty, self).__init__(*columns, **kwargs)
         self._col_position_map = dict((c, i) for i, c in enumerate(columns))
         self.composite_class = class_
-        self.comparator_factory = kwargs.pop('comparator', CompositeProperty.Comparator)
         self.strategy_class = strategies.CompositeColumnLoader
 
     def do_init(self):