Render table hints in generic SQL

Added :meth:`.Select.with_hint` output to the generic SQL string that is
produced when calling ``str()`` on a statement.  Previously, this clause
would be omitted under the assumption that it was dialect specific.
The hint text is presented within brackets to indicate the rendering
of such hints varies among backends.

Fixes: #5353
References: #4667
Change-Id: I01d97d6baa993e495519036ec7ecd5ae62856c16

diff --git a/doc/build/changelog/unreleased_13/5353.rst b/doc/build/changelog/unreleased_13/5353.rst
new file mode 100644 (file)
index 0000000..39a5ba4
--- /dev/null
+++ b/doc/build/changelog/unreleased_13/5353.rst
@@ -0,0 +1,10 @@
+.. change::
+    :tags: bug, sql
+    :tickets: 5353
+
+    Added :meth:`.Select.with_hint` output to the generic SQL string that is
+    produced when calling ``str()`` on a statement.  Previously, this clause
+    would be omitted under the assumption that it was dialect specific.
+    The hint text is presented within brackets to indicate the rendering
+    of such hints varies among backends.
+

diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index 8eae0ab7d5d1ca9f818fa3ce248edd5ee3600605..fc66ca5177f5ecd7ab5c43e09ea99d4fb32f9e06 100644 (file)
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -3491,6 +3491,9 @@ class StrSQLCompiler(SQLCompiler):
     def visit_empty_set_expr(self, type_):
         return "SELECT 1 WHERE 1!=1"
 
+    def get_from_hint_text(self, table, text):
+        return "[%s]" % text
+
 
 class DDLCompiler(Compiled):
     @util.memoized_property

diff --git a/test/sql/test_compiler.py b/test/sql/test_compiler.py
index efe4d08c53632cf6118e68acf29b65b915348a11..20f31ba1e2c7cec5a32cd45e3929be87b030680f 100644 (file)
--- a/test/sql/test_compiler.py
+++ b/test/sql/test_compiler.py
@@ -3886,6 +3886,41 @@ class StringifySpecialTest(fixtures.TestBase):
             "'%s'" % value,
         )
 
+    def test_with_hint_table(self):
+        stmt = (
+            select([table1])
+            .select_from(
+                table1.join(table2, table1.c.myid == table2.c.otherid)
+            )
+            .with_hint(table1, "use some_hint")
+        )
+
+        # note that some dialects instead use the "with_select_hint"
+        # hook to put the 'hint' up front
+        eq_ignore_whitespace(
+            str(stmt),
+            "SELECT mytable.myid, mytable.name, mytable.description "
+            "FROM mytable [use some_hint] "
+            "JOIN myothertable ON mytable.myid = myothertable.otherid",
+        )
+
+    def test_with_hint_statement(self):
+        stmt = (
+            select([table1])
+            .select_from(
+                table1.join(table2, table1.c.myid == table2.c.otherid)
+            )
+            .with_statement_hint("use some_hint")
+        )
+
+        eq_ignore_whitespace(
+            str(stmt),
+            "SELECT mytable.myid, mytable.name, mytable.description "
+            "FROM mytable "
+            "JOIN myothertable ON mytable.myid = myothertable.otherid "
+            "use some_hint",
+        )
+
 
 class KwargPropagationTest(fixtures.TestBase):
     @classmethod