Reword implicit left join error; ensure deterministic FROM for columns

Adjusted the error message emitted by :meth:`.Query.join` when a left hand
side can't be located that the :meth:`.Query.select_from` method is the
best way to resolve the issue.  Also, within the 1.3 series, used a
deterministic ordering when determining the FROM clause from a given column
entity passed to :class:`.Query` so that the same expression is determined
each time.

Fixes: #5194
Change-Id: I2e4065fd31e98c57edf2f11d5e831be44d2c1ea2

diff --git a/doc/build/changelog/unreleased_13/5194.rst b/doc/build/changelog/unreleased_13/5194.rst
new file mode 100644 (file)
index 0000000..7047fb3
--- /dev/null
+++ b/doc/build/changelog/unreleased_13/5194.rst
@@ -0,0 +1,11 @@
+.. change::
+    :tags: bug, orm
+    :tickets: 5194
+
+    Adjusted the error message emitted by :meth:`.Query.join` when a left hand
+    side can't be located that the :meth:`.Query.select_from` method is the
+    best way to resolve the issue.  Also, within the 1.3 series, used a
+    deterministic ordering when determining the FROM clause from a given column
+    entity passed to :class:`.Query` so that the same expression is determined
+    each time.
+

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 796ebe3ac4edce750dacbcbab65ec4b780c6172f..fe1ea9bfcdd668ba4d0e48bce96eb5cbea1e2857 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -2530,14 +2530,18 @@ class Query(Generative):
                 raise sa_exc.InvalidRequestError(
                     "Can't determine which FROM clause to join "
                     "from, there are multiple FROMS which can "
-                    "join to this entity. Try adding an explicit ON clause "
-                    "to help resolve the ambiguity."
+                    "join to this entity. Please use the .select_from() "
+                    "method to establish an explicit left side, as well as "
+                    "providing an explcit ON clause if not present already to "
+                    "help resolve the ambiguity."
                 )
             else:
                 raise sa_exc.InvalidRequestError(
-                    "Don't know how to join to %s; please use "
-                    "an ON clause to more clearly establish the left "
-                    "side of this join" % (right,)
+                    "Don't know how to join to %r. "
+                    "Please use the .select_from() "
+                    "method to establish an explicit left side, as well as "
+                    "providing an explcit ON clause if not present already to "
+                    "help resolve the ambiguity." % (right,)
                 )
 
         elif self._entities:
@@ -2572,14 +2576,18 @@ class Query(Generative):
                 raise sa_exc.InvalidRequestError(
                     "Can't determine which FROM clause to join "
                     "from, there are multiple FROMS which can "
-                    "join to this entity. Try adding an explicit ON clause "
-                    "to help resolve the ambiguity."
+                    "join to this entity. Please use the .select_from() "
+                    "method to establish an explicit left side, as well as "
+                    "providing an explcit ON clause if not present already to "
+                    "help resolve the ambiguity."
                 )
             else:
                 raise sa_exc.InvalidRequestError(
-                    "Don't know how to join to %s; please use "
-                    "an ON clause to more clearly establish the left "
-                    "side of this join" % (right,)
+                    "Don't know how to join to %r. "
+                    "Please use the .select_from() "
+                    "method to establish an explicit left side, as well as "
+                    "providing an explcit ON clause if not present already to "
+                    "help resolve the ambiguity." % (right,)
                 )
         else:
             raise sa_exc.InvalidRequestError(

diff --git a/test/orm/test_joins.py b/test/orm/test_joins.py
index 1243c7f19432a86dbbda9b056c0c243c1b278a25..2cd30d88d751fe3a321ff501f6d4b8bb05c60903 100644 (file)
--- a/test/orm/test_joins.py
+++ b/test/orm/test_joins.py
@@ -1338,9 +1338,9 @@ class JoinTest(QueryTest, AssertsCompiledSQL):
 
         assert_raises_message(
             sa.exc.InvalidRequestError,
-            "Don't know how to join to .*Item.*; "
-            "please use an ON clause to more clearly establish the "
-            "left side of this join",
+            "Don't know how to join to .*Item.*. "
+            r"Please use the .select_from\(\) "
+            "method to establish an explicit left side, as well as",
             q.join,
             Item,
         )
@@ -1353,9 +1353,9 @@ class JoinTest(QueryTest, AssertsCompiledSQL):
 
         assert_raises_message(
             sa.exc.InvalidRequestError,
-            "Don't know how to join to .*Item.*; "
-            "please use an ON clause to more clearly establish the "
-            "left side of this join",
+            "Don't know how to join to .*Item.*. "
+            r"Please use the .select_from\(\) "
+            "method to establish an explicit left side, as well as",
             q.join,
             Item,
         )
@@ -1375,9 +1375,9 @@ class JoinTest(QueryTest, AssertsCompiledSQL):
 
         assert_raises_message(
             sa.exc.InvalidRequestError,
-            "Don't know how to join to .*Item.*; "
-            "please use an ON clause to more clearly establish the "
-            "left side of this join",
+            "Don't know how to join to .*Item.*. "
+            r"Please use the .select_from\(\) "
+            "method to establish an explicit left side, as well as",
             q.join,
             Item,
         )
@@ -1473,7 +1473,8 @@ class JoinTest(QueryTest, AssertsCompiledSQL):
             sa.exc.InvalidRequestError,
             "Can't determine which FROM clause to join from, there are "
             "multiple FROMS which can join to this entity. "
-            "Try adding an explicit ON clause to help resolve the ambiguity.",
+            r"Please use the .select_from\(\) "
+            "method to establish an explicit left side, as well as",
             q.join,
             a1,
         )
@@ -1529,7 +1530,8 @@ class JoinTest(QueryTest, AssertsCompiledSQL):
             sa.exc.InvalidRequestError,
             "Can't determine which FROM clause to join from, there are "
             "multiple FROMS which can join to this entity. "
-            "Try adding an explicit ON clause to help resolve the ambiguity.",
+            r"Please use the .select_from\(\) "
+            "method to establish an explicit left side, as well as",
             q.join,
             a1,
         )
@@ -1580,7 +1582,8 @@ class JoinTest(QueryTest, AssertsCompiledSQL):
             sa.exc.InvalidRequestError,
             "Can't determine which FROM clause to join from, there are "
             "multiple FROMS which can join to this entity. "
-            "Try adding an explicit ON clause to help resolve the ambiguity.",
+            r"Please use the .select_from\(\) "
+            "method to establish an explicit left side, as well as",
             q.outerjoin,
             a1,
         )
@@ -2368,14 +2371,18 @@ class JoinTest(QueryTest, AssertsCompiledSQL):
 
         assert_raises_message(
             sa_exc.InvalidRequestError,
-            "Don't know how to join to .*User.* please use an ON clause to ",
+            "Don't know how to join to .*User.*. "
+            r"Please use the .select_from\(\) "
+            "method to establish an explicit left side, as well as",
             sess.query(users.c.id).join,
             User,
         )
 
         assert_raises_message(
             sa_exc.InvalidRequestError,
-            "Don't know how to join to .*User.* please use an ON clause to ",
+            "Don't know how to join to .*User.* "
+            r"Please use the .select_from\(\) "
+            "method to establish an explicit left side, as well as",
             sess.query(users.c.id).select_from(users).join,
             User,
         )