- start encouraging the use of text() for injection of string-based SQL

rather than straight strings.  reference #2992

2 files changed, 18 insertions, 15 deletions

diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index 6c6905b22..e5af58c88 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -778,8 +778,9 @@ feeding in the bind parameters to the :meth:`~.Connection.execute` method:
     ('m', 'z', '%@aol.com', '%@msn.com')
     {stop}[(u'Wendy Williams, wendy@aol.com',)]
 
-To gain a "hybrid" approach, the :func:`.select` construct accepts strings for most
-of its arguments. Below we combine the usage of strings with our constructed
+To gain a "hybrid" approach, the :func:`.select` construct accepts
+:func:`~.expression.text` constructs for most of its arguments.
+Below we combine the usage of :func:`~.expression.text` with our constructed
 :func:`.select` object, by using the :func:`.select` object to structure the
 statement, and strings to provide all the content within the structure. For
 this example, SQLAlchemy is not given any :class:`~sqlalchemy.schema.Column`
@@ -791,15 +792,15 @@ to be placed within the FROM clause:
 .. sourcecode:: pycon+sql
 
     >>> s = select([
-    ...            "users.fullname || ', ' || addresses.email_address AS title"
+    ...            text("users.fullname || ', ' || addresses.email_address AS title")
     ...          ]).\
     ...           where(
     ...              and_(
-    ...                 "users.id = addresses.user_id",
-    ...                 "users.name BETWEEN 'm' AND 'z'",
-    ...                 "(addresses.email_address LIKE :x OR addresses.email_address LIKE :y)"
+    ...                 text("users.id = addresses.user_id"),
+    ...                 text("users.name BETWEEN 'm' AND 'z'"),
+    ...                 text("(addresses.email_address LIKE :x OR addresses.email_address LIKE :y)")
     ...             )
-    ...           ).select_from('users, addresses')
+    ...           ).select_from(text('users, addresses'))
     {sql}>>> conn.execute(s, x='%@aol.com', y='%@msn.com').fetchall() #doctest: +NORMALIZE_WHITESPACE
     SELECT users.fullname || ', ' || addresses.email_address AS title
     FROM users, addresses
diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index f90dc48d2..fda9115b0 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -913,16 +913,18 @@ Using Literal SQL
 -----------------
 
 Literal strings can be used flexibly with
-:class:`~sqlalchemy.orm.query.Query`. Most methods accept strings in addition
-to SQLAlchemy clause constructs. For example,
+:class:`~sqlalchemy.orm.query.Query`, by specifying their use
+with the :func:`~.expression.text` construct, which is accepted
+by most applicable methods.  For example,
 :meth:`~sqlalchemy.orm.query.Query.filter()` and
 :meth:`~sqlalchemy.orm.query.Query.order_by()`:
 
 .. sourcecode:: python+sql
 
+    >>> from sqlalchemy import text
     {sql}>>> for user in session.query(User).\
-    ...             filter("id<224").\
-    ...             order_by("id").all(): #doctest: +NORMALIZE_WHITESPACE
+    ...             filter(text("id<224")).\
+    ...             order_by(text("id")).all(): #doctest: +NORMALIZE_WHITESPACE
     ...     print user.name
     SELECT users.id AS users_id,
             users.name AS users_name,
@@ -942,7 +944,7 @@ method:
 
 .. sourcecode:: python+sql
 
-    {sql}>>> session.query(User).filter("id<:value and name=:name").\
+    {sql}>>> session.query(User).filter(text("id<:value and name=:name")).\
     ...     params(value=224, name='fred').order_by(User.id).one() # doctest: +NORMALIZE_WHITESPACE
     SELECT users.id AS users_id,
             users.name AS users_name,
@@ -961,7 +963,7 @@ mapper (below illustrated using an asterisk):
 .. sourcecode:: python+sql
 
     {sql}>>> session.query(User).from_statement(
-    ...                     "SELECT * FROM users where name=:name").\
+    ...                     text("SELECT * FROM users where name=:name")).\
     ...                     params(name='ed').all()
     SELECT * FROM users where name=?
     ('ed',)
@@ -973,8 +975,8 @@ completely "raw", using string names to identify desired columns:
 .. sourcecode:: python+sql
 
     {sql}>>> session.query("id", "name", "thenumber12").\
-    ...         from_statement("SELECT id, name, 12 as "
-    ...                 "thenumber12 FROM users where name=:name").\
+    ...         from_statement(text("SELECT id, name, 12 as "
+    ...                 "thenumber12 FROM users where name=:name")).\
     ...                 params(name='ed').all()
     SELECT id, name, 12 as thenumber12 FROM users where name=?
     ('ed',)