Commits

Mike Bayer committed e39cac1

- start encouraging the use of text() for injection of string-based SQL
rather than straight strings. reference #2992

Comments (0)

Files changed (2)

doc/build/core/tutorial.rst

     ('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`
 .. 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

doc/build/orm/tutorial.rst

 -----------------
 
 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,
 
 .. 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,
 .. 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',)
 .. 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',)