- query.join() can now accept class-mapped attributes

as arguments, which can be used in place or in any
combination with strings.  In particular this allows
construction of joins to subclasses on a polymorphic
relation, i.e.
query(Company).join(['employees', Engineer.name]),
etc.

2 files changed, 36 insertions, 13 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index b3678f1aa..bec6f1c3e 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -24,6 +24,7 @@ from sqlalchemy.sql import expression, visitors, operators
 from sqlalchemy.orm import mapper, object_mapper
 from sqlalchemy.orm.mapper import _state_mapper
 from sqlalchemy.orm import util as mapperutil
+from sqlalchemy.orm import interfaces
 
 __all__ = ['Query', 'QueryContext']
 
@@ -422,7 +423,11 @@ class Query(object):
         mapper = start
         alias = self._aliases
         for key in util.to_list(keys):
-            prop = mapper.get_property(key, resolve_synonyms=True)
+            if isinstance(key, interfaces.PropComparator):
+                prop = key.property
+            else:
+                prop = mapper.get_property(key, resolve_synonyms=True)
+                
             if prop._is_self_referential() and not create_aliases:
                 raise exceptions.InvalidRequestError("Self-referential query on '%s' property requires create_aliases=True argument." % str(prop))
 
@@ -583,21 +588,39 @@ class Query(object):
         return q
 
     def join(self, prop, id=None, aliased=False, from_joinpoint=False):
-        """create a join of this ``Query`` object's criterion
-        to a relationship and return the newly resulting ``Query``.
-
-        'prop' may be a string property name or a list of string
-        property names.
+        """Create a join against this ``Query`` object's criterion
+        and apply generatively, retunring the newly resulting ``Query``.
+
+        'prop' may be one of:
+          * a string property name, i.e. "rooms"
+          * a class-mapped attribute, i.e. Houses.rooms
+          * a list containing a combination of any of the above.
+          
+        e.g.::
+        
+            session.query(Company).join('employees')
+            session.query(Company).join(['employees', 'tasks'])
+            session.query(Houses).join([Colonials.rooms, Room.closets])
+        
         """
 
         return self._join(prop, id=id, outerjoin=False, aliased=aliased, from_joinpoint=from_joinpoint)
 
     def outerjoin(self, prop, id=None, aliased=False, from_joinpoint=False):
-        """create a left outer join of this ``Query`` object's criterion
-        to a relationship and return the newly resulting ``Query``.
-
-        'prop' may be a string property name or a list of string
-        property names.
+        """Create a left outer join against this ``Query`` object's criterion
+        and apply generatively, retunring the newly resulting ``Query``.
+
+        'prop' may be one of:
+          * a string property name, i.e. "rooms"
+          * a class-mapped attribute, i.e. Houses.rooms
+          * a list containing a combination of any of the above.
+          
+        e.g.::
+        
+            session.query(Company).outerjoin('employees')
+            session.query(Company).outerjoin(['employees', 'tasks'])
+            session.query(Houses).outerjoin([Colonials.rooms, Room.closets])
+        
         """
 
         return self._join(prop, id=id, outerjoin=True, aliased=aliased, from_joinpoint=from_joinpoint)
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 187b38a2c..4eb555d4d 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -26,7 +26,7 @@ to stay the same in future releases.
 """
 
 import datetime, re
-from itertools import chain
+import itertools
 from sqlalchemy import util, exceptions
 from sqlalchemy.sql import operators, visitors
 from sqlalchemy import types as sqltypes
@@ -2349,7 +2349,7 @@ class Join(FromClause):
         return self.select(use_labels=True, correlate=False).alias(name)
 
     def _hide_froms(self):
-        return chain(*[x.left._get_from_objects() + x.right._get_from_objects() for x in self._cloned_set])
+        return itertools.chain(*[x.left._get_from_objects() + x.right._get_from_objects() for x in self._cloned_set])
     _hide_froms = property(_hide_froms)
 
     def _get_from_objects(self, **modifiers):