From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 29 Dec 2008 20:25:11 +0000 (+0000)
Subject: - added another usage recipe for contains_eager()
X-Git-Tag: rel_0_5_0~54
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=f9adad3acce8a219393f6997e77be8c44f05f0e4;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- added another usage recipe for contains_eager()
- some typos
---

diff --git a/doc/build/mappers.rst b/doc/build/mappers.rst
index 80fe8045a2..bc0d59e31b 100644
--- a/doc/build/mappers.rst
+++ b/doc/build/mappers.rst
@@ -1564,7 +1564,7 @@ It works just as well with an inline ``Query.join()`` or ``Query.outerjoin()``::
 
     session.query(User).outerjoin(User.addresses).options(contains_eager(User.addresses)).all()
 
-If the "eager" portion of the statement is "aliased", the ``alias`` keyword argument to ``contains_eager()`` may be used to indicate it.  This is a string alias name or reference to an actual ``Alias`` object:
+If the "eager" portion of the statement is "aliased", the ``alias`` keyword argument to ``contains_eager()`` may be used to indicate it.  This is a string alias name or reference to an actual ``Alias`` (or other selectable) object:
 
 .. sourcecode:: python+sql
 
@@ -1572,7 +1572,9 @@ If the "eager" portion of the statement is "aliased", the ``alias`` keyword argu
     adalias = aliased(Address)
 
     # construct a Query object which expects the "addresses" results
-    query = session.query(User).outerjoin((adalias, User.addresses)).options(contains_eager(User.addresses, alias=adalias))
+    query = session.query(User).\
+        outerjoin((adalias, User.addresses)).\
+        options(contains_eager(User.addresses, alias=adalias))
 
     # get results normally
     {sql}r = query.all()
@@ -1580,6 +1582,22 @@ If the "eager" portion of the statement is "aliased", the ``alias`` keyword argu
     adalias.user_id AS adalias_user_id, adalias.email_address AS adalias_email_address, (...other columns...)
     FROM users LEFT OUTER JOIN email_addresses AS email_addresses_1 ON users.user_id = email_addresses_1.user_id
 
+The ``alias`` argument is used only as a source of columns to match up to the result set.  You can use it even to match up the result to arbitrary label names in a string SQL statement, by passing a selectable() which links those labels to the mapped ``Table``::
+
+    # label the columns of the addresses table
+    eager_columns = select([
+                        addresses.c.address_id.label('a1'), 
+                        addresses.c.email_address.label('a2'), 
+                        addresses.c.user_id.label('a3')])
+    
+    # select from a raw SQL statement which uses those label names for the
+    # addresses table.  contains_eager() matches them up.
+    query = session.query(User).\
+        from_statement("select users.*, addresses.address_id as a1, "
+                "addresses.email_address as a2, addresses.user_id as a3 "
+                "from users left outer join addresses on users.user_id=addresses.user_id").\
+        options(contains_eager(User.addresses, alias=eager_columns))
+
 The path given as the argument to ``contains_eager()`` needs to be a full path from the starting entity.  For example if we were loading ``Users->orders->Order->items->Item``, the string version would look like::
 
     query(User).options(contains_eager('orders', 'items'))
diff --git a/lib/sqlalchemy/databases/mssql.py b/lib/sqlalchemy/databases/mssql.py
index 4d2176f854..95be55e7f6 100644
--- a/lib/sqlalchemy/databases/mssql.py
+++ b/lib/sqlalchemy/databases/mssql.py
@@ -96,7 +96,7 @@ arguments on the URL, or as keyword argument to
 
 * *auto_identity_insert* - enables support for IDENTITY inserts by
   automatically turning IDENTITY INSERT ON and OFF as required.
-  Defaults to ``True`.
+  Defaults to ``True``.
 
 * *query_timeout* - allows you to override the default query timeout.
   Defaults to ``None``. This is only supported on pymssql.
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 3be8dac392..b44ec25d5d 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -742,7 +742,7 @@ class Session(object):
           Optional, a ``mapper`` or mapped class
 
         \**kw
-          Additional keyword arguments are sent to :method:`get_bind()`
+          Additional keyword arguments are sent to :meth:`get_bind()`
           which locates a connectable to use for the execution.
           Subclasses of :class:`Session` may override this.