added query.subquery() as shorthand for query.statement.alias()

diff --git a/doc/build/content/ormtutorial.txt b/doc/build/content/ormtutorial.txt
index f784d57cf65109cb64619141e8a227bf0dd6dc35..efbe4c951882c30e8f6791d5f8bb5a184aae2bfd 100644 (file)
--- a/doc/build/content/ormtutorial.txt
+++ b/doc/build/content/ormtutorial.txt
@@ -674,11 +674,11 @@ Using the `Query`, we build a statement like this from the inside out.  The `sta
     
     {python}
     >>> from sqlalchemy.sql import func
-    >>> stmt = session.query(Address.user_id, func.count('*').label('address_count')).group_by(Address.user_id).statement.alias()
+    >>> stmt = session.query(Address.user_id, func.count('*').label('address_count')).group_by(Address.user_id).subquery()
     
-The `func` keyword generates SQL functions, and the `alias()` method on `Select` (the return value of `query.statement`) creates a SQL alias, in this case an anonymous one which will have a generated name.
+The `func` keyword generates SQL functions, and the `subquery()` method on `Query` produces a SQL expression construct representing a SELECT statement embedded within an alias (it's actually shorthand for `query.statement.alias()`).
 
-Once we have our statement, it behaves like a `Table` construct, which we created for `users` at the top of this tutorial.  The columns on the statement are accessible through an attribute called `c`:
+Once we have our statement, it behaves like a `Table` construct, such as the one we created for `users` at the start of this tutorial.  The columns on the statement are accessible through an attribute called `c`:
 
     {python}
     {sql}>>> for u, count in session.query(User, stmt.c.address_count).outerjoin((stmt, User.id==stmt.c.user_id)): # doctest: +NORMALIZE_WHITESPACE

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index a5230277163d989b0f3ba3333be36e8af8354fd3..e39287b7706d90ec4c8a27f63dc70f40f6b19691 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -307,6 +307,11 @@ class Query(object):
         return self._compile_context(labels=self._with_labels).statement
     statement = property(statement)
 
+    def subquery(self):
+        """return the full SELECT statement represented by this Query, embedded within an Alias."""
+        
+        return self.statement.alias()
+        
     def with_labels(self):
         """Apply column labels to the return value of Query.statement.