selectresults docs

1 files changed, 20 insertions, 1 deletions

diff --git a/lib/sqlalchemy/ext/selectresults.py b/lib/sqlalchemy/ext/selectresults.py
index 5ba9153dd..17e92ef32 100644
--- a/lib/sqlalchemy/ext/selectresults.py
+++ b/lib/sqlalchemy/ext/selectresults.py
@@ -1,9 +1,10 @@
 import sqlalchemy.sql as sql
-
 import sqlalchemy.orm as orm
 
 
 class SelectResultsExt(orm.MapperExtension):
+    """a MapperExtension that provides SelectResults functionality for the 
+    results of query.select_by() and query.select()"""
     def select_by(self, query, *args, **params):
         return SelectResults(query, query.join_by(*args, **params))
     def select(self, query, arg=None, **kwargs):
@@ -13,47 +14,65 @@ class SelectResultsExt(orm.MapperExtension):
             return SelectResults(query, arg, ops=kwargs)
 
 class SelectResults(object):
+    """Builds a query one component at a time via separate method calls, 
+    each call transforming the previous SelectResults instance into a new SelectResults 
+    instance with further limiting criterion added. When interpreted
+    in an iterator context (such as via calling list(selectresults)), executes the query."""
+    
     def __init__(self, query, clause=None, ops={}):
+        """constructs a new SelectResults using the given Query object and optional WHERE 
+        clause.  ops is an optional dictionary of bind parameter values."""
         self._query = query
         self._clause = clause
         self._ops = {}
         self._ops.update(ops)
 
     def count(self):
+        """executes the SQL count() function against the SelectResults criterion."""
         return self._query.count(self._clause)
     
     def min(self, col):
+        """executes the SQL min() function against the given column"""
         return sql.select([sql.func.min(col)], self._clause, **self._ops).scalar()
 
     def max(self, col):
+        """executes the SQL max() function against the given column"""
         return sql.select([sql.func.max(col)], self._clause, **self._ops).scalar()
 
     def sum(self, col):
+        """executes the SQL sum() function against the given column"""
         return sql.select([sql.func.sum(col)], self._clause, **self._ops).scalar()
 
     def avg(self, col):
+        """executes the SQL avg() function against the given column"""
         return sql.select([sql.func.avg(col)], self._clause, **self._ops).scalar()
 
     def clone(self):
+        """creates a copy of this SelectResults."""
         return SelectResults(self._query, self._clause, self._ops.copy())
         
     def filter(self, clause):
+        """applies an additional WHERE clause against the query."""
         new = self.clone()
         new._clause = sql.and_(self._clause, clause)
         return new
 
     def order_by(self, order_by):
+        """applies an ORDER BY to the query."""
         new = self.clone()
         new._ops['order_by'] = order_by
         return new
 
     def limit(self, limit):
+        """applies a LIMIT to the query."""
         return self[:limit]
 
     def offset(self, offset):
+        """applies an OFFSET to the query."""
         return self[offset:]
 
     def list(self):
+        """returns the results represented by this SelectResults as a list.  this results in an execution of the underlying query."""
         return list(self)
         
     def __getitem__(self, item):