- changelog, improve docstring/test for #3217. fixes #3217

3 files changed, 26 insertions, 8 deletions

diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst
index d0d025011..4a350370f 100644
--- a/doc/build/changelog/changelog_10.rst
+++ b/doc/build/changelog/changelog_10.rst
@@ -22,6 +22,15 @@
     on compatibility concerns, see :doc:`/changelog/migration_10`.
 
     .. change::
+        :tags: feature, orm
+        :tickets: 3217
+
+        Added a parameter :paramref:`.Query.join.isouter` which is synonymous
+        with calling :meth:`.Query.outerjoin`; this flag is to provide a more
+        consistent interface compared to Core :meth:`.FromClause.join`.
+        Pull request courtesy Jonathan Vanasco.
+
+    .. change::
         :tags: bug, sql
         :tickets: 3243
 
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 884e04bbc..790686288 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1741,7 +1741,13 @@ class Query(object):
          and similar will adapt the incoming criterion to the target
          alias, until :meth:`~.Query.reset_joinpoint` is called.
         :param isouter=False: If True, the join used will be a left outer join,
-         just as if the ``outerjoin()`` method were called.
+         just as if the :meth:`.Query.outerjoin` method were called.  This
+         flag is here to maintain consistency with the same flag as accepted
+         by :meth:`.FromClause.join` and other Core constructs.
+
+
+         .. versionadded:: 1.0.0
+
         :param from_joinpoint=False: When using ``aliased=True``, a setting
          of True here will cause the join to be from the most recent
          joined target, rather than starting back from the original
diff --git a/test/orm/test_joins.py b/test/orm/test_joins.py
index 98888862f..979ab0518 100644
--- a/test/orm/test_joins.py
+++ b/test/orm/test_joins.py
@@ -430,6 +430,16 @@ class JoinTest(QueryTest, AssertsCompiledSQL):
             sess.query(literal_column('x'), User).join, Address
         )
 
+    def test_isouter_flag(self):
+        User = self.classes.User
+
+        self.assert_compile(
+            create_session().query(User).join('orders', isouter=True),
+            "SELECT users.id AS users_id, users.name AS users_name "
+            "FROM users LEFT OUTER JOIN orders ON users.id = orders.user_id"
+        )
+
+
     def test_multi_tuple_form(self):
         """test the 'tuple' form of join, now superseded
         by the two-element join() form.
@@ -724,13 +734,6 @@ class JoinTest(QueryTest, AssertsCompiledSQL):
                 filter_by(id=3).outerjoin('orders','address').filter_by(id=1).all()
         assert [User(id=7, name='jack')] == result
 
-    def test_overlapping_paths_join_isouter(self):
-        User = self.classes.User
-
-        result = create_session().query(User).join('orders', 'items', isouter=True).\
-                filter_by(id=3).join('orders','address', isouter=True).filter_by(id=1).all()
-        assert [User(id=7, name='jack')] == result
-
     def test_from_joinpoint(self):
         Item, User, Order = (self.classes.Item,
                                 self.classes.User,