deprecated CompositeProperty 'comparator' which is now

named 'comparator_factory'.

3 files changed, 15 insertions, 13 deletions

diff --git a/doc/build/content/mappers.txt b/doc/build/content/mappers.txt
index 297a5167e..acf48bb17 100644
--- 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 c9066fb6c..ad19d7969 100644
--- 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 714b18047..6404b8349 100644
--- 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):