- comparator_factory is accepted by all MapperProperty constructors. [ticket:1149]

- added other unit tests as per [ticket:1149]
- rewrote most of the "joined table inheritance" documentation section, removed badly out of
date "polymorphic_fetch" and "select_table" arguments.
- "select_table" raises a deprecation warning.  converted unit tests to not use it.
- removed all references to "ORDER BY table.oid" from mapping docs.
- renamed PropertyLoader to RelationProperty.  Old symbol remains.
- renamed ColumnProperty.ColumnComparator to ColumnProperty.Comparator.  Old symbol remains.

3 files changed, 35 insertions, 18 deletions

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 4496c21e4..c9066fb6c 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -41,6 +41,7 @@ from sqlalchemy.orm.properties import (
      ColumnProperty,
      ComparableProperty,
      CompositeProperty,
+     RelationProperty,
      PropertyLoader,
      SynonymProperty,
      )
@@ -159,7 +160,7 @@ def relation(argument, secondary=None, **kwargs):
 
     This corresponds to a parent-child or associative table relationship.  The
     constructed class is an instance of
-    [sqlalchemy.orm.properties#PropertyLoader].
+    [sqlalchemy.orm.properties#RelationProperty].
 
       argument
           a class or Mapper instance, representing the target of the relation.
@@ -209,6 +210,10 @@ def relation(argument, secondary=None, **kwargs):
           a class or function that returns a new list-holding object. will be
           used in place of a plain list for storing elements.
 
+        comparator_factory
+          a class which extends sqlalchemy.orm.properties.RelationProperty.Comparator
+          which provides custom SQL clause generation for comparison operations.
+          
         extension
           an [sqlalchemy.orm.interfaces#AttributeExtension] instance, 
           or list of extensions, which will be prepended to the list of 
@@ -359,11 +364,11 @@ def relation(argument, secondary=None, **kwargs):
           use an alternative method.
 
     """
-    return PropertyLoader(argument, secondary=secondary, **kwargs)
+    return RelationProperty(argument, secondary=secondary, **kwargs)
 
 def dynamic_loader(argument, secondary=None, primaryjoin=None, secondaryjoin=None, 
     foreign_keys=None, backref=None, post_update=False, cascade=False, remote_side=None, enable_typechecks=True,
-    passive_deletes=False, order_by=None):
+    passive_deletes=False, order_by=None, comparator_factory=None):
     """Construct a dynamically-loading mapper property.
 
     This property is similar to relation(), except read operations return an
@@ -377,10 +382,10 @@ def dynamic_loader(argument, secondary=None, primaryjoin=None, secondaryjoin=Non
     """
     from sqlalchemy.orm.dynamic import DynaLoader
 
-    return PropertyLoader(argument, secondary=secondary, primaryjoin=primaryjoin,
+    return RelationProperty(argument, secondary=secondary, primaryjoin=primaryjoin,
             secondaryjoin=secondaryjoin, foreign_keys=foreign_keys, backref=backref,
             post_update=post_update, cascade=cascade, remote_side=remote_side, enable_typechecks=enable_typechecks,
-            passive_deletes=passive_deletes, order_by=order_by,
+            passive_deletes=passive_deletes, order_by=order_by, comparator_factory=comparator_factory,
             strategy_class=DynaLoader)
 
 def column_property(*args, **kwargs):
@@ -398,6 +403,10 @@ def column_property(*args, **kwargs):
       \*cols
           list of Column objects to be mapped.
 
+      comparator_factory
+        a class which extends sqlalchemy.orm.properties.RelationProperty.Comparator
+        which provides custom SQL clause generation for comparison operations.
+
       group
           a group name for this property when marked as deferred.
 
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index 37a431012..a6b49ab6b 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -139,6 +139,9 @@ class Mapper(object):
 
         self.select_table = select_table
         if select_table:
+            util.warn_deprecated('select_table option is deprecated.  Use with_polymorphic=("*", selectable) '
+                            'instead.')
+
             if with_polymorphic:
                 raise sa_exc.ArgumentError("select_table can't be used with "
                             "with_polymorphic (they define conflicting settings)")
diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index bd493aaf2..714b18047 100644
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -25,7 +25,7 @@ from sqlalchemy.orm.interfaces import (
     )
 
 __all__ = ('ColumnProperty', 'CompositeProperty', 'SynonymProperty',
-           'ComparableProperty', 'PropertyLoader', 'BackRef')
+           'ComparableProperty', 'RelationProperty', 'BackRef')
 
 
 class ColumnProperty(StrategizedProperty):
@@ -82,7 +82,7 @@ class ColumnProperty(StrategizedProperty):
     def get_col_value(self, column, value):
         return value
 
-    class ColumnComparator(PropComparator):
+    class Comparator(PropComparator):
         @util.memoized_instancemethod
         def __clause_element__(self):
             if self.adapter:
@@ -96,7 +96,9 @@ class ColumnProperty(StrategizedProperty):
         def reverse_operate(self, op, other, **kwargs):
             col = self.__clause_element__()
             return op(col._bind_param(other), col, **kwargs)
-
+    
+    ColumnComparator = Comparator
+    
     def __str__(self):
         return str(self.parent.class_.__name__) + "." + self.key
 
@@ -244,7 +246,7 @@ class ComparableProperty(MapperProperty):
         pass
 
 
-class PropertyLoader(StrategizedProperty):
+class RelationProperty(StrategizedProperty):
     """Describes an object property that holds a single item or list
     of items that correspond to a related database table.
     """
@@ -263,6 +265,7 @@ class PropertyLoader(StrategizedProperty):
         collection_class=None, passive_deletes=False,
         passive_updates=True, remote_side=None,
         enable_typechecks=True, join_depth=None,
+        comparator_factory=None,
         strategy_class=None, _local_remote_pairs=None):
 
         self.uselist = uselist
@@ -280,12 +283,13 @@ class PropertyLoader(StrategizedProperty):
         self.passive_updates = passive_updates
         self.remote_side = remote_side
         self.enable_typechecks = enable_typechecks
-        self.comparator = PropertyLoader.Comparator(self, None)
+        
         self.join_depth = join_depth
         self.local_remote_pairs = _local_remote_pairs
         self.extension = extension
         self.__join_cache = {}
-        self.comparator_factory = PropertyLoader.Comparator
+        self.comparator_factory = comparator_factory or RelationProperty.Comparator
+        self.comparator = self.comparator_factory(self, None)
         util.set_creation_order(self)
 
         if strategy_class:
@@ -337,7 +341,7 @@ class PropertyLoader(StrategizedProperty):
             on the local side of generated expressions.
 
             """
-            return PropertyLoader.Comparator(self.prop, self.mapper, getattr(self, '_of_type', None), adapter)
+            return self.__class__(self.prop, self.mapper, getattr(self, '_of_type', None), adapter)
             
         @property
         def parententity(self):
@@ -357,7 +361,7 @@ class PropertyLoader(StrategizedProperty):
             return op(self, *other, **kwargs)
 
         def of_type(self, cls):
-            return PropertyLoader.Comparator(self.prop, self.mapper, cls)
+            return RelationProperty.Comparator(self.prop, self.mapper, cls)
 
         def in_(self, other):
             raise NotImplementedError("in_() not yet supported for relations.  For a "
@@ -843,7 +847,7 @@ class PropertyLoader(StrategizedProperty):
                 "added to the primary mapper, i.e. the very first "
                 "mapper created for class '%s' " % (self.key, self.parent.class_.__name__, self.parent.class_.__name__))
 
-        super(PropertyLoader, self).do_init()
+        super(RelationProperty, self).do_init()
 
     def _refers_to_parent_table(self):
         return self.parent.mapped_table is self.target or self.parent.mapped_table is self.target
@@ -946,12 +950,13 @@ class PropertyLoader(StrategizedProperty):
         if not self.viewonly:
             self._dependency_processor.register_dependencies(uowcommit)
 
-log.class_logger(PropertyLoader)
+PropertyLoader = RelationProperty
+log.class_logger(RelationProperty)
 
 class BackRef(object):
-    """Attached to a PropertyLoader to indicate a complementary reverse relationship.
+    """Attached to a RelationProperty to indicate a complementary reverse relationship.
 
-    Can optionally create the complementing PropertyLoader if one does not exist already."""
+    Can optionally create the complementing RelationProperty if one does not exist already."""
 
     def __init__(self, key, _prop=None, **kwargs):
         self.key = key
@@ -982,7 +987,7 @@ class BackRef(object):
             self.kwargs.setdefault('viewonly', prop.viewonly)
             self.kwargs.setdefault('post_update', prop.post_update)
 
-            relation = PropertyLoader(parent, prop.secondary, pj, sj,
+            relation = RelationProperty(parent, prop.secondary, pj, sj,
                                       backref=BackRef(prop.key, _prop=prop),
                                       _is_backref=True,
                                       **self.kwargs)