Allow join() to pick the best candidate from multiple froms/entities

Refactored :meth:`.Query.join` to further clarify the individual components
of structuring the join. This refactor adds the ability for
:meth:`.Query.join` to determine the most appropriate "left" side of the
join when there is more than one element in the FROM list or the query is
against multiple entities.  In particular this targets the regression we
saw in :ticket:`4363` but is also of general use.   The codepaths within
:meth:`.Query.join` are now easier to follow and the error cases are
decided more specifically at an earlier point in the operation.

Fixes: #4365
Change-Id: I403f451243904a020ceab4c3f94bead550c7b2d5

1 files changed, 14 insertions, 0 deletions

diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index 64886b326..f64f152c4 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -987,6 +987,19 @@ class Join(FromClause):
             return and_(*crit)
 
     @classmethod
+    def _can_join(cls, left, right, consider_as_foreign_keys=None):
+        if isinstance(left, Join):
+            left_right = left.right
+        else:
+            left_right = None
+
+        constraints = cls._joincond_scan_left_right(
+            a=left, b=right, a_subset=left_right,
+            consider_as_foreign_keys=consider_as_foreign_keys)
+
+        return bool(constraints)
+
+    @classmethod
     def _joincond_scan_left_right(
             cls, a, a_subset, b, consider_as_foreign_keys):
         constraints = collections.defaultdict(list)
@@ -1059,6 +1072,7 @@ class Join(FromClause):
                 "Please specify the 'onclause' of this "
                 "join explicitly." % (a.description, b.description))
 
+
     def select(self, whereclause=None, **kwargs):
         r"""Create a :class:`.Select` from this :class:`.Join`.