Enhance documentation for string compilation use cases

- Add a web link for UnsupportedCompilationError
- Add new section to errors.rst
- add more detail and cross-linking to the FAQ
- include security caveats for parameter rendering

Fixes: #4595
Change-Id: I31ea57c18d65770cd2a51276bbe2847a9eb72bba

1 files changed, 13 insertions, 3 deletions

diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index 15ddd7d6f..c7fe3dc50 100644
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -2717,10 +2717,20 @@ class SQLCompiler(Compiled):
 
 
 class StrSQLCompiler(SQLCompiler):
-    """"a compiler subclass with a few non-standard SQL features allowed.
+    """A :class:`.SQLCompiler` subclass which allows a small selection
+    of non-standard SQL features to render into a string value.
 
-    Used for stringification of SQL statements when a real dialect is not
-    available.
+    The :class:`.StrSQLCompiler` is invoked whenever a Core expression
+    element is directly stringified without calling upon the
+    :meth:`.ClauseElement.compile` method.   It can render a limited set
+    of non-standard SQL constructs to assist in basic stringification,
+    however for more substantial custom or dialect-specific SQL constructs,
+    it will be necessary to make use of :meth:`.ClauseElement.compile`
+    directly.
+
+    .. seealso::
+
+        :ref:`faq_sql_expression_string`
 
     """