From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sun, 26 Jul 2015 20:09:25 +0000 (-0400)
Subject: - add an example of text.columns
X-Git-Tag: rel_1_1_0b1~84^2~70^2~160
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d73ffaafe656f3e623765b44a8121f1591c51275;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- add an example of text.columns
- correct the scalar() example output
---

diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index e3ce6adadf..2f904d828a 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -902,10 +902,9 @@ database results.  Here's a brief tour:
       {sql}>>> query.scalar() #doctest: +NORMALIZE_WHITESPACE
       SELECT users.id AS users_id
       FROM users
-      WHERE users.name LIKE ? ORDER BY users.id
-       LIMIT ? OFFSET ?
-      ('%ed', 1, 0)
-      {stop}7
+      WHERE users.name = ? ORDER BY users.id
+      ('ed',)
+      {stop}1
 
 .. _orm_tutorial_literal_sql:
 
@@ -982,11 +981,27 @@ completely "raw", using string names to identify desired columns:
     ('ed',)
     {stop}[(1, u'ed', 12)]
 
+The :func:`.text` construct also supports the :meth:`.TextClause.columns`
+method, which can be used to associate ORM-mapped columns explicitly.
+This is useful to make an explicit mapping of columns in the string
+statement to those that are mapped::
+
+.. sourcecode:: python+sql
+
+    >>> stmt = text("SELECT name, id FROM users where name=:name")
+    >>> stmt = stmt.columns(User.name, User.id)
+    {sql}>>> session.query(User).from_statement(stmt).params(name='ed').all()
+    SELECT name, id FROM users where name=?
+    ('ed',)
+    {stop}[<User(name='ed', fullname='Ed Jones', password='f8s7ccs')>]
+
+
 .. versionchanged:: 1.0.0
    The :class:`.Query` construct emits warnings when string SQL
    fragments are coerced to :func:`.text`, and :func:`.text` should
    be used explicitly.  See :ref:`migration_2992` for background.
 
+
 .. seealso::
 
     :ref:`sqlexpression_text` - Core description of textual segments.  The