Provide a more detailed error message for Query.join()

An :class:`.ArgumentError` with more detail is now raised if the target
parameter for :meth:`_query.Query.join` is set to an unmapped object.
Prior to this change a less detailed ``AttributeError`` was raised.
Pull request courtesy Ramon Williams.

Fixes: #4428
Closes: #5452
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5452
Pull-request-sha: b148df547037e9a254fe331eff8e922c78426261

Change-Id: I873453d1fdb651178216aac698baac63ae5a94e8

1 files changed, 39 insertions, 1 deletions

diff --git a/test/orm/test_joins.py b/test/orm/test_joins.py
index 4ffa5fb9e..8225214f6 100644
--- a/test/orm/test_joins.py
+++ b/test/orm/test_joins.py
@@ -2220,17 +2220,55 @@ class JoinTest(QueryTest, AssertsCompiledSQL):
             ._compile_context,
         )
 
-    def test_on_clause_no_right_side(self):
+    def test_on_clause_no_right_side_one(self):
         User = self.classes.User
         Address = self.classes.Address
         sess = create_session()
 
+        # coercions does not catch this due to the
+        # legacy=True flag for JoinTargetRole
         assert_raises_message(
             sa_exc.ArgumentError,
             "Expected mapped entity or selectable/table as join target",
             sess.query(User).join(User.id == Address.user_id)._compile_context,
         )
 
+    def test_on_clause_no_right_side_one_future(self):
+        User = self.classes.User
+        Address = self.classes.Address
+
+        # future mode can raise a more specific error at the coercions level
+        assert_raises_message(
+            sa_exc.ArgumentError,
+            "Join target, typically a FROM expression, "
+            "or ORM relationship attribute expected",
+            select(User).join,
+            User.id == Address.user_id,
+        )
+
+    def test_on_clause_no_right_side_two(self):
+        User = self.classes.User
+        Address = self.classes.Address
+        sess = create_session()
+
+        assert_raises_message(
+            sa_exc.ArgumentError,
+            "Join target Address.user_id does not refer to a mapped entity",
+            sess.query(User).join(Address.user_id)._compile_context,
+        )
+
+    def test_on_clause_no_right_side_two_future(self):
+        User = self.classes.User
+        Address = self.classes.Address
+
+        stmt = select(User).join(Address.user_id)
+
+        assert_raises_message(
+            sa_exc.ArgumentError,
+            "Join target Address.user_id does not refer to a mapped entity",
+            stmt.compile,
+        )
+
     def test_select_from(self):
         """Test that the left edge of the join can be set reliably with
         select_from()."""